BioStar X introduces a powerful new capability that allows external systems to insert event logs directly into the BioStar X server. This feature enables access events to be sent directgly to BioStar X without database-level integration. 

To support this feature, external events must be linked to a Virtual Device—a logical device record created within BioStar X to represent the originating device.

Important:
The BioStar X Event Log API License is required to use this feature.

Overview of the Feature Workflow

Importing external event logs into BioStar X involves two main API operations:

  1. Create a Virtual Device

  2. Import Events Associated With the Virtual Device

This article explains both steps in detail.

1. Creating a Virtual Device

Before importing any external events, you must first define a virtual device that will serve as the source of those events.

Endpoint

POST /api/v2/virtual_devices

Example Request Body

{ 
 "VirtualDevice": { 
   "id": 100001,
   "name": "Virtual Device 100001",
      "description": "Virtual device for mobile punch import", 
   "device_group_id": { 
      "id": 1 
   }
  }
}

Field Requirements

FieldDescriptionRequired
idUnique identifier for the virtual device. Must be between 100001–999999, and cannot duplicate any existing device ID or device name.Yes
nameName of the virtual device.Yes
descriptionOptional description for your reference.No
device_group_idDevice group to which this virtual device belongs.Yes

Once the virtual device is successfully created, it can be used as the event source for all imported event logs.

2. Importing Events

BioStar X allows batch import of two specific event types generated by a virtual device:

  • 4088 — Access Granted

  • 6400 — Access Denied

Endpoint

POST /api/events/import

Example Request Body

{ 
 "packet_device_id": 100001, 
 "is_virtual_device": true,
  "events": [ 
    { 
      "dev_id": 100001, 
      "evt": 6400,
           "datetime": "2025-10-30T15:12:00Z",
           "user_id": "2" 
    }, 
    { 
     "dev_id": 100001, 
     "evt": 6400, 
     "datetime": "2025-10-30T15:13:01Z", 
     "user_id": "2", 
     "tna_key": "1"
       }
  ]
}

Field Requirements

FieldDescriptionRequired
packet_device_idID of the virtual device. Must match all events[].dev_id values.Yes
is_virtual_deviceMust be set to true for event imports.Yes
eventsArray of event objects to import.Yes

Within each event object

FieldDescriptionRequired
dev_idID of the virtual device. Must match packet_device_id.Yes
evtEvent type (4088 for Access Granted, 6400 for Access Denied).Yes
datetimeTimestamp in UTC.Yes
user_idUser ID associated with the event.Yes
tna_keyOptional transaction key or reference identifier.No

Viewing Imported Event Logs

After completing the import, you can retrieve and verify the event logs via:

/api/events/search

For detailed guidance on searching event history, please refer to the following article:
 [BioStar 2 API] How To Retrieve Events Logs

Additional Resources

BioStar X API Documentation

BioStar X API Doc

If an API you are looking for does not appear in this documentation, it is not yet available for public use.

Need Help?

If you have questions regarding BioStar X API, please submit a ticket through our support page:
Suprema Support Page