Skip to main content
API docs by Redocly

BioStar X API (1.0.0)

Download OpenAPI specification:Download

Suprema Inc.: CS@suprema.co.kr URL: https://www.supremainc.com

Overview

Suprema BioStar X API is a JSON-based API. All requests are made to endpoints beginning with https://server_ip|domain_name[:port]/api

The API can be used to perform almost any operation. Following are a few examples of what can be done with Suprema BioStar X API:

  • Manage User data

  • Manage Access Group data

  • Manage Doors data

  • Assign an Access Group to one or multiple User

  • Assign a User with one or multiple Access Group

  • Manage Devices

  • And many more...

All requests must be secure (https).

General Information

To call the API, BioStar X is mainly using HTTP Methods GET, POST, PUT, and DELETE.

  • GET is used to retrieve data from the server at the specified resource. For example, if you want to retrieve the User data with /users endpoint, then by making a GET request to the endpoint should result with the list of all available users.

  • POST request is used to send data to the server to create or a resource. The data sent to the server is stored on the body of the HTTP request.

  • PUT is similar to POST in that it creates or s a resource. The difference between them is that when calling the same PUT requests multiple times it will have the same result. While calling a POST request repeatedly will create the same resource multiple times.

  • DELETE is used to delete resources at the specified endpoint.

There are four parameter location that’s being used on Suprema BioStar X API:

  • PATH parameter is located on the URL, usually on the end of an endpoint. For example in /items/{ItemID}, the PATH parameter is ItemID.

  • BODY. An array of string values will be located on the BODY of the HTTP request. The request body needs to be in JSON format.

  • QUERY. Similar to the PATH parameter, QUERY parameter is also located on the URL, the difference is QUERY parameter will be located after a question mark. Example: /items?id=###, the QUERY parameter is id.

  • HEADER. Custom headers that are expected as part of the request.

Path templating refers to the usage of template expressions, delimited by curly braces ({}), to mark a section of a URL path as replaceable using path parameters. Example: https://127.0.0.1:4433/api/some_api/{id}
Above example shows that the required value will be placed on {id}

Release Notes

2025-09-30

  • Initial version

Authorization

Login

In order to create User through Suprema BioStar X API, you will need a Session ID which will be available after you’re logged in.

To log in, make a form encoded server side POST request as shown on example right. There will be a key called bs-session-id, which is a consecutive strings of hex digits located on the header of the response:

bs-session-id: 643f64efb7114485a2fd89de17ca13fb

This value will be used as authorization of the APIs that will be called. To apply this value, put it on the header of the API that will be called with key name bs-session-id.

Request Body schema: application/json
login_id
required
string

Your login ID.

password
required
string

Your password.

Responses

Request samples

Content type
application/json
{
  • "login_id": "admin",
  • "password": "admin"
}

Response samples

Content type
application/json
{
  • "User": {
    },
  • "Response": {}
}

Logout

This API is used to Logout from the current session. There are no body parameter on this endpoint. It is required to have bs-session-id key on the header, the value generated on successful login. Known errors:

  • Placing "/" at the end of the endpoint
Authorizations:
SessionAuth

Responses

Request samples 

curl --request POST \
  --url https://{baseurl}/api/logout \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{}

Access Group

This section contains all API related to Access Group (AG)

Create New Access Group

This request is used to make a new Access Group (AG).

Note: If BioStar X does not have license for Elevator module, skip the floor_levels parameter or set it to an empty string.

Known errors:

  • Placing "/" at the end of the endpoint - name is a required and unique parameter
Authorizations:
SessionAuth
Request Body schema: application/json
required
required
object
name
required
string

The name of the AG. Must be unique

description
string

AG's description

Array of objects

List of user(s) id of the AG

Array of objects

List of user group(s) id of the AG

Array of objects

List of access level(s) id of the AG

Array of objects

List of floor level(s) id of the AG

Responses

Request samples

Content type
application/json
{
  • "AccessGroup": {
    }
}

Response samples

Content type
application/json
{
  • "AccessGroup": {
    },
  • "DeviceResponse": {
    },
  • "Response": {}
}

List All Access Group

This API is used to view all available Access Groups.

By default the result will be sorted ascending by id.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/access_groups \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "AccessGroupCollection": {
    },
  • "Response": {}
}

Delete an Access Group

Delete an Access Group specified by the id query parameter.

Note: The id parameter is required and must be a valid access group ID.

To get an Access Group's id, you can use GET /api/access_groups to view all available Access Groups.

Known errors:

  • Using id which doesn't exist - Using value other than number
Authorizations:
SessionAuth
query Parameters
id
required
string
Example: id=12

ID of the Access Group to be deleted

Responses

Request samples 

curl --request DELETE \
  --url 'https://{baseurl}/api/access_groups?id=12' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{}

List All Access Group v2

This API is used to see all Access Groups. It provides more concise response rather than the previous (GET /api/access_groups) and parameters to filter the response.

Known errors:

  • Empty body
  • Input other than number on limit parameter
  • Input without key:value pair (name:val or id:val) on order_by parameter

Changes:

  • v2.9.9:

    Trailing slashes (/) at the end of this endpoint are no longer supported.

Authorizations:
SessionAuth
Request Body schema: application/json
required
limit
required
integer

To limit result by n record(s), 0 to show all

order_by
required
string^(name|id):(true|false)$

To order result(s) by name or id. Format - field:direction (false=ascending, true=descending)

Responses

Request samples

Content type
application/json
{
  • "limit": 0,
  • "order_by": "id:false"
}

Response samples

Content type
application/json
{
  • "AccessGroupCollection": {
    },
  • "Response": {}
}

View an Access Group

To view an Access Group with id {id} or :id {id} or :id are markers for replacing with the required value.

Known errors:

  • Using id which doesn't exist
  • Using value other than number
  • Placing "/" at the end of the endpoint
Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 1

ID of the Access Group to retrieve

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/access_groups/1 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
Example
{
  • "AccessGroup": {
    },
  • "Response": {}
}

Update an Access Group

Update an existing Access Group by replacing it with new data.

Notes:

  • To add/delete multiple, repeat the braces (see users example)

  • When you add/update data, it will remove any previous data and add the one that you input.

    Ex: If parameter description have value, and on update this parameter value is left empty, then the previous value will be removed.

  • To skip a record from updating, either skip the parameter or fill the current data on the update field.

  • When updating an AG, parameter user_group need to be filled if existing User Group want to be retained. If this parameter is left empty, the existing User Group(s) in the AG that should be still there will not be there.

Known Errors:

  • Repeating the same value on parameter with multiple options
Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 1

ID of the Access Group which will be updated

Request Body schema: application/json
required
required
object (AccessGroupUpdate)
name
required
string

The name of the Access Group. Must be unique

description
string

Access Group description

Array of objects

Current list of user IDs for the Access Group (replaces existing users)

Array of objects

List of user group IDs for the Access Group (replaces existing user groups)

Array of objects

List of access level IDs for the Access Group (replaces existing access levels)

Array of objects

List of floor level IDs for the Access Group (replaces existing floor levels)

Array of objects

List of user IDs to add to the Access Group

Array of objects

List of user IDs to remove from the Access Group

Responses

Request samples

Content type
application/json
{
  • "AccessGroup": {
    }
}

Response samples

Content type
application/json
{}

View List of Users from an Access Group

To view user information only from AG with id {id} Known errors:

  • Using id which doesn't exist will return success but show no record

  • Using value other than number

  • Placing "/" at the end of the endpoint

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 1

ID of the Access Group to retrieve users from

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/access_groups/1/users \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "UserCollection": {
    },
  • "Response": {}
}

Access Level

This section contains all API related to Access Level (AL)

Create New Access Level

Create a new Access Level (AL) with doors and schedule configuration.

Important Notes:

  • Access level items link doors with schedules
  • Multiple doors can be assigned to the same schedule
  • Each door can only appear once in the access level items

Known errors:

  • Placing "/" at the end of the endpoint
  • name is a required and unique parameter
  • Duplicate id on doors instance
Authorizations:
SessionAuth
Request Body schema: application/json
required
required
object (AccessLevelInput)
name
required
string

The name of the Access Level. Must be unique

description
string

Access Level description

Array of objects

Array of access level items linking doors to schedules

Responses

Request samples

Content type
application/json
{
  • "AccessLevel": {
    }
}

View All Access Level

This request is used to view all Access Level (AL)

The parameter type is QUERY.

Known errors:

  • Duplicate id on doors instance
Authorizations:
SessionAuth
query Parameters
limit
integer
Example: limit=50

Limit response record(s) by the amount specified on this parameter. 0 for show all.

offset
integer

Shift response record(s) by the amount specified on this parameter. default value = 0

order_by
string
Example: order_by=id:false

Order the response record(s)

Responses

Request samples 

curl --request GET \
  --url 'https://{baseurl}/api/access_levels?limit=50&offset=0&order_by=id%3Afalse' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Update an Access Level

This request is used to update an Access Level (AL)

Known errors:

  • Placing "/" at the end of the endpoint

  • name is a required and unique parameter

  • Duplicate id on doors instance

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 41

ID of the AL that will be updated

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "AccessLevel": {
    }
}

Delete an Access Level

This request is used to delete an existing Access Level (AL)

Known errors:

  • Placing "/" at the end of the endpoint

  • Value other than number on PATH variable

  • Non-existent record id on PATH variable will return success but no action.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 12

ID of the AL that will be deleted

Responses

Request samples 

curl --request DELETE \
  --url https://{baseurl}/api/access_levels/12 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Backup

View Backup Configuration

This API is used to view BioStar X Backup configuration.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/v2/setting/getBackupDbConfig \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Check Running Schedule

This API is used to check if there's any running backup process.

Message response will be True if there's any, and False if there's no running backup process.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/v2/setting/checkBackupScheduler \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Update Backup Configuration

This API is used to modify BioStar X backup configuration.

Authorizations:
SessionAuth
Request Body schema: application/json
required
use
required
string
Enum: "true" "false"

Toggle to enable/disable scheduled backup

cycle
required
string^([1-9]|[1-9][0-9]|100)$

Number of backup files to keep (1 to 100)

path
required
string

Backup folder path (must exist)

minute
required
string^([0-9]|[1-5][0-9])$

Minute value for scheduled backup (0 to 59)

hour
required
string^([0-9]|1[0-9]|2[0-3])$

Hour value for scheduled backup (0 to 23)

days
required
string

Date value for scheduled backup

month
required
string

Month value for Scheduled Backup. Leave it as * since currently it only support Daily and Weekly.

weeks
required
string

Day value for Scheduled Backup. Used when it's configured as Weekly Backup. (mon tue wed thu fri sat sun, default value is ?)

userId
required
string

User ID of the user who modifies the configuration

Responses

Request samples

Content type
application/json
{
  • "use": "true",
  • "cycle": "10",
  • "path": "C:\\\\Backup",
  • "minute": "12",
  • "hour": "0",
  • "days": "*",
  • "month": "*",
  • "weeks": "?",
  • "userId": "1"
}

Run Backup

This API is used to run Backup process.

It is required to have BODY parameters when running this API. Use GET /api/v2/setting/getBackupDbConfig for BODY payload.

Authorizations:
SessionAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "use": "false",
  • "cycle": "5",
  • "path": "C:\\Program Files\\BioStar 2(x64)\\Backup",
  • "minute": "0",
  • "hour": "0",
  • "days": "*",
  • "month": "*",
  • "weeks": "*"
}

Cards

Update Wiegand Formats

It is possible to use a custom wiegand format. To create a custom format, you can edit the provided formats which is between id number 5 to 14.

Authorizations:
SessionAuth
path Parameters
id
required
integer [ 5 .. 14 ]

ID of the wiegand format which will be updated (5-14 for custom formats).

Request Body schema: application/json
required
object
id
string

ID of the Wiegand format

name
string

Name of the Wiegand format

description
string

Description of the Wiegand format

length
integer

Total bits of the card

use_facility_code
boolean
Enum: true false

Toggle to use facility code

id_fields
Array of strings <base64> [ items <base64 > ]

Encoded input of the ID bits. Facility code will also be placed here

parity_fields
Array of strings <base64> [ items <base64 > ]

Encoded input of the parity bits

parity_types
Array of integers
Items Enum: 1 2

Parity types (1=Odd, 2=Even)

parity_positions
Array of integers

Position of the parity bits. Put it on the same sequence as parity_types

Responses

Request samples

Content type
application/json
{
  • "WiegandFormat": {
    }
}

View Wiegand Format Detail

This API is used to view a wiegand format detail.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 1

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/cards/wiegand_formats/1 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Delete Smart Card Layout

This API is used to delete smart card layout from BioStar X.

Authorizations:
SessionAuth
query Parameters
id
string

Responses

Request samples 

curl --request DELETE \
  --url 'https://{baseurl}/api/cards/layouts?id=SOME_STRING_VALUE' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

View Smart Cards Layout

This API is used to view all available smart card layouts.

Authorizations:
SessionAuth
query Parameters
limit
string
Example: limit=null

Limit the number of responses by n records. Remove this parameter to view all.

offset
string
Example: offset=null

Offset the response shown by n records.

Responses

Request samples 

curl --request GET \
  --url 'https://{baseurl}/api/cards/layouts?limit=null&offset=null' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Create Smart Card Layout

This API is used to create smart card layout.

Fill the corresponding parameter with the card's specification.

If the card uses default configuration, then simply fill the name and run the API.

Authorizations:
SessionAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "CardLayout": {
    }
}

View All Card Types

This API is used to view all available card types.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/cards/types \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Check Card Availability

This API is used to check whether a card already posted on the system or not.

If card already posted, then it will show the card's detail on the response.

Authorizations:
SessionAuth
query Parameters
card_id
integer
Example: card_id=123

ID of the card which will be checked.

Responses

Request samples 

curl --request GET \
  --url 'https://{baseurl}/api/v2/cards/registered?card_id=123' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

View a Card Detail

This API is used to find a card by card ID and find out who owns the card.

Authorizations:
SessionAuth
query Parameters
query
integer
Example: query=1169166509350528

ID of the card which will be viewed

Responses

Request samples 

curl --request GET \
  --url 'https://{baseurl}/api/cards?query=1169166509350528' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Create BioStar X QR

This API is used to create BioStar X QR. NOTE: This API will return error if the card_id already exists in the database. Use Check Card Availability API to validate.

Authorizations:
SessionAuth
Request Body schema: application/json
required
required
object
required
Array of objects

Array of card objects to create

Array
required
object

Card type configuration

display_card_id
integer

Display card ID shown in the interface

card_id
required
integer

Input value shown/read when scanning the card. Must be unique

Responses

Request samples

Content type
application/json
{
  • "CardCollection": {
    }
}

List Unassigned Cards

This API is used to view all unassigned cards recorded on BioStar X.

Authorizations:
SessionAuth
query Parameters
card_type
string
Example: card_type=csn

Limit the response to show only the specified type of card. Use plus (+) sign as separator to filter by multiple types.

limit
string
Example: limit=null

Limit the number of responses by n records. Remove this parameter to view all.

offset
string
Example: offset=null

Offset the response shown by n records.

wiegand_format_id
integer
Example: wiegand_format_id=4

Limit the response to show only the specified wiegand format. Remove this parameter to show all.

Responses

Request samples 

curl --request GET \
  --url 'https://{baseurl}/api/cards/unassigned?card_type=csn&limit=null&offset=null&wiegand_format_id=4' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

List Assigned Cards

This API is used to view all assigned cards recorded on BioStar X.

Authorizations:
SessionAuth
query Parameters
card_type
string
Example: card_type=wiegand

Limit the response to show only the specified type of card. Use plus (+) sign as separator to filter by multiple types.

offset
integer

Offset the response shown by n records.

wiegand_format_id
string

Limit the response to show only the specified wiegand format. Remove this parameter to show all.

Responses

Request samples 

curl --request GET \
  --url 'https://{baseurl}/api/cards/assigned?card_type=wiegand&offset=0&wiegand_format_id=SOME_STRING_VALUE' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

List Blacklisted Cards

This API is used to view all blacklisted cards recorded on BioStar X.

Authorizations:
SessionAuth
query Parameters
limit
integer
Example: limit=1000

Limit the number of responses by n records. Remove this parameter to view all.

offset
integer

Offset the response shown by n records.

Responses

Request samples 

curl --request GET \
  --url 'https://{baseurl}/api/cards/blacklist?limit=1000&offset=0' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Delete Blacklisted Card

This API is used to remove a blacklisted card from the list.

Authorizations:
SessionAuth
query Parameters
id
integer
Example: id=50

ID of the blacklisted card which will be removed from the list.

Responses

Request samples 

curl --request DELETE \
  --url 'https://{baseurl}/api/cards/blacklist?id=50' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Blacklist Card

This API is used to add a card to blacklist.

Authorizations:
SessionAuth
Request Body schema: application/json
required
required
object
required
object

Card identifier information

id
required
integer

ID of the card which will be added to the blacklist

Responses

Request samples

Content type
application/json
{
  • "Blacklist": {
    }
}

View Wiegand Formats

This API is used to view all available wiegand format.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/cards/wiegand_formats \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

View a Smart Card Layout Details

This API is used to view a smart card layout details.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 1

ID of the card layout which will be viewed.

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/cards/layouts/1 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Write Card Data

This API is used to create Access on Card and write data to a card (Smart Card, etc.) using the specified device. The device must have a Smart Card layout configured before running this API.

Authorizations:
SessionAuth
path Parameters
device_id
required
integer
Example: 542353521

ID of the device which will be used to write the card. Do set the Smart Card layout of the device before running this API.

Request Body schema: application/json
required
object
required
object

User information and biometric templates

required
object

Card identification information

Responses

Request samples

Content type
application/json
{
  • "SmartCard": {
    }
}

Create Mobile Card

This API is used to create Mobile Card.

Authorizations:
SessionAuth
Request Body schema: application/json
required
required
object
required
object

User information and biometric templates

required
object

Card identification information

required
object

Layout ID for Mobile Credential

required
object

Mobile credential options

Responses

Request samples

Content type
application/json
{
  • "SmartCard": {
    }
}

Format Smart Card

This API is used to remove the written smart card data from a Smart Card.

Authorizations:
SessionAuth
path Parameters
dev_id
required
string

Device ID with the corresponding layout set which will be used to write the card.

Responses

Request samples 

curl --request POST \
  --url https://{baseurl}/api/devices/{dev_id}/erase_card \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Send BioStar X QR by Email

This API is used to send BioStar X QR by email.

Before using this API, make sure that:

  • SMTP is set
  • User email field is filled
Authorizations:
SessionAuth
Request Body schema: application/json
required
id
required
integer

ID of the user which the QR code applied to and the email will be sent to.

language
required
string
Enum: "ko" "en"

Language for the email content. (ko=Korean, en=English)

required
Array of objects non-empty

Collection of QR cards to be sent via email

total
required
integer

Total number of cards in the collection

Responses

Request samples

Content type
application/json
{
  • "id": 1,
  • "language": "en",
  • "card_collection": [
    ],
  • "total": 1
}

Send Visual Face by Email

This API is used to send Visual Face mobile enrollment link.

Authorizations:
SessionAuth
Request Body schema: application/json
required
id
required
string

User ID

language
required
string
Enum: "ko" "en" "ja"

Language which will be used for the email content. (ko=Korean, en=English, ja=Japanese)

required
object

Advanced search criteria for batch processing. See Batch Edit with Advanced Search for adv_criteria details

Responses

Request samples

Content type
application/json
{
  • "id": "1",
  • "language": "en",
  • "adv_criteria": {
    }
}

User Groups

List User Group

This API is used to list all User Groups.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/user_groups \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Create User Group

This API is used to create a new User Group.

Note:

  • User groups may be created in up to 8 levels.

  • Up to 48 characters may be entered for a user group name.

Authorizations:
SessionAuth
Request Body schema: application/json
required
required
object
required
object

Parent User Group information

depth
integer <= 8

Depth of the User Group based on the parent (automatically calculated if not provided).

name
required
string <= 48 characters

Name of the User Group.

Responses

Request samples

Content type
application/json
{
  • "UserGroup": {
    }
}

Delete User Group

This API is used to delete a User Group.

Authorizations:
SessionAuth
query Parameters
id
integer
Example: id=21436

Id of the User Group which will be deleted.

Responses

Request samples 

curl --request DELETE \
  --url 'https://{baseurl}/api/user_groups?id=21436' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Search User Groups by ID

This API is used to list User Group(s) which are specified in the request body.

Authorizations:
SessionAuth
Request Body schema: application/json
optional
user_group_id_list
Array of strings

Specify User Group ids which will be viewed. Use comma (,) as separator.

Responses

Request samples

Content type
application/json
{
  • "user_group_id_list": {
    }
}

Update User Group

This API is used to update a User Group.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 21436

ID of the User Group which will be updated

Request Body schema: application/json
required
object
name
string [ 1 .. 48 ] characters

New name for the user group

Responses

Request samples

Content type
application/json
{
  • "UserGroup": {
    }
}

User

This section contains all API related to Users

Update User Fingerprint Credentials

This API is used to update fingerprint data on a User.

Use POST /api/devices/{dev_id}/scan_fingerprint to enroll fingerprint. Use POST /api/server_matching/identify_finger to check whether the fingerprint already recorded or not.

Important Notes:

  • Raw data for template0 and template1 available after enrolling a fingerprint
  • Fingerprint(s) used for regular access should not be registered as duress fingerprint
  • If the fingerprint authentication rate is low, delete the existing fingerprint information and add a new fingerprint
  • Use an adequate security level. If 1:1 Security Level is too high, the fingerprint authentication rate may be too low or the false rejection rate (FRR) may be too high
  • For best fingerprint scanning quality, make sure to cover the entire surface of the fingerprint sensor with the finger
Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 14

ID of the user to update fingerprint credentials

Request Body schema: application/json
required
required
object
required
Array of objects [ 1 .. 10 ] items

Array of fingerprint templates for the user

Array ([ 1 .. 10 ] items)
finger_mask
boolean

Set to true to mark the fingerprint as a duress fingerprint. When threatened by someone to open the door, the user can authenticate using this fingerprint to send an alarm signal to BioStar X.

template0
required
string

First scan template of the fingerprint (Raw data)

template1
required
string

Second scan template of the fingerprint (Raw data)

isNew
boolean

Indicates if this is a new fingerprint template

Responses

Request samples

Content type
application/json
{
  • "User": {
    }
}

View a User's Details

This API is used to view a user's details which is recorded on BioStar X.

Known errors:

  • Putting "/" at the end of the endpoint

  • Using User ID which doesn't exist

Authorizations:
SessionAuth
path Parameters
id
required
string
Example: {{iterIDVal}}

ID of the User

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/users/{{iterIDVal}} \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

User: Bulk Update

This API is used for updating user information in bulk.

The difference of this API and /api/users?id=1+2+3 is that this API can update different data of many users at the same time.

Warning: The maximum number of users that can be modified in a single API call is 100.

Response Codes:

  • ret_code presents BioStar X response code for modifying each user
  • Response.code could be 0 (Overall success), 1 (Partial success), 8 (Overall failed)
  • For error code meanings, refer to [BioStar X Install Path]\nginx\html\resources\messages_en
Authorizations:
SessionAuth
Request Body schema: application/json
required
required
object
required
Array of objects [ 1 .. 100 ] items

Array of user objects to update (maximum 100 users)

Array ([ 1 .. 100 ] items)
user_id
required
string

User ID of the user. This will be used as the update target

name
string <= 48 characters

Name of the user. Up to 48 characters

object

User Group information

disabled
boolean

Toggle User active or not; false for active, true for non-active

start_datetime
string <date-time>

Start active period for the User

expiry_datetime
string <date-time>

End active period for the User

email
string <email>

Email address of the User

department
string <= 64 characters

Department of the User. Up to 64 characters

user_title
string

Title of the User

login_id
string

Login ID of the user

password
string

Password for the user

user_ip
string

Limit the access of the User so he/she can only login from the registered IP Address

Responses

Request samples

Content type
application/json
{
  • "UserCollection": {
    }
}

Response samples

Content type
application/json
{}

Check Picture Specification

This API is used to check whether the image that will be uploaded on Visual Face credential is according to specification or not.

  • Supported image file size is up to 10MB.
  • Supported image file formats are JPG, JPEG and PNG.
Authorizations:
SessionAuth
Request Body schema: application/json
template_ex_picture
string <byte>

Image that will be checked (base64 encoded)

Responses

Request samples

Content type
application/json
{
  • "template_ex_picture": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcUFhYaHSUfGhsjHBYWICwgIyYnKSopGR8tMC0oMCUoKSj/2wBDAQcHBwoIChMKChMoGhYaKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCj/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAv/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFQEBAQAAAAAAAAAAAAAAAAAAAAX/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwBVD//Z"
}

Delete User(s) with Advanced Search

This API is used to delete user(s) which is collected from Advanced Search query.

Users matching the advanced search criteria will be deleted from the system.

Authorizations:
SessionAuth
query Parameters
adv
required
string
Example: adv=mode1

Use this to enable Advanced Search query result

Request Body schema: application/json
required
required
object (AdvancedSearchCriteria)

Advanced Search criteria for finding users

limit
required
integer

The maximum number of users to return. Default is 50.

offset
integer

The number of users to skip before starting to return results. Default is 0.

user_id
string

The User ID to search, supports like search

order_by
required
string

Order, will accept with format properties:false, for example if we want to order by name, it will be user_name:false. (false = ASCENDING and true = DESCENDING)

user_group_id
integer

Group ID for search user. Also gets the child user group

user_group_ids
Array of integers

Array of Group IDs for advanced search parameter

user_name
string

User name for Advance Search parameter, supports like search both encrypted and unencrypted

user_email
string <email>

User email, supports like search both encrypted and unencrypted

user_phone
string

User Phone for Advance Search parameter, supports like search both encrypted and unencrypted

user_access_group_ids
string

User access group id for advance search parameter, supports multiple value with format String with Delimiter , i.e 1,2,3.

* = User(s) who have any Access Group.

void = User(s) who does not belong to any Access Group.

user_operator_level_id
required
integer

User operator level id for Advance Search parameter Value 0 = user with all operator level, -1 = user with no operator level, else ID of operator level

user_department
string

User Department for Advance Search parameter, supports like search on unencrypted and exact search on encrypted

user_title
string

User title for advance search parameter, supports like search on unencrypted and exact search on encrypted

user_card
string

User card ID to search

user_custom_field_1
string or null

Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted

user_custom_field_2
string or null

Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted

user_custom_field_3
string or null

Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted

user_custom_field_4
string or null

Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted

user_custom_field_5
string or null

Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted

user_custom_field_6
string or null

Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted

user_custom_field_7
string or null

Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted

user_custom_field_8
string or null

Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted

user_custom_field_9
string or null

Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted

user_custom_field_10
string or null

Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted

user_status
boolean
Enum: false true

User status for advance search parameter. false = Active, true = Inactive

Responses

Request samples

Content type
application/json
{
  • "adv_criteria": {
    }
}

Response samples

Content type
application/json
{}

Send User Data to Device

This API is used to send user data to a device. For example when you want to send user John data after credential update to FaceStation F2. Notes:

  • Set adv=mode1 on Query Parameter to enable advanced search compatibility. This parameter is optional. When not used, it will use the previous capability.
  • Maximum of 100 users can be processed in a single request
  • Request Body with Advanced Search example (see Batch Edit with Advanced Search for adv_criteria details)
{
  "DeviceCollection" : {
    "rows" : [ {
      "id" : "50362288"
    } ]
  },
  "adv_criteria" : {
    "limit" : 50,
    "order_by" : "user_id:false",
    "user_group_ids" : [ 1014 ],
    "user_id" : "8",
    "user_email" : "support@supremainc.com"
  }
}
Authorizations:
SessionAuth
query Parameters
overwrite
boolean
Example: overwrite=true

Toggle to overwrite the data on the device. True to overwrite (default value)

id
integer
Example: id=15

ID of the User that will be sent to the Device. To send multiple users, use plus (+) sign as separator of each User ID. Ex: 1001+1002+1003+1004

adv
string
Example: adv=mode1

Use this to enable Advanced Search query result.

Request Body schema: application/json
required
One of
required
object
required
Array of objects non-empty

Array of device IDs to export user data to

Array (non-empty)
id
required
string

ID of the device

Responses

Request samples

Content type
application/json
Example
{
  • "DeviceCollection": {
    }
}

Response samples

Content type
application/json
{}

Delete User(s) From Device (Advanced Search)

This API is used to delete user data from device(s) based on Advanced Search query results. Users matching the advanced search criteria will have their data removed from the specified devices. Notes:

  • Requires adv=mode1 query parameter to enable advanced search functionality
  • Only user data is removed from devices, not from the BioStar X database
Authorizations:
SessionAuth
query Parameters
adv
string
Example: adv=mode1

Use this to enable Advanced Search query result.

Request Body schema: application/json
required
required
object
required
object (AdvancedSearchCriteria)

Advanced Search criteria for finding users

Responses

Request samples

Content type
application/json
{
  • "DeviceCollection": {
    },
  • "adv_criteria": {
    }
}

Response samples

Content type
application/json
{}

List Idle Users - Multiple ID

This API shows a workaround using this API to get multiple users data by adjusting the parameters.

The advantage of this workaround is that the API response can be adjusted to only show only the required users directly.

  • Query parameter search_month value is set to 0 or removed
  • Body parameter conditions:column value set to user_id, :operator value to 2 (contains), and :value can specify multiple user id which uses comma as separator.

For BODY Parameter details refer to POST List Idle Users.

Authorizations:
SessionAuth
Request Body schema: application/json
required
required
object
offset
required
integer >= 0

Number of records to skip

limit
required
integer >= 0

Maximum number of records to return (0 for no limit)

Array of objects

Array of search conditions

Array of objects

Array of ordering specifications

Responses

Request samples

Content type
application/json
{
  • "Query": {
    }
}

Delete Idle Users

This API is used to delete idle users.

For BODY parameter refer to POST List Idle Users.

Authorizations:
SessionAuth
query Parameters
search_month
integer
Example: search_month=1

Filter user(s) which idle for the last n month(s).

id
string
Example: id=10 11

ID of the idle users which will be deleted. Use space as separator to delete multiple users.

Request Body schema: application/json
required
required
object
offset
required
integer >= 0

Number of records to skip

limit
required
integer >= 0

Maximum number of records to return (0 for no limit)

Array of objects

Array of search conditions

Array of objects

Array of ordering specifications

Responses

Request samples

Content type
application/json
{
  • "Query": {
    }
}

Advanced Search

This API is used to fetch user information via advanced search.

Supports flexible searching across multiple user fields including personal information, group membership, access levels, and custom fields. Notes:

  • To search users without documents, use "user_custom_field_#": "No" for specific custom fields
  • To search users with documents, use "user_custom_field_#": "Yes" for specific custom fields
  • user_operator_level_id values: -1 (None), 0 (All), or specific ID
  • Supports both encrypted and unencrypted field searches
  • Access group search format: "1,2,3" or "*" (any Access Group) or "void" (no Access Group)
Authorizations:
SessionAuth
Request Body schema: application/json
required
limit
required
integer

The maximum number of users to return. Default is 50.

offset
integer

The number of users to skip before starting to return results. Default is 0.

user_id
string

The User ID to search, supports like search

order_by
required
string

Order, will accept with format properties:false, for example if we want to order by name, it will be user_name:false. (false = ASCENDING and true = DESCENDING)

user_group_id
integer

Group ID for search user. Also gets the child user group

user_group_ids
Array of integers

Array of Group IDs for advanced search parameter

user_name
string

User name for Advance Search parameter, supports like search both encrypted and unencrypted

user_email
string <email>

User email, supports like search both encrypted and unencrypted

user_phone
string

User Phone for Advance Search parameter, supports like search both encrypted and unencrypted

user_access_group_ids
string

User access group id for advance search parameter, supports multiple value with format String with Delimiter , i.e 1,2,3.

* = User(s) who have any Access Group.

void = User(s) who does not belong to any Access Group.

user_operator_level_id
required
integer

User operator level id for Advance Search parameter Value 0 = user with all operator level, -1 = user with no operator level, else ID of operator level

user_department
string

User Department for Advance Search parameter, supports like search on unencrypted and exact search on encrypted

user_title
string

User title for advance search parameter, supports like search on unencrypted and exact search on encrypted

user_card
string

User card ID to search

user_custom_field_1
string or null

Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted

user_custom_field_2
string or null

Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted

user_custom_field_3
string or null

Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted

user_custom_field_4
string or null

Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted

user_custom_field_5
string or null

Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted

user_custom_field_6
string or null

Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted

user_custom_field_7
string or null

Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted

user_custom_field_8
string or null

Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted

user_custom_field_9
string or null

Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted

user_custom_field_10
string or null

Custom fields for advance search parameter support like search on unencrypted and exact search on encrypted

user_status
boolean
Enum: false true

User status for advance search parameter. false = Active, true = Inactive

Responses

Request samples

Content type
application/json
{
  • "limit": 50,
  • "offset": 0,
  • "user_id": "11",
  • "order_by": "user_id:false",
  • "user_group_id": 1,
  • "user_group_ids": {
    },
  • "user_name": "John",
  • "user_email": "abc@gmail.com",
  • "user_phone": "123-456-7890",
  • "user_access_group_ids": "17,18",
  • "user_operator_level_id": 0,
  • "user_department": "Engineering",
  • "user_title": "Manager",
  • "user_card": "123456",
  • "user_custom_field_1": "string",
  • "user_custom_field_2": "string",
  • "user_custom_field_3": "string",
  • "user_custom_field_4": "string",
  • "user_custom_field_5": "string",
  • "user_custom_field_6": "string",
  • "user_custom_field_7": "string",
  • "user_custom_field_8": "string",
  • "user_custom_field_9": "string",
  • "user_custom_field_10": "string",
  • "user_status": false
}

Response samples

Content type
application/json
{
  • "UserCollection": {
    },
  • "Response": {}
}

List All User v2

This API is used to list all users recorded on Bio Star X.

Known errors:

  • At least one parameter must exist

  • Using unavailable user_group_id will show empty response

Authorizations:
SessionAuth
Request Body schema: application/json
required
limit
required
integer >= 0

Limit response record(s) by the value specified on this parameter. Use 0 for no limit.

search_text
string or null

Search record(s) with the text specified on this parameter. Performs like search across user fields.

user_group_id
integer or null

Filter response record(s) according to user_group_id specified on this parameter

order_by
string

Order the response record(s) by the User parameter such as user_id or name. Format is field_name:false for ascending, field_name:true for descending.

Responses

Request samples

Content type
application/json
{
  • "limit": 50,
  • "search_text": "John",
  • "user_group_id": 1,
  • "order_by": "user_id:false"
}

View User by Account Level

This API is used to view all user permission grouped by user account level.

1: Administrator
2: User Operator
3: Monitoring Operator
4-252: Custom Account Level
253: Video
254: TA
255: User
100000: Visitor

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/permissions \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

List User Fields

This API is used to list user fields which can be processed as CSV.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/users/csv_option \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Download CSV File

This API is used to download exported CSV files from BioStar X Server.

Supports downloading both user-related CSV files and events-related CSV files. The system automatically detects the file type based on the filename pattern.

Supported File Types:

  • User CSV files: Generated from POST /api/users/csv_export
  • Events CSV files: Generated from POST /api/events/export

Usage:

  1. Export data using the appropriate API (csv_export for users, export for events)
  2. Get the filename from the export response
  3. Use the filename as the path parameter in this download API
Authorizations:
SessionAuth
path Parameters
csv_filename
required
string
Examples:
  • User_Import_Error_20220124T143708.csv - User CSV file
  • Report_20220204T165145.csv - Events CSV file

Name of the CSV file to download (supports both user and events files)

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/download/User_Import_Error_20220124T143708.csv \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Upload User File (CSV/TGZ) to BioStar X Server

This API is used to upload a file to BioStar X Server.

Usage of this API is to upload a .csv or .tgz file to BioStar X Server Installation path, which after the file can be further processed for importing User Data to the database through POST /api/users/csv_import or POST /api/users/data_import.

Uploaded file will be located on: {{BioStar X Installation Path}}\nginx\html\download

Do note that if there's any file with the same name, it will be overwritten

Authorizations:
SessionAuth
Request Body schema: multipart/form-data
file
string <binary>

Responses

Request samples 

curl --request POST \
  --url https://{baseurl}/api/attachments \
  --header 'bs-session-id: REPLACE_KEY_VALUE' \
  --header 'content-type: multipart/form-data' \
  --form file=/C:/Users/user/Desktop/BioStarX_20220124_173247.tgz

Export User Data as CSV (File Upload Example)

This API is used to export user data as CSV file with customizable columns and headers. Supports exporting user information including custom fields and file upload information. The exported CSV file can be downloaded using the /download/{csv_filename} endpoint.

Features:

  • Customizable column selection and headers
  • Support for custom fields including file upload fields
  • Advanced search criteria integration
  • Flexible user selection (specific IDs, all users, or search results)

Usage Flow:

  1. Call this API with desired query parameters and criteria
  2. Get the generated filename from the response
  3. Use the filename with /download/{csv_filename} to download the actual CSV file
Authorizations:
SessionAuth
query Parameters
id
string
Examples:
  • id=* - Export all users
  • id=1+2+3 - Export specific users
  • id=1001 - Export single user

ID of the Users to export. Use * to export all users. To select multiple users use plus sign (+) or space ( ) as separator.

adv
string
Value: "mode1"
Example: adv=mode1

Enable Advanced Search query result mode

Request Body schema: application/json
required
required
object

Data criteria and formatting options for CSV export

required
object

Advanced Search criteria for finding users

Responses

Request samples

Content type
application/json
{
  • "Query": {
    },
  • "adv_criteria": {
    }
}

Response samples

Content type
application/json
{}

Import User Data from CSV

This API is used to import User Data from a .csv file to the BioStar X database.

To run this API successfully, it is imperative to run POST /api/attachments first to upload the .csv file to the server install path.

After .csv file got uploaded to the server, put the filename value from the above API to the uri and fileName parameter on this API.

Fields listed on Query parameter are also used for field mapping between .csv file and BioStar X database.

For example field user_id on Query:headers (.csv) will be matched with the first field of Query:columns (BioStar X). To change this mapping, adjust the sequence on Query:headers as desired (eg. exchange field department with user_id so the value of department will be used on user_id on BioStar X).

To skip a field from mapping, put empty string ("") on the intended field.

If there's no issue on the import process, the API will shows "Success" response.
If there's issue (duplicate email, etc.), the response will show that the "Request is successful but partially" and will include a filename which contain records that caused the errors which can be downloaded by using GET /download/:csv_filename

If the CSV file to import contains data for custom user fields and the fields do not exist on the server, then the data for the fields will be ignored during the import process.

To enter user information in a language other than English or Korean, save the CSV file in UTF-8 format.

Authorizations:
SessionAuth
Request Body schema: application/json
required
required
object

Information about the uploaded CSV file

required
object

Import configuration and options

required
object

Field mapping configuration between CSV and database

Responses

Request samples

Content type
application/json
{
  • "File": {
    },
  • "CsvOption": {
    },
  • "Query": {
    }
}

Data File Export

You can store the data file on external storage (USB) and import to BioStar X or device. Up to 500,000 users can be moved from server to device or from device to device.

  • The exported data file from devices using older firmware version cannot be imported into BioStar X. Make sure always use the latest version of firmware.

  • If you use BioStar 2.8.10 or later, data exported from the previous version of BioStar 2 cannot be imported.

  • If you use BioStar 2.8.10 or later, it is impossible to read data from a device that are using older firmware version. Upgrade the device’s firmware to a compatible version. Compatible devices and firmware versions are as follows:

    • BioStation 2 FW 1.9.0 or later > device_type: 8

    • BioStation A2 FW 1.8.0 or later > device_type: 9

    • FaceStation 2 FW 1.4.0 or later > device_type: 10

    • FaceStation F2 FW 1.0.0 or later > device_type: 29

    • X-Station 2 FW 1.0.0 or later > device_type: 32

  • If the fingerprint template format is different, the data file cannot be imported. For example, the data file exported from a device which uses the Suprema fingerprint template format cannot be imported into a device which uses the ISO fingerprint template format.

  • When importing user data with visual faces enrolled from FaceStation F2, the existing data will be retained if there are already visual face data enrolled on BioStar 2 via Upload Image or a mobile device.

  • The exported data file includes the profile photo, user ID, name, period, access group, PIN, auth. mode, credentials (face, fingerprint, card, mobile access card, visual face, BioStar 2 QR, QR/Barcode), 1:1 security level.

  • You can export visual face data directly registered from the device only. It is not possible to export the data registered with the other methods, such as image file upload, CSV import, and mobile devices.

  • Be sure that the device is selected correctly. Otherwise, the device cannot recognize the data file.

Authorizations:
SessionAuth
query Parameters
id
string
Example: id=14 15 16

User ID(s) to export. Use space as separator for multiple users.

adv
string
Example: adv=mode1

Enable Advanced Search query mode

Request Body schema: application/json
required
device_type
required
integer

Device type for which the exported data will be applied

  • 8: "BioStation 2 (FW 1.9.0 or later)"
  • 9: "BioStation A2 (FW 1.8.0 or later)"
  • 10: "FaceStation 2 (FW 1.4.0 or later)"
  • 29: "FaceStation F2 (FW 1.0.0 or later)"
  • 32: "X-Station 2 (FW 1.0.0 or later)"
group_id
required
integer >= 1

Group ID of the device

required
object

Advanced Search criteria for finding users

Responses

Request samples

Content type
application/json
{
  • "device_type": 35,
  • "group_id": 1,
  • "adv_criteria": {
    }
}

Response samples

Content type
application/json
{}

Data File Import

You can store the data file on external storage (USB) and import to BioStar 2 or device. Up to 500,000 users can be moved from server to device or from device to device.

  • The exported data file from devices using older firmware version cannot be imported into BioStar 2. Make sure always use the latest version of firmware.

  • If you use BioStar 2.8.10 or later, data exported from the previous version of BioStar 2 cannot be imported.

  • If you use BioStar 2.8.10 or later, it is impossible to read data from a device that are using older firmware version. Upgrade the device’s firmware to a compatible version. Compatible devices and firmware versions are as follows:

    • BioStation 2 FW 1.9.0 or later > device_type: 8

    • BioStation A2 FW 1.8.0 or later > device_type: 9

    • FaceStation 2 FW 1.4.0 or later > device_type: 10

    • FaceStation F2 FW 1.0.0 or later > device_type: 29

    • X-Station 2 FW 1.0.0 or later > device_type: 32

  • If the fingerprint template format is different, the data file cannot be imported. For example, the data file exported from a device which uses the Suprema fingerprint template format cannot be imported into a device which uses the ISO fingerprint template format.

  • When importing user data with visual faces enrolled from FaceStation F2, the existing data will be retained if there are already visual face data enrolled on BioStar 2 via Upload Image or a mobile device.

Select the desired file (.tgz) and then click Open.

A success message will appear on the screen when import successfully. Use POST /api/attachments to upload the file (.tgz) to the BioStar 2 server. Use the resulting filename on the response as value on the BODY parameter.

Authorizations:
SessionAuth
Request Body schema: application/json
required
required
object

Information about the uploaded device file

originalName
required
string^.*\.tgz$

Original filename of the uploaded file

name
required
string^.*\.tgz$

Current filename of the file on server (from /api/attachments response)

Responses

Request samples

Content type
application/json
{
  • "file": {
    }
}

Export User(s) as PDF/SVG with Advanced Search

Generate customizable user reports in PDF or SVG format using Advanced Search criteria.

Prerequisites:

  • Valid Advanced Search criteria must be provided
  • User must have appropriate permissions to generate reports

Report Configuration:

  • Display fields can be customized to show specific user data columns
  • Supports various formatting options (page size, orientation, headers)
  • Includes pagination and footer customization options

Output Formats:

  • PDF: For printable reports with consistent formatting
  • SVG: For web display and scalable graphics
Authorizations:
SessionAuth
query Parameters
use_centigrade
boolean
Example: use_centigrade=true
adv
string
Example: adv=mode1

Use this to enable Advanced Search query result.

Request Body schema: application/json
required

Report configuration and user data criteria

required
object

Report configuration and layout settings

required
object (AdvancedSearchCriteria)

Advanced Search criteria for finding users

Responses

Request samples

Content type
application/json
{
  • "View": {
    },
  • "adv_criteria": {
    }
}

Response samples

Content type
application/json
{
  • "FileCollection": {
    },
  • "Response": {}
}

Create/Update User Private Message

This API is used to create or update User Private Message.

This API is available starting from BioStar 2 version 2.9.8.

Authorizations:
SessionAuth
path Parameters
userId
required
integer
Example: 12

User ID of the user to whom the private message will be configured.

Request Body schema: application/json
required

Private message data to set for the user

phrase
required
string [ 1 .. 128 ] characters

Private message text to display to the user. Maximum 128 bytes - longer messages will be truncated.

Responses

Request samples

Content type
application/json
{
  • "phrase": "Good morning. Set private message here."
}

Response samples

Content type
application/json
{}

Delete User Private Message

This API is used to delete User Private Message.

This API is available starting from BioStar 2 version 2.9.8.

Authorizations:
SessionAuth
path Parameters
userId
required
integer
Example: 12

User ID of the user to whom the private message will be deleted.

Responses

Request samples 

curl --request DELETE \
  --url https://{baseurl}/api/v2/users/phrase/12 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{}

Fetch User Private Message

This API is used to fetch User Private Message.

This API is available starting from BioStar 2 version 2.9.8.

Authorizations:
SessionAuth
path Parameters
userId
required
integer
Example: 12

User ID of the user to whom the private message will be fetched.

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/v2/users/phrase/12 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "user_id": 12,
  • "phrase": "Good morning. You're expected at meeting room 1 at 09.00"
}

Download File from File Upload Custom Field

This API is used to download the file which contained in a File Upload Custom Field.

This API is available starting from BioStar 2 v2.9.8.

After receiving the response, convert the Base64 data on key document to file type specified on key mimetype.

Authorizations:
SessionAuth
path Parameters
UserID
required
integer
Example: 3

ID of the user which have the intended file.

customFieldID
required
integer
Example: 5

ID of the File Upload Custom Field which contain the file.

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/user_document/3/5 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{}

View User & Group

Retrieves a combined list of user groups and users, including hierarchical relationships between groups and their members.

This endpoint is typically used to build a tree structure (group → subgroup → user) for user management, filtering, or selection interfaces.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/v2/user/filter/user_and_group \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "Response": {},
  • "UserAndGroupCollection": {
    }
}

Delete User(s)

This API is used to delete user(s) from BioStar X.

Known errors:

  • Empty parameter `id``

  • Using `id`` which doesn't exist

Authorizations:
SessionAuth
query Parameters
id
string
Example: id={{iterIDVal}}

ID of the User which will be deleted. To delete multiple Users, use plus (+) sign as separator of each User ID. Ex: 1001+1002+1003+1004 Use GET `/api/users`` to list available users

Responses

Request samples 

curl --request DELETE \
  --url 'https://{baseurl}/api/users?id={{iterIDVal}}' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Batch Edit with Advanced Search

By adding adv=mode1 on Query Parameter, Batch Edit feature can works with Advanced Search result.

The API works by query users based on adv_criteria object, then apply new value based on input in User object.

Authorizations:
SessionAuth
query Parameters
adv
required
string
Value: "mode1"
Example: adv=mode1

Use this to enable Advanced Search query result

Request Body schema: application/json
required
required
object

User data to change

required
object (AdvancedSearchCriteria)

Advanced Search criteria for finding users

Responses

Request samples

Content type
application/json
{
  • "User": {
    },
  • "adv_criteria": {
    }
}

Response samples

Content type
application/json
{}

List All User

This API is used to list users which is recorded on BioStar X.

Known errors:

  • Putting "/" at the end of the endpoint
  • Using group_id which doesn't exist will return success but no records

Note: This API is deprecated in BioStar 2 v2.8.12, please use /api/v2/users/search instead.

Authorizations:
SessionAuth
query Parameters
group_id
integer
Example: group_id=1

Filter response record(s) according to the group_id specified on this parameter. Use GET /api/user_groups to list all User Groups. Default value: 1 to show all.

limit
integer

Limit response record(s) by the amount specified on this parameter. 0 for show all.

offset
integer

Shift response record(s) by the amount specified on this parameter. default value = 0. Ex: If you have 10 records, put value 5 on limit, and when you put value 5 on offset, you will get record 6 to 10 on the result.

order_by
string
Example: order_by=user_id:false

Order the response record(s) by the User parameter such as user_id or name. False for ascending, True for descending.

last_modified
integer

Show response record(s) with User last_modified value which is equal or greater than this parameter value.

Responses

Request samples 

curl --request GET \
  --url 'https://{baseurl}/api/users?group_id=1&limit=0&offset=0&order_by=user_id%3Afalse&last_modified=0' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Device Group

View All Device Group

This API is used to list all device groups recorded on BioStar X database.

Authorizations:
SessionAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "order_by": "depth:false"
}

View Device Group(s) with Criteria & Permission

This API is used to list all device groups recorded on BioStar 2 database.

Authorizations:
SessionAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "order_by": "depth:false"
}

Create New Device Group

This API is used to create new device group.

Authorizations:
SessionAuth
Request Body schema: application/json
object
name
string

Name of the device group

description
string

Description of the device group

object

Responses

Request samples

Content type
application/json
{
  • "DeviceGroup": {
    }
}

Update Device Group

This API is used to update a device group.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 5

ID of the device group which will be updated

Responses

Request samples 

curl --request PUT \
  --url https://{baseurl}/api/device_groups/5 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Delete Device Group

This API is used to delete device group.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 5

ID of the device group which will be deleted

Responses

Request samples 

curl --request DELETE \
  --url https://{baseurl}/api/device_groups/5 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Device

Write Card Data

This API is used to create Access on Card and write data to a card (Smart Card, etc.) using the specified device. The device must have a Smart Card layout configured before running this API.

Authorizations:
SessionAuth
path Parameters
device_id
required
integer
Example: 542353521

ID of the device which will be used to write the card. Do set the Smart Card layout of the device before running this API.

Request Body schema: application/json
required
object
required
object

User information and biometric templates

required
object

Card identification information

Responses

Request samples

Content type
application/json
{
  • "SmartCard": {
    }
}

Verify Fingerprint Scan

This API is used to compare 2 fingerprint scan to determine whether it's the same finger or not.

As shown on the example, it is applied on template0 and template1 where template0 is the 1st scan of the finger and template1 is the 2nd scan.

To get the value for these parameters, use POST /api/devices/:dev_id/scan_fingerprint two times. The first scan for template0 and second scan for template1.

It will return HTTP 200 and shows message result: true on success, HTTP 500 and shows message result: false on failure.

Authorizations:
SessionAuth
path Parameters
dev_id
required
integer >= 1
Example: 544140034

Unique identifier of the device to perform fingerprint verification

Request Body schema: application/json
required

Fingerprint templates and verification options

required
object

Container for the two fingerprint templates to compare

object

Optional verification configuration

Responses

Request samples

Content type
application/json
{
  • "FingerprintTemplate": {
    },
  • "VerifyFingerprintOption": {
    }
}

Verify Duplicate Fingerprint

This API is used to verify duplicate fingerprint.

If fingerprint already exist, it will return success (HTTP 200) and response will show the user which currently using the fingerprint.

Use the result of POST /api/devices/:dev_id/scan_fingerprint for the value of parameter template (either the 1st or 2nd scan).

If fingerprint available, it will return server error (HTTP 500) with response showing message "Failed to identify fingerprint.".

Authorizations:
SessionAuth
Request Body schema: application/json
required
object
template
required
string

Base64-encoded fingerprint template to identify

Responses

Request samples

Content type
application/json
{
  • "ServerMatching": {
    }
}

View Waiting Devices

This API is used to view device(s) which is on waiting list after changing connection mode from Server > Device to Device > Server.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/devices/waiting \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Add Slave Device

This example shows how to add slave device to BioStar X.

Authorizations:
SessionAuth
Request Body schema: application/json
object
Array of objects
Array
id
string

ID of the device

name
string

Name of the device

object
object
object

Responses

Request samples

Content type
application/json
{
  • "DeviceCollection": {
    }
}

List All Added Device(s)

This API is used to view all devices added to BioStar X.

Status response for this API:

Parameter Type Description
status Integer Connection status of the device.
0: Disconnected
1: Connected
2: Sync Error
Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/devices \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Remove Device(s)

This API is used to delete device(s).

Authorizations:
SessionAuth
query Parameters
id
integer
Example: id=543408590

ID of the device(s) which will be deleted. To delete multiple device use plus (+) sign as separator.

Responses

Request samples 

curl --request DELETE \
  --url 'https://{baseurl}/api/devices?id=543408590' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Update Device

This API is used to update device's configuration.
Put value which will be updated on the respective body parameter and remove any parameters which will not be updated.

Authorizations:
SessionAuth
path Parameters
id
required
string

ID of the device which will be updated

Request Body schema: application/json
required

Device configuration data to update. Only include fields that need to be changed.

object

Container for all device configuration settings

name
string

Display name of the device

object

Group ID of the device

object

LAN network configuration

object

USB configuration settings

object

WLAN wireless network configuration

object

RS485 serial communication configuration

object

Authentication and biometric settings

object

Card reader configuration and supported card types

object

Display and user interface settings

object

System-level configuration

object

Wiegand configuration

object

Time and Attendance (T&A) configuration

object

Input configuration

object

List of event filters in which image logs are saved on the device

object

VoIP configuration

object

Barcode configuration

pktversion
string

Packet version

support_occupancy
boolean

Support occupancy

object

Thermal camera configuration for temperature screening

object

Detailed thermal camera settings

trigger_actions
string

Trigger Actions

object

Authentication mode capabilities

object

Card types supported by the device

object

Device capability information

object

Image log event information

use_image_log
boolean

Use image log

dst1
string

DST1

dst2
string

DST2

Responses

Request samples

Content type
application/json
{
  • "Device": {
    }
}

View Device Information

This API is used to view device's information.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 542353521

ID of the device which information will be viewed

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/devices/542353521 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Update Device Homescreen

Updates the homescreen display resources for one or more BioStar X devices. This API allows you to customize the device display with custom images, logos, or notices that appear on the device's homescreen.

Prerequisites Before using this API, you must first configure the device's display settings using the Update Device API (/api/devices/{id}) with the following parameters:

  • background: Display mode (0=Default, 2=Slide Show)
  • background_theme: Content type (0=Normal, 1=Notice, 2=Logo)

{
 "Device": {
   "display": {
     "background": "0"
     "background_theme": "2"
   }
 }
}

For Slide Show mode, set both background and background_theme to "2".

Authorizations:
SessionAuth
Request Body schema: application/json
required

Device collection and resource data for updating homescreen display

required
object

Collection of devices to update

required
object

Collection of resource data to apply to devices

Responses

Request samples

Content type
application/json
{
  • "DeviceCollection": {
    },
  • "ResourceDataCollection": {
    }
}

List Device Types

This API is used to list Suprema devices recorded on BioStar X.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/device_types \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

View Device(s) Based on Enrollment Type

This API is used to view device(s) based on its enrollment capabilities.

Authorizations:
SessionAuth
query Parameters
type
integer

Device enrollment type. 0=All, 1=Finger, 2=CSN, 3= Smart, 4=Face, 5=Visual Face

Responses

Request samples 

curl --request GET \
  --url 'https://{baseurl}/api/devices/enrollment?type=0' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

List Added Device(s) with Criteria

This API is used to list devices with parameters to filter the result. It is required to at least put {} for the API to run correctly.

Authorizations:
SessionAuth
Request Body schema: application/json
limit
integer

Limit the number of responses according to the specified value

exclude_device_type_id
integer

Exclude device to show on the response according to the device type id specified

order_by
string

Order the response according to the specified value

Responses

Request samples

Content type
application/json
{
  • "limit": 0,
  • "exclude_device_type_id": 254,
  • "order_by": "id:false"
}

Response samples

Content type
application/json
{
  • "status": 1,
  • "user_sync_status": 0
}

View Device Configuration

This API is used to view device's configuration.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 543720368

ID of the device which information will be viewed

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/devices/543720368/config \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

View User Statistics in a Device

This API is used to view user statistics in a device.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 538152248

ID of the device which will be viewed

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/devices/538152248/discover_userdata \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

View Device Capabilities

This API is used to list device's capabilities such as fingerprint, wifi, etc.

Authorizations:
SessionAuth
Request Body schema: application/json
object (DeviceCollectionID)
Array of objects
Array
id
required
integer

ID of the device

Responses

Request samples

Content type
application/json
{
  • "DeviceCollection": {
    }
}

Sync Device Data

This API is used to sync device's data with BioStar X.

Authorizations:
SessionAuth
query Parameters
clean
boolean

Toggle true to delete data on the device before sync process.

Request Body schema: application/json
object (DeviceCollectionID)
Array of objects
Array
id
required
integer

ID of the device

Responses

Request samples

Content type
application/json
{
  • "DeviceCollection": {
    }
}

Unlock Device

This API is used to set a device state to unlocked.

Manually unlocked device state will persist until it's normalized.

Authorizations:
SessionAuth
Request Body schema: application/json
object (DeviceCollectionID)
Array of objects
Array
id
required
integer

ID of the device

Responses

Request samples

Content type
application/json
{
  • "DeviceCollection": {
    }
}

Search Devices (TCP)

This API is used to view device's information using TCP.

This API only works for devices which haven't been added to BioStar X.

Authorizations:
SessionAuth
Request Body schema: application/json
object
object
ip
required
string

IP of the device

device_port
required
integer

Port of the device

Responses

Request samples

Content type
application/json
{
  • "Device": {
    }
}

Search Devices (UDP)

This API is used to search devices through UDP.

Authorizations:
SessionAuth
Request Body schema: application/json
object
timeout
integer

Search devices until the specified second reached

with_rs485
boolean

Toggle to find device(s) with RS485

hide_known_devices
boolean

Toggle to show device(s) which already known (added to BioStar X) or not.

Responses

Request samples

Content type
application/json
{
  • "UdpSearchOption": {
    }
}

View Device IP Settings

This API is used to get the IP settings of a device which have not been added to BioStar X.

Authorizations:
SessionAuth
Request Body schema: application/json
object
id
required
integer

ID of the device which the IP setting will be viewed.

Responses

Request samples

Content type
application/json
{
  • "Device": {
    }
}

Update Device IP Settings

This API is used to update IP settings on device which have not been added to BioStar X.

It is required to fill in the id parameter with the id of the device which the IP settings will be updated.

Fill in the required value on the respective parameters and remove those which is not required.

Authorizations:
SessionAuth
Request Body schema: application/json
object
id
required
integer

ID of the device which will be updated.

object
object

Responses

Request samples

Content type
application/json
{
  • "Device": {
    }
}

Connect Device

This API is used to connect a device which have been disconnected.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 542353521

ID of the device which will be connected

Responses

Request samples 

curl --request POST \
  --url https://{baseurl}/api/devices/542353521/connect \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Disconnect Device

This API is used to disconnect a device connection from BioStar X.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 542353521

ID of the device which will be disconnected

Responses

Request samples 

curl --request POST \
  --url https://{baseurl}/api/devices/542353521/disconnect \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Find Wiegand

This API is used to find wiegand device attached to master device.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 544140034

ID of the master device

Responses

Request samples 

curl --request POST \
  --url https://{baseurl}/api/devices/544140034/discover_wiegand \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Find Slave Device

This API is used to find slave device attached to a master device.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 544140034

ID of the master device

Responses

Request samples 

curl --request POST \
  --url https://{baseurl}/api/devices/544140034/discover \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Clear Device Alarm

This API is used to clear alarm from a device.

Authorizations:
SessionAuth
Request Body schema: application/json
object
Array of objects
Array
id
integer

Responses

Request samples

Content type
application/json
{
  • "DeviceCollection": {
    }
}

View Total User on a Device

This API is used to view user data summary from a device.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 543308153
query Parameters
limit
integer
Example: limit=20

Limit the number of response's records by the specified value. (Default=50)

page
integer

Filter the response based on the specified page number. (Default=1)

Responses

Request samples 

curl --request GET \
  --url 'https://{baseurl}/api/devices/543308153/users?limit=20&page=0' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Delete User from a Device

This API is used to delete user data on a device.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 543720368

ID of the device which the user data will be deleted

query Parameters
id
string
Example: id=*

ID of the user which will be deleted. Use (*) for all user.

Responses

Request samples 

curl --request DELETE \
  --url 'https://{baseurl}/api/devices/543720368/users?id=*' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Export User Data from a Device to BioStar X

This API is used to export user data from a device to BioStar X.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 538152248

ID of the device which the user data will be uploaded to.

query Parameters
id
integer
Example: id=44004

ID of the user which will be uploaded. Use plus symbol ( + ) to separate multiple user ID, ex: 1+2+3.

Responses

Request samples 

curl --request POST \
  --url 'https://{baseurl}/api/devices/538152248/users/export?id=44004' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "UserCollection": {
    },
  • "DeviceResponse": {
    },
  • "Response": {}
}

View RS485 Devices

This API is used to list devices which connected using RS-485.

Authorizations:
SessionAuth
path Parameters
dev_id
required
integer
Example: 542071155

ID of the device which will be viewed

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/devices/rs485/542071155 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Door Groups

View All Door Groups

This API is used to view all available door groups. It is required to put {} on the body parameter to run the API successfully.

Authorizations:
SessionAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

View All Door Groups (Sort)

This API is used to view all door groups while sorting the response using available fields.

Authorizations:
SessionAuth
Request Body schema: application/json
order_by
string

Sort the response records by value which inputted on this parameter Available fields: id, name, depth

Responses

Request samples

Content type
application/json
{
  • "order_by": "depth:false"
}

Create Door Group

This API is used to create door groups. Known issue:

  • Duplicate group name within one parent group

  • Depth value not within 1-8

  • Using parent_id which doesn't exist will result in success but the created group will not be visible.

  • Using empty value on name will success creating a door with name: undefined. This door can't be deleted. To resolve this, update the door name then it will be able to be deleted.

Authorizations:
SessionAuth
Request Body schema: application/json
object
required
object
depth
required
integer

Depth of the group in accordance with the parent group (parent depth+1). Value between 1 to 8.

name
required
string

Name of the group. Do not put empty value on this parameter. Max 48 characters.

Responses

Request samples

Content type
application/json
{
  • "DoorGroup": {
    }
}

Delete Door Group

This API is used to delete door group.

Put the door's ID on the id parameters of this API to delete door.

Note:

  • Deleting parent group will also delete child group

  • Deleting groups with door(s) will also remove door(s) under that group. This will consequently remove doors from Access Levels

  • Can't delete groups with parent_id which doesn't exist

  • Can't delete groups with undefined name

Authorizations:
SessionAuth
query Parameters
id
integer
Example: id=33

ID of the door which will be deleted

Responses

Request samples 

curl --request DELETE \
  --url 'https://{baseurl}/api/door_groups?id=33' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Update Door Group

This API is used to update door group.

Put the door's ID on the id parameters of this API to update door.

Note:

  • When parent_id updated, any child group will follow the parent group
Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 42
Request Body schema: application/json
object
name
string

Name of the group. Do not put empty value on this parameter. Max 48 characters.

object

Responses

Request samples

Content type
application/json
{
  • "DoorGroup": {
    }
}

Doors

View a Door Details

This API is used to view a Door details.

Authorizations:
SessionAuth
path Parameters
id
required
string
Example: 1

ID of the door which will be viewed

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/doors/1 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Update a Door

This API is used to update a Door details.

Leave the values to be edited, and remove everything else.

Authorizations:
SessionAuth
path Parameters
id
required
string

ID of the door which will be updated

Request Body schema: application/json
object (Door)
name
string

Name of the door

description
string

Description of the door

object
open_timeout
integer

Configure the maximum allowed time for the door to remain open.

open_duration
integer

Set the duration for which the door will remain open after a user authentication is completed. When the authentication is successful, the relay will be activated for the set time. When this time elapses, the relay no longer sends the signal to the door. Open Time may vary depending on the type of door lock used.

open_once
boolean

Lock when door is closed. When the door sensor detects that the door is closed, the door is locked. Set this option to false if unconditional_lock is true. Set true to enable this parameter. (Default= false)

unconditional_lock
boolean

Use Automatic Door. When using an automatic door as an entrance door, a relay can operate regardless of the status of a door sensor. Set this option as false if open_once is set to true.

object
object
object

Responses

Request samples

Content type
application/json
{
  • "Door": {
    }
}

View All Doors

This API is used to view Doors which is recorded on BioStar 2 database.

Authorizations:
SessionAuth
query Parameters
limit
integer

Limit the number of records according with the value specified

order_by
string
Example: order_by=id:true

Sort the records based on the id, toggle true/false to switch asceding/descending

Responses

Request samples 

curl --request GET \
  --url 'https://{baseurl}/api/doors?limit=0&order_by=id%3Atrue' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Create a Door

This API is used to create a door.

Authorizations:
SessionAuth
Request Body schema: application/json
object (Door)
name
string

Name of the door

description
string

Description of the door

object
open_timeout
integer

Configure the maximum allowed time for the door to remain open.

open_duration
integer

Set the duration for which the door will remain open after a user authentication is completed. When the authentication is successful, the relay will be activated for the set time. When this time elapses, the relay no longer sends the signal to the door. Open Time may vary depending on the type of door lock used.

open_once
boolean

Lock when door is closed. When the door sensor detects that the door is closed, the door is locked. Set this option to false if unconditional_lock is true. Set true to enable this parameter. (Default= false)

unconditional_lock
boolean

Use Automatic Door. When using an automatic door as an entrance door, a relay can operate regardless of the status of a door sensor. Set this option as false if open_once is set to true.

object
object
object

Responses

Request samples

Content type
application/json
{
  • "Door": {
    }
}

Delete Door(s)

This API is used to delete Door(s).

Authorizations:
SessionAuth
query Parameters
id
string
Example: id=1

ID of the door which will be deleted. To delete multiple doors, separate the IDs with space.

Responses

Request samples 

curl --request DELETE \
  --url 'https://{baseurl}/api/doors?id=1' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

View All Doors v2

This API is used to view door records from BioStar X.

It is required to at least put {} on the body for the API to run correctly.

Authorizations:
SessionAuth
Request Body schema: application/json
limit
integer

Limit the number of records on the response according to the value specified

search_text
string

Find records with the specified string

door_group_id
integer

Limit the records to only those with door_group_id specified

order_by
string

Sort the response by stated value (id, door_group_id.name). Toggle boolean to switch ascending or descending.

Responses

Request samples

Content type
application/json
{
  • "limit": 25,
  • "search_text": "",
  • "door_group_id": 1,
  • "order_by": "door_group_id.name:true"
}

View Door Status

This API is used to view various door status information such as the door status, relay status, alarm and last event.

  • Fire alarm unlocked: A state where the door designated as a fire alarm zone is unlocked because a fire has broken out.
  • Manual Lock: A state where the door is locked because the administrator has locked it manually.
  • Manual Unlock: A state where the door is unlocked and able to enter without an authentication because the administrator has unlocked it manually.
  • Schedule Locked: A state where the door is locked by the schedule that has been set.
  • Schedule Unlocked: A state where the door is unlocked by the schedule that has been set.
  • Normal: A state where a user can enter the door after an authentication.
Authorizations:
SessionAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "monitoring_permission": true
}

Clear Door Alarm

This API is used to clear alarms of all doors. If an alarm is
set in the Zone, the alarm may be continuously output even if the door alarm is released.

Authorizations:
SessionAuth
Request Body schema: application/json
object (DoorCollection)
Array of objects
Array
id
integer

ID of the door

Responses

Request samples

Content type
application/json
{
  • "DoorCollection": {
    }
}

Clear Anti PassBack: Specific User(s)

This example shows how to clear APB for specific user(s).

Authorizations:
SessionAuth
Request Body schema: application/json
object (TimedAntiPassBackConfig)
object
target
string

User target, all users or single user.

Responses

Request samples

Content type
application/json
{
  • "AntiPassBackConfig": {
    },
  • "target": "users:,[object Object],[object Object]"
}

Manual Lock Door

This API is used to lock a door manually. If you set the state to Manual Lock, the door will have remained inaccessible even if a user authentication succeeded.

Authorizations:
SessionAuth
Request Body schema: application/json
object (DoorCollection)
Array of objects
Array
id
integer

ID of the door

Responses

Request samples

Content type
application/json
{
  • "DoorCollection": {
    }
}

Manual Unlock Door

This API is used to unlock a door manually. If you set the state to Manual Unlock, the door will have remained accessible even if a user does not authenticate.

Authorizations:
SessionAuth
Request Body schema: application/json
object (DoorCollection)
Array of objects
Array
id
integer

ID of the door

Responses

Request samples

Content type
application/json
{
  • "DoorCollection": {
    }
}

Release Manual Lock/Unlock

This API is used to release the manual lock or manual unlock set by the administrator.

Authorizations:
SessionAuth
Request Body schema: application/json
object (DoorCollection)
Array of objects
Array
id
integer

ID of the door

Responses

Request samples

Content type
application/json
{
  • "DoorCollection": {
    }
}

Clear Timed APB

This API is used to clear Timed APB access record.

Authorizations:
SessionAuth
Request Body schema: application/json
object (TimedAntiPassBackConfig)
object
target
string

User target, all users or single user.

Responses

Request samples

Content type
application/json
{
  • "TimedAntiPassBackConfig": {
    },
  • "target": "users:,[object Object]"
}

Response samples

Content type
application/json
{}

Open Door

This API is used to open a door.

Authorizations:
SessionAuth
Request Body schema: application/json
object (DoorCollection)
Array of objects
Array
id
integer

ID of the door

Responses

Request samples

Content type
application/json
{
  • "DoorCollection": {
    }
}

View Doors with RS485

This API is used to list doors which use devices that connected to the system using RS485.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 1

ID of the door which will be viewed

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/doors/rs485/1 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Retrieve Door Tree

Retrieves the hierarchical structure of door groups and doors, including device and status information.

This endpoint is commonly used to populate door monitoring trees, access control dashboards, or group-based door management UIs.

Authorizations:
SessionAuth
Request Body schema: application/json
root_id
integer

The ID of the root door group to start searching from.

max_recursion_depth
integer

Maximum depth of recursive traversal through child groups.

collapsed_node_ids
Array of integers

Fill with child group IDs to set is_collapsed parameter on response to true.

Responses

Request samples

Content type
application/json
{
  • "root_id": 1,
  • "max_recursion_depth": 7,
  • "collapsed_node_ids": {
    }
}

Elevator Groups

Create Elevator Group

This API is used to create elevator group.

Authorizations:
SessionAuth
Request Body schema: application/json
object
required
object
isElevatorGroups
required
boolean

Marker for elevator group

depth
required
integer

Depth of the group in accordance with the parent group (parent depth+1). Value between 1 to 8.

sync_device_groups
Array of objects

Synchronized device groups

sync_devices
Array of objects

Synchronized devices

inherited
required
boolean

Inheritance marker of the group

iconCls
string

Icon class for the elevator group

text
string

Text for the elevator group

name
required
string

Name of the elevator group. Up to 48 characters may be entered for an elevator group name.

Responses

Request samples

Content type
application/json
{
  • "ElevatorGroup": {
    }
}

List Elevator Group

This API is used to list elevator groups recorded in BioStar X.

It is required to at least put {} on body for the API to run correctly.

Authorizations:
SessionAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

List Elevator Group with Criteria & Permission

This API is used to view elevator groups with criteria and permissions.

Authorizations:
SessionAuth
Request Body schema: application/json
order_by
string

Sort the response records by value which inputted on this parameter Available fields: id, name, depth

Responses

Request samples

Content type
application/json
{
  • "order_by": "depth:false"
}

Update Elevator Group

This API is used to update elevator group.

Up to 48 characters may be entered for an elevator group name.

Authorizations:
SessionAuth
path Parameters
id
required
string

ID of the elevator group which will be updated

Request Body schema: application/json
object
required
object
isElevatorGroups
required
boolean

Marker for elevator group

depth
required
integer

Depth of the group in accordance with the parent group (parent depth+1). Value between 1 to 8.

sync_device_groups
Array of objects

Synchronized device groups

sync_devices
Array of objects

Synchronized devices

inherited
required
boolean

Inheritance marker of the group

iconCls
string

Icon class for the elevator group

text
string

Text for the elevator group

name
required
string

Name of the elevator group. Up to 48 characters may be entered for an elevator group name.

Responses

Request samples

Content type
application/json
{
  • "ElevatorGroup": {
    }
}

Delete Elevator Group

This API is used to delete elevator group.

Deleting a group deletes all elevators in the group.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 5

ID of the elevator group which will be deleted

Responses

Request samples 

curl --request DELETE \
  --url https://{baseurl}/api/v2/elevator_groups/5 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Elevators

Create Elevator

This API is used to create elevator.

The minimum values is name, elevator_group_id(id, name), reader_devices(id, name), control_device_id(id, name, device_type_id), floors(name, order, elevator_device_id, relay_index). The rest can be removed.

Controller - control_device_id

Select a device that controls the elevator access permission.

  • Only a master device can be selected.

  • You can select it from the list of registered devices. Reader - reader_devices Select a device you intend to use for authentication.

  • You can select a device among the master device, slave device, and Wiegand device.

  • You can select up to 4 readers.

  • OM-120 cannot be set as the reader.

Module - module_devices

Select OM-120 to control the elevator button relay.

  • Only OM-120 can be selected.

Total Number of Floors - floors

Enter the total number of floors that you can move using the elevator.

  • Up to 192 floors can be entered.
Authorizations:
SessionAuth
Request Body schema: application/json
object (Elevator)
name
string

Name of the elevator. Max 48 characters.

description
string

Description of the elevator. Max 255 characters.

object
Array of objects

List of reader devices.

object
Array of objects

List of floors in the elevator.

Array of objects

List of module devices.

trigger_actions
Array of objects

List of trigger actions.

active_timeout
string

Active timeout duration.

object
object

Responses

Request samples

Content type
application/json
{
  • "Elevator": {
    }
}

Delete Elevator

This API is used to delete elevator.

Authorizations:
SessionAuth
query Parameters
id
string

ID of the elevator which will be deleted

Responses

Request samples 

curl --request DELETE \
  --url 'https://{baseurl}/api/elevators?id=SOME_STRING_VALUE' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

List Elevators

This API is used to list elevators recorder in BioStar X

It is required to at least put {} for the API to run correctly.

Authorizations:
SessionAuth
Request Body schema: application/json
limit
integer

Limit the response records by the number specified on this parameter

search_text
string

Search records based on the value specified

elevator_group_id
integer

List elevators with specified group id

order_by
string

Sort response by specified value

Responses

Request samples

Content type
application/json
{
  • "limit": 50,
  • "search_text": "Odds",
  • "elevator_group_id": 1,
  • "order_by": "elevator_group_id:false"
}

View an Elevator Details

This API is used to view an elevator details.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 32770

ID of the elevator which will be viewed

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/elevators/32770 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Update Elevator

This API is used to update an elevator configuration.

Leave values which will be edited and remove everything else.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 32771

ID of the elevator which will be updated

Request Body schema: application/json
object (Elevator)
name
string

Name of the elevator. Max 48 characters.

description
string

Description of the elevator. Max 255 characters.

object
Array of objects

List of reader devices.

object
Array of objects

List of floors in the elevator.

Array of objects

List of module devices.

trigger_actions
Array of objects

List of trigger actions.

active_timeout
string

Active timeout duration.

object
object

Responses

Request samples

Content type
application/json
{
  • "Elevator": {
    }
}

View Elevator(s) Status

This API is used to view elevator status.

Authorizations:
SessionAuth
Request Body schema: application/json
object (ElevatorCollection)
Array of objects
Array
id
required
integer

ID of the elevator.

Responses

Request samples

Content type
application/json
{
  • "ElevatorCollection": {
    }
}

Manual Lock Elevator

This API is used to lock elevator access to single/multiple floor manually. If you set the state to Manual Lock, the elevator will have remained inaccessible even if a user authenticatation succeeded.

floors:order correlates with order on GET /api/elevators/:id or with floor_id:index on POST /api/elevators/status

Authorizations:
SessionAuth
Request Body schema: application/json
object (ElevatorCollectionFloor)
Array of objects
Array
id
required
integer

ID of the elevator.

object

Responses

Request samples

Content type
application/json
{
  • "ElevatorCollection": {
    }
}

Manual Unlock Elevator

This API is used to unlock an elevator manually. If you set the state to Manual Unlock, the elevator will have remained accessible even if a user does not authenticate.

floors:order correlates with order on GET /api/elevators/:id or with floor_id:index on POST /api/elevators/status

Authorizations:
SessionAuth
Request Body schema: application/json
object (ElevatorCollectionFloor)
Array of objects
Array
id
required
integer

ID of the elevator.

object

Responses

Request samples

Content type
application/json
{
  • "ElevatorCollection": {
    }
}

Release Elevator Manual Lock/Unlock

This API is used to release the manual lock or manual unlock set by the administrator. When running this API, it will also reset the status caused by POST /api/elevators/open floors:order correlates with order on GET /api/elevators/:id or with floor_id:index on POST /api/elevators/status

Authorizations:
SessionAuth
Request Body schema: application/json
object (ElevatorCollectionFloor)
Array of objects
Array
id
required
integer

ID of the elevator.

object

Responses

Request samples

Content type
application/json
{
  • "ElevatorCollection": {
    }
}

Open Elevator Floor(s)

This API is used to open a floor.

Will only works if the floor status is clear/default (not manually locked/unlocked or there's active alarm)

floors:order correlates with order on GET /api/elevators/:id or with floor_id:index on POST /api/elevators/status

Authorizations:
SessionAuth
Request Body schema: application/json
object (ElevatorCollectionFloor)
Array of objects
Array
id
required
integer

ID of the elevator.

object

Responses

Request samples

Content type
application/json
{
  • "ElevatorCollection": {
    }
}

Clear Elevator Alarm

This API is used to clear alarms of all doors. If an alarm is

set in the Zone, the alarm may be continuously output even if the elevator alarm is released.

Authorizations:
SessionAuth
Request Body schema: application/json
object (ElevatorCollection)
Array of objects
Array
id
required
integer

ID of the elevator.

Responses

Request samples

Content type
application/json
{
  • "ElevatorCollection": {
    }
}

Firmware

Update Firmware

This API is used to update a device's firmware.

Firmware file need to be placed on [BioStar X Install Path]\firmware folder.

Use /api/device_types to find device_type and device_type_id, find the device's name and get the id for the parameters value.

Authorizations:
SessionAuth
Request Body schema: application/json
object
object

Responses

Request samples

Content type
application/json
{
  • "FirmwareFile": {
    },
  • "DeviceCollection": {
    }
}

View Firmwares Information

This API is used to view firmwares information which is placed on folder [BioStar X Install Path]\firmware.

Response Information Table

Device Type Value
BS2_DEVICE_TYPE_UNKNOWN 0
BIOENTRY_PLUS 1
BIOENTRY_W 2
BIOLITE_NET 3
XPASS 4
XPASS_S2 5
SECURE_IO_2 6
DOOR_MODULE_20 7
BIOSTATION_2 8
BIOSTATION_A2 9
FACESTATION_2 10
IO_DEVICE 11
BIOSTATION_L2 12
BIOENTRY_W2 13
CORESTATION_40 14
OUTPUT_MODULE 15
INPUT_MODULE 16
BIOENTRY_P2 17
BIOLITE_N2 18
XPASS2 19
NOT USED 20
BIOENTRY_R2 21
XPASS_D2 22
DOOR_MODULE_21 23
XPASS_D2_KEYPAD 24
FACELITE 25
XPASS2_KEYPAD 26
XPASS_D2_REV 27
XPASS_D2_KEYPAD_REV 28
FACESTATION_F2_FP 29
FACESTATION_F2 30
XSTATION_2_QR 31
XSTATION_2 32
IM_120 33
XSTATION_2_FP 34
BIOSTATION_3 35
3RD_OSDP_DEVICE 36
3RD_OSDP_IO_DEVICE 37
BIOSTATION_2A 38
UZ_OSDP_MODULE 39
UZ_OSDP_DOOR_HANDLE 40
UZ_OSDP_DOOR_KNOB 41
BIOENTRY_W3 42
Card Model Value
OMPW 0
OIPW 1
OEPW 2
OHPW 3
ODPW 4
OAPW 5
ODSPW 6
PMPW 20
PIPW 21
PEPW 22
PHPW 23
PDPW 24
PAPW 25
PDSPW 26
ALL 30

Model Code

Code Position Description
O Front Optical FP Sensor
P Front PIV Certified Optical FP Sensor
A Middle All Cards
M Middle Mifare & DESFire
I Middle iClass
E Middle EM
H Middle HID
D Middle Dual Frequency (Mifare/DESFire [13.56 MHz], EM [125 kHz])
DS Middle Dual Frequency with SAM Card Slot
P End PoE
W End WiFi

Note:

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/firmwares \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Floor Levels

View Floor Levels

This API is used to view floor levels recorded on BioStar X.

Authorizations:
SessionAuth
query Parameters
limit
string

Limit the number of responses by n records. Remove this parameter to view all.

offset
string

Offset the response shown by n records.

order_by
string
Example: order_by=id:false

Order the response result either ascending or descending

Responses

Request samples 

curl --request GET \
  --url 'https://{baseurl}/api/floor_levels?limit=SOME_STRING_VALUE&offset=SOME_STRING_VALUE&order_by=id%3Afalse' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Create Floor Levels

This API is used to create floor level.

You can configure the floor access privileges by using elevators and floor information.

Known errors:

  • Duplicate name
Authorizations:
SessionAuth
Request Body schema: application/json
object (FloorLevel)
name
string

Name of the floor level

description
string

Description of the floor level

Array of objects

Responses

Request samples

Content type
application/json
{
  • "FloorLevel": {
    }
}

View a Floor Level Detail

This API is used to view the details of a floor level.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 32769

ID of the floor level which will be viewed

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/floor_levels/32769 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Update Floor Levels

This API is used to update floor level. Known errors:

  • Duplicate name
Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 32776

ID of the floor level which will be updated

Request Body schema: application/json
object (FloorLevel)
name
string

Name of the floor level

description
string

Description of the floor level

Array of objects

Responses

Request samples

Content type
application/json
{
  • "FloorLevel": {
    }
}

Delete Floor Level

This API is used to delete floor levels.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 32775

ID of the floor level which will be deleted

Responses

Request samples 

curl --request DELETE \
  --url https://{baseurl}/api/floor_levels/32775 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Schedules

View Schedules

This API is used to view all schedules recorded on BioStar X.

Authorizations:
SessionAuth
query Parameters
limit
string

Limit the number of responses by n records. Remove this parameter to view all.

offset
string

Offset the response shown by n records.

Responses

Request samples 

curl --request GET \
  --url 'https://{baseurl}/api/schedules?limit=SOME_STRING_VALUE&offset=SOME_STRING_VALUE' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Create Schedule (Daily)

This API example shows how to create daily schedule.

Authorizations:
SessionAuth
Request Body schema: application/json
object (Schedule)
name
string

Name of the schedule

description
string

Description of the schedule

Array of objects

Daily schedules configuration

holiday_schedules
Array of objects

Holiday schedules used

days_of_iteration
integer

Repeat schedule every N days

start_date
string <date-time>

Enable schedule from specified date

use_daily_iteration
boolean

Specify schedule weekly or daily. False for weekly

Responses

Request samples

Content type
application/json
{
  • "Schedule": {
    }
}

View a Schedule Detail

This API is used to view a schedule detail recorded on BioStar X.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 2

ID of the schedule which will be viewed

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/schedules/2 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Delete Schedules

This API is used to delete schedules recorded on BioStar X.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 5

ID of the schedule which will be deleted

Responses

Request samples 

curl --request DELETE \
  --url https://{baseurl}/api/schedules/5 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Update a Schedule

This API is used to update a schedule.

Authorizations:
SessionAuth
path Parameters
id
required
string

ID of the schedule which will be updated

Request Body schema: application/json
object (Schedule)
name
string

Name of the schedule

description
string

Description of the schedule

Array of objects

Daily schedules configuration

holiday_schedules
Array of objects

Holiday schedules used

days_of_iteration
integer

Repeat schedule every N days

start_date
string <date-time>

Enable schedule from specified date

use_daily_iteration
boolean

Specify schedule weekly or daily. False for weekly

Responses

Request samples

Content type
application/json
{
  • "Schedule": {
    }
}

Holiday Groups

View Holiday Groups

This API is used to view all holiday groups recorded on BioStar X.

Authorizations:
SessionAuth
query Parameters
limit
string

Limit the number of responses by n records. Remove this parameter to view all.

offset
string

Offset the response shown by n records.

Responses

Request samples 

curl --request GET \
  --url 'https://{baseurl}/api/holiday_groups?limit=SOME_STRING_VALUE&offset=SOME_STRING_VALUE' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Create Holiday Group

This API is used to create holiday groups on BioStar X.

Authorizations:
SessionAuth
Request Body schema: application/json
object (HolidayGroup)
name
required
string

Name of the holiday group

description
string

Description of the holiday group

Array of objects

List of holidays in the group

Responses

Request samples

Content type
application/json
{
  • "HolidayGroup": {
    }
}

Update Holiday Group

This API is used to update holiday groups on BioStar X.

Authorizations:
SessionAuth
path Parameters
id
required
string

ID of the holiday group which will be updated.

Request Body schema: application/json
object (HolidayGroup)
name
required
string

Name of the holiday group

description
string

Description of the holiday group

Array of objects

List of holidays in the group

Responses

Request samples

Content type
application/json
{
  • "HolidayGroup": {
    }
}

Delete Holiday Group

This API is used to delete holiday group.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 1

ID of the holiday group which will be deleted

Responses

Request samples 

curl --request DELETE \
  --url https://{baseurl}/api/holiday_groups/1 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Trigger Actions

View Trigger Actions

This API is used to view all Trigger & Actions.

Authorizations:
SessionAuth
query Parameters
limit
string

Limit the number of responses by n records. Remove this parameter to view all.

offset
string

Offset the response shown by n records.

Responses

Request samples 

curl --request GET \
  --url 'https://{baseurl}/api/trigger_actions?limit=SOME_STRING_VALUE&offset=SOME_STRING_VALUE' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Create Trigger Actions (Zone)

You can set the device or BioStar X to do a specific operation when a specific event has occurred at the devices, doors and zones.

Authorizations:
SessionAuth
Request Body schema: application/json
object (TriggerAction)
name
string

Name of the Trigger & Action

priority
integer

Priority index of the Trigger & Action

object
object
object

Responses

Request samples

Content type
application/json
{
  • "TriggerAction": {
    }
}

Update Trigger Actions

This API is used to update Trigger/Actions.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 2

ID of the Trigger & Actions which will be updated.

Request Body schema: application/json
object (TriggerAction)
name
string

Name of the Trigger & Action

priority
integer

Priority index of the Trigger & Action

object
object
object

Responses

Request samples

Content type
application/json
{
  • "TriggerAction": {
    }
}

Delete Trigger Actions

This API is used to view all Trigger & Actions.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 2

ID of the Trigger & Action which will be deleted.

Responses

Request samples 

curl --request DELETE \
  --url https://{baseurl}/api/trigger_actions/2 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Create Multiple Trigger Actions

This API is used to create multiple trigger actions.

Authorizations:
SessionAuth
Request Body schema: application/json
object (MultipleTriggerAction)
name
required
string

Name of the Trigger & Action

priority
required
integer

Priority index of the Trigger & Action

required
object
is_quick_action
string

Fill with character "Y" or "N". This parameter used to describe that the Trigger & Action can be use as a Quick Action

required
object
required
object

Responses

Request samples

Content type
application/json
{
  • "TriggerAction": {
    }
}

Response samples

Content type
application/json
{
  • "TriggerAction": {
    },
  • "Response": {}
}

Delete Multiple Trigger Actions Copy

This API is used to delete multiple trigger actions by ID.

Authorizations:
SessionAuth
query Parameters
id
string

Trigger and Action ID(s). Delimit each ID by using plus symbol (+; ex: 1+2+3)

Responses

Request samples 

curl --request DELETE \
  --url 'https://{baseurl}/api/multiple/trigger_actions?id=SOME_STRING_VALUE' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{}

Update Multiple Trigger Actions

This API is used to update multiple trigger actions by ID.

Authorizations:
SessionAuth
path Parameters
id
required
string

Trigger & Action's ID

Request Body schema: application/json
object (MultipleTriggerAction)
name
required
string

Name of the Trigger & Action

priority
required
integer

Priority index of the Trigger & Action

required
object
is_quick_action
string

Fill with character "Y" or "N". This parameter used to describe that the Trigger & Action can be use as a Quick Action

required
object
required
object

Responses

Request samples

Content type
application/json
{
  • "TriggerAction": {
    }
}

Response samples

Content type
application/json
{}

View Multiple Trigger Actions

This API is used to view trigger actions by ID.

Authorizations:
SessionAuth
path Parameters
id
required
string

ID of the Trigger and Action which will be viewed.

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/multiple/trigger_actions/{id} \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "TriggerAction": {
    },
  • "Response": {}
}

Quick Action

Trigger Quick Action by ID

This API is used to trigger Quick Action by ID.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 2

ID of the Quick Action which will be viewed.

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/quick_action/2 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{}

View Trigger Action with Quick Action Enabled

This API is used to fetch Trigger Actions with Quick Action status enabled.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/v2/quick_action/alarm_set \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "alarm_sets": {
    },
  • "Response": {}
}

View All Quick Action

This API is used to fetch all configured quick actions.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/v2/quick_action \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "quick_action": [
    ],
  • "Response": {}
}

Save/Update/Delete Quick Action

This API is used to save/update/delete Quick Action.

To CREATE: Fill in all Quick Action(s) parameter (excluding ID). It is possible to create multiple Quick Action in one payload.
In the case creating new one while there's existing Quick Action(s), the new one doesn't require ID while the existing require it.

To DELETE: Fill in all Quick Action(s) parameter (including ID). Input all Quick Action(s) besides the one that will be deleted. To delete all, simply send an empty payload.

To UPDATE: Fill in all Quick Action(s) parameter (including ID). Input all Quick Action(s) including any which will not be updated.

Authorizations:
SessionAuth
Request Body schema: application/json
Array of objects
Array
name
string

Quick Action name.

description
string

Quick Action description.

confirm_before_run
string

Confirmation before run (Y=enabled, N=disabled).

operator_level_ids
Array of integers

List Operator Level ID(s) which allowed to run the Quick Action.

trigger_action_ids
Array of integers

List Trigger & Action ID(s) which will be executed when Quick Action triggered.

order_number
integer

Quick Action order number.

id
integer

Quick Action's ID. Will be generated after Quick Action created. Required to be filled when update or adding.

Responses

Request samples

Content type
application/json
{
  • "QuickActions": {
    }
}

Response samples

Content type
application/json
{}

View All Quick Action by Permission ID

This API is used to fetch Quick Actions by Permission ID.

Authorizations:
SessionAuth
path Parameters
id
required
string

Permission ID of the Quick Action which will be viewed.

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/v2/quick_action/permission/{id} \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "quick_action": [
    ],
  • "Response": {}
}

View Quick Action by ID

This API is used to fetch Quick Action information by ID.

Authorizations:
SessionAuth
path Parameters
id
required
string

ID of the Quick Action which will be viewed.

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/v2/quick_action/{id} \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "quick_action": [
    ],
  • "Response": {}
}

Setting

Update BioStar X Settings

This API is used to update various BioStar X settings.

Authorizations:
SessionAuth
Request Body schema: application/json
object
session_timeout
string

Set a session timeout period. If there is no activity on BioStar X for the set time after logging in, the session is logged out automatically. This value represents second.

server_port
string

Port number that BioStar X uses.

object (ServerMatching)
user_sync_method
integer

Automatic user synchronization setting. Need to be combined with user_by_device_sync_method to use.

  • Not Used : user_sync_method : "0" & user_by_device_sync_method:"0"
  • All Devices : user_sync_method : "1" & user_by_device_sync_method:"0"
  • All Devices (Including user update from device) : user_sync_method : "1" & user_by_device_sync_method:"1"
  • Specific Devices (Only devices belonging to the access group) : user_sync_method : "3" & user_by_device_sync_method:"0"
user_by_device_sync_method
integer

See user_sync_method

log_sync_method
integer

Toggle value to 1 to set the Log Upload to manual, and 0 for automatic.

Responses

Request samples

Content type
application/json
{
  • "BioStar": {
    }
}

Create Custom Field(s)

This API is used to create user custom field(s) on BioStar X.

Authorizations:
SessionAuth
Request Body schema: application/json
object (CustomFieldCollection)
Array of objects
Array
order
required
integer

Unique

name
required
string

Unique

type
required
integer

0: Text Input, 1: Number Input, 2: Combo Box, 3: File Upload.

data
string

Combo Box options, use (;) as separator of each value.

enable
boolean

Toggle true to enable custom field.

Responses

Request samples

Content type
application/json
{
  • "CustomFieldCollection": {
    }
}

Response samples

Content type
application/json
{}

Update Custom Field(s)

This example shows how to update custom field.

Note:

  • The main difference between Create and Updating custom field(s) is on Update, ID needs to be specified.
  • To get the custom field's ID, use GET /api/setting/custom_fields
  • When updating a custom field when there are more than 1 custom fields, the custom fields which are not updated need to be specified since the API is using PUT method.
Authorizations:
SessionAuth
Request Body schema: application/json
object (CustomFieldCollection)
Array of objects
Array
order
required
integer

Unique

name
required
string

Unique

type
required
integer

0: Text Input, 1: Number Input, 2: Combo Box, 3: File Upload.

data
string

Combo Box options, use (;) as separator of each value.

enable
boolean

Toggle true to enable custom field.

Responses

Request samples

Content type
application/json
{
  • "CustomFieldCollection": {
    }
}

Delete Custom Field(s)

This API is used to delete user custom fields which recorded on BioStar X.

Authorizations:
SessionAuth
query Parameters
id
string

ID of the Custom Field(s) which will be deleted. Use space ( ) as separator for multiple IDs.

Responses

Request samples 

curl --request DELETE \
  --url 'https://{baseurl}/api/setting/custom_fields?id=SOME_STRING_VALUE' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

List Available Custom Field(s)

This API is used to view all available user custom fields.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/setting/custom_fields \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "CustomFieldCollection": {
    },
  • "Response": {}
}

View Output Signal

This API is used to view output signals which used on certain actions for setting the relay of the device to trigger in certain signals. The trigger & action from the device configuration is one of them.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/setting/output_signals \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Create Output Signal

This API is used to create output signal.

Authorizations:
SessionAuth
Request Body schema: application/json
object
name
required
string

Name of the output signal

delay
integer

Set the signal delay

count
integer

Set the signal count

on_duration
integer

Set the signal ON duration

off_duration
integer

Set the signal OFF duration

Responses

Request samples

Content type
application/json
{
  • "OutputSignal": {
    }
}

Update Output Signal

This API is used to update output signal.

Authorizations:
SessionAuth
path Parameters
id
required
string

ID of the output signal which will be updated.

Responses

Request samples 

curl --request PUT \
  --url https://{baseurl}/api/setting/output_signals/{id} \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Delete Output Signal

This API is used to delete output signal.

Authorizations:
SessionAuth
path Parameters
id
required
string

ID of the output signal which will be deleted.

Responses

Request samples 

curl --request DELETE \
  --url https://{baseurl}/api/setting/output_signals/{id} \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Update Server Matching

If server matching enabled, the user’s fingerprint will be matched from BioStar X, not the device. The Server Matching can be used when the corresponding license is activated.

Authorizations:
SessionAuth
Request Body schema: application/json
object
object (ServerMatching)
use-server-matching
boolean

Activates/Deactivates server matching. Toggle true to activate.

matching-concurrency-count
integer

Configure how many matchings can be done simultaneously.

security-level
integer

Configure the server matching’s security level for fingerprints. The higher the security level is set, the more the false rejection rate (FRR) can occur.

fast-mode
boolean

Configure the fingerprint matching speed.

face-security-level
integer

Configure the server matching’s security level for faces. The higher the security level is set, the more the false rejection rate (FRR) can occur.

Responses

Request samples

Content type
application/json
{
  • "BioStar": {
    }
}

Check BioStar X Version

This API is used to check BioStar X's version.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/js/info.json \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Active Directory

Active Directory integration and configuration

Check Active Directory Connection

This API is used to test BioStar X connection with Windows Active Directory.

Successful connection will return code : 0.

See these articles for more information on connecting BioStar X with Active Directory:

Authorizations:
SessionAuth
Request Body schema: application/json
required

Active Directory or Entra ID connection configuration parameters

serverAddress
required
string

IP Address of the Domain Controller

userName
required
string

User Name which will be used to connect to the Domain Controller

password
required
string <password>

User Name's corresponding password

userDomainName
required
string

BaseDN of the Domain Controller

useSSL
required
boolean

Option to use encryption when communicating with a Windows Active Directory server.

Install Active Directory Certificate Services and set the keystore password by referring to Active Directory Encryption.

adlogin
required
boolean

Enable logging into BioStar X using the Windows Active Directory account.

RedirectionUri
required
string <uri>

Required for Entra ID interworking.

adEnable
required
string

Set to 0.

adType
required
string
Enum: "A" "E"

Interworking target classification. (Active Directory=A, Entra ID=E)

prevAdType
required
string
Enum: "A" "E"

It is required to enter the previous connection information when modifying the interworking target. If there is no change, enter the current connection information.

prevDomainName
required
string

It is required to enter the previous connection information when modifying the interworking target. If there is no change, enter the current connection information.

prevServerAddr
required
string

It is required to enter the previous connection information when modifying the interworking target. If there is no change, enter the current connection information.

resetSync
required
boolean
Default: false

Delete existing users and user groups due to changes in connection information and set them to true if new settings are required.

scheduleSyncInterval
required
integer [ 0 .. 10080 ]

Set the time interval for automatic synchronization. (0=Manual synchronization, 30 to 10080=Automatic synchronization)

syncEvtCheck
required
boolean

Settings for whether to leave event logs on BioStar X. (true=event logs are kept on BioStar X as usual.)

syncType
required
string
Enum: "N" "A"

Toggle automatic synchronization. (N=Manual synchronization, A=Automatic synchronization)

useCustomField
required
boolean

Set this parameter to true if a custom user field has been added via Change AD User Mapping. If no custom user field is being used, set the parameter to false.

Responses

Request samples

Content type
application/json
{
  • "serverAddress": "",
  • "userName": "3323232-1111-33b6-a0a0-dfeq6bc7a762",
  • "password": "asdfasdfas~!2sdfsdfasdf",
  • "userDomainName": "test.onmicrosoft.com",
  • "useSSL": false,
  • "adlogin": false,
  • "RedirectionUri": "https://127.0.0.1/api/v2/entraid/auth",
  • "adEnable": "0",
  • "adType": "E",
  • "prevAdType": "E",
  • "prevDomainName": "test.onmicrosoft.com",
  • "prevServerAddr": "",
  • "resetSync": false,
  • "scheduleSyncInterval": 0,
  • "syncEvtCheck": false,
  • "syncType": "N",
  • "useCustomField": true
}

User Group Search

To run BioStar X AD APIs, it is required to be connected to the AD server.

This API is used to get User Group information from the Domain Controller.

It is required to put domain name information on the body.

The response value is returned in JSON format. At this time, Collection.rows.userGroups is used for the next user group update.

Authorizations:
SessionAuth
Request Body schema: application/json
string

Responses

Request samples

Content type
application/json
"DC=domain,DC=com"

User Group Update

Based on the user group information queried in User Group Search, the user group which will be linked is updated.

Update the user group and save it to the Biostar X server.

Authorizations:
SessionAuth
Request Body schema: application/json
allUserGroup
required
boolean

Toggle True when selecting all User Groups.

dn
required
string

Domain Name

lastSyncVersion
required
integer

Set to 0

userGroups
required
Array of objects

Put Collection.rows.userGroups from User Group Search

userGroupFilters
required
Array of objects

Place the id and name of the user groups to be synchronized into an array.

Responses

Request samples

Content type
application/json
{
  • "allUserGroup": true,
  • "dn": "DC=domain,DC=com",
  • "lastSyncVersion": 0,
  • "userGroups": {
    },
  • "userGroupFilters": {
    }
}

View AD User Group Filter List

View group information, subgroup information and filter information that Active Directory or EntraID is using.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/v2/setting/adUserGroupFilterSetting \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "Response": {},
  • "Collection": {
    }
}

Change AD User Mapping

This API is used to set the user field configuration.

The payload is in the form of a JSON array.
Each array has BioStar X column name (columnm), AD column name (adcolumnm), whether to use (use), and column description (columnmdescription).

[

{"columnm":"usrid","adcolumnm":"sAMAccountName","use":"true","columnmdescription":"userid"} {"columnm":"nm","adcolumnm":"displayName" ,"use":"true","columnmdescription":"User NAME"}

]

If you set the payload as above, you can sync the username as well.

Authorizations:
SessionAuth
Request Body schema: application/json
Array
columnm
required
string

BioStar X column name

adcolumnm
required
string

Active Directory column name

use
required
string

Whether to use this mapping

columnmdescription
required
string

Column description

Responses

Request samples

Content type
application/json
{
  • "0": {
    },
  • "1": {
    }
}

Synchronize

This API is used to synchronizes AD user information with Biostar X.

If there is no user group change or field reorganization then only this synchronization operation is sufficient.

serverAddress, userName, password, userDomainName, and useSSL must be sent in the payload.

lastSyncTime, lastSyncResult, lastUpdateTime fields on response are "recent sync time with ad server", "recent sync result", "recent update time of ad server information",
It can be checked through GET /api/v2/setting/adserversetting

Authorizations:
SessionAuth
Request Body schema: application/json
serverAddress
required
string

IP Address of the Domain Controller

userName
required
string

User Name which will be used to connect to the Domain Controller

password
required
string <password>

User Name's corresponding password

userDomainName
required
string

BaseDN of the Domain Controller

useSSL
required
boolean

Option to use encryption when communicating with a Windows Active Directory server.

Install Active Directory Certificate Services and set the keystore password by referring to Active Directory Encryption.

adlogin
required
boolean

Enable logging into BioStar X using the Windows Active Directory account.

RedirectionUri
required
string <uri>

Required for Entra ID interworking.

adEnable
required
string

Set to 0.

adType
required
string
Enum: "A" "E"

Interworking target classification. (Active Directory=A, Entra ID=E)

prevAdType
required
string
Enum: "A" "E"

It is required to enter the previous connection information when modifying the interworking target. If there is no change, enter the current connection information.

prevDomainName
required
string

It is required to enter the previous connection information when modifying the interworking target. If there is no change, enter the current connection information.

prevServerAddr
required
string

It is required to enter the previous connection information when modifying the interworking target. If there is no change, enter the current connection information.

resetSync
required
boolean
Default: false

Delete existing users and user groups due to changes in connection information and set them to true if new settings are required.

scheduleSyncInterval
required
integer [ 0 .. 10080 ]

Set the time interval for automatic synchronization. (0=Manual synchronization, 30 to 10080=Automatic synchronization)

syncEvtCheck
required
boolean

Settings for whether to leave event logs on BioStar X. (true=event logs are kept on BioStar X as usual.)

syncType
required
string
Enum: "N" "A"

Toggle automatic synchronization. (N=Manual synchronization, A=Automatic synchronization)

useCustomField
required
boolean

Set this parameter to true if a custom user field has been added via Change AD User Mapping. If no custom user field is being used, set the parameter to false.

Responses

Request samples

Content type
application/json
{
  • "adType": "E",
  • "RedirectionUri": "https://192.168.12.161/api/v2/entraid/auth",
  • "scheduleSyncInterval": 0,
  • "syncType": "N",
  • "useSSL": false,
  • "adlogin": false,
  • "adEnable": "0",
  • "serverAddress": "",
  • "userName": "3323232-1111-33b6-a0a0-dfeq6bc7a762",
  • "password": "asdfasdfas~!2sdfsdfasdf",
  • "userDomainName": "test.onmicrosoft.com",
  • "syncEvtCheck": true,
  • "prevAdType": "E",
  • "prevDomainName": "",
  • "prevServerAddr": "",
  • "resetSync": false,
  • "useCustomField": true
}

View AD Server Setting

Retrieves AD server configurations.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/v2/setting/adserversetting \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
Example
{
  • "ADServerSettingCollection": {
    },
  • "Response": {}
}

View AD User Mapping List

Retrieves the mapping relationships between user attribute fields in BioStar X and those used in Active Directory or Entra ID.

Please note that the required mapping information differs between Entra ID and Active Directory.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/v2/setting/adusrmappinglist \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
Example
{
  • "ADUsrMappingCollection": {
    },
  • "Response": {}
}

View AD Column List

Retrieve user property information used by Active Directory or EntraID.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/v2/setting/adcolumnlist \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "List<String>": {
    },
  • "Response": {},
  • "ADColumnCollection": {
    }
}

Check EntraID SSO Login Setting

Checks whether Entra ID SSO Login is enabled.

If the "BioStar X Login with Entra ID" option is enabled in the Directory Integration settings, the returned value is 'E'. If it is disabled (default), the value is 'D'.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/v2/setting/checkEntraIDSetting \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
Example
{}

Email Setting

Email notification settings

View Email Setting

This API is used to view the email template for Visual Face and BioStar X QR.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/setting_email \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Create Email Setting (Visual Face / QR)

This API is used to set email template for Visual Face and BioStar X QR.

Authorizations:
SessionAuth
query Parameters
email_type
integer
Example: email_type=1

1:Visual face mobile enrollment contents, 2:QR credential contents

Request Body schema: application/json
title
required
string

Enter the title of the email.

company_name
required
string

Enter the company name.

company_logo
required
string

Supported image file formats are GIF, JPG, JPEG, JPE, JFIF, PNG.
Supported image file size is up to 5MB. Base64 encoded string of the company logo image.

admin_contact
required
string

Enter the contact information of the person in charge.

use_setting
required
boolean

To use the enrollment set it as Use. If you set it as Not Use, BioStar X will be unable to send the visual face mobile enrollment link or QR to users.

Responses

Request samples

Content type
application/json
{
  • "title": "VisualFace",
  • "company_name": "Suprema Inc.",
  • "company_logo": "",
  • "admin_contact": "admin@example.com",
  • "use_setting": true
}

Update Email Setting (Visual Face / QR)

This API is used to set email template for Visual Face and BioStar X QR.

Authorizations:
SessionAuth
query Parameters
email_type
integer
Example: email_type=1

1:Visual face mobile enrollment contents, 2:QR credential contents

Request Body schema: application/json
title
required
string

Enter the title of the email.

company_name
required
string

Enter the company name.

company_logo
required
string

Supported image file formats are GIF, JPG, JPEG, JPE, JFIF, PNG.
Supported image file size is up to 5MB. Base64 encoded string of the company logo image.

admin_contact
required
string

Enter the contact information of the person in charge.

use_setting
required
boolean

To use the enrollment set it as Use. If you set it as Not Use, BioStar X will be unable to send the visual face mobile enrollment link or QR to users.

Responses

Request samples

Content type
application/json
{
  • "title": "VisualFace",
  • "company_name": "Suprema Inc.",
  • "company_logo": "",
  • "admin_contact": "admin@example.com",
  • "use_setting": true
}

View SMTP Setting

This API is used to view the SMTP (Simple Mail Transfer Protocol) for sending emails.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/setting/alarm_smtps \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Create SMTP Setting

This API is used to set the SMTP (Simple Mail Transfer Protocol) for sending emails.

Note:

When using an SMTP server with an email account that has two-factor authentication (2FA) enabled, be aware of the following:

  • Once 2FA is set up, the SMTP password is not the same as the email account password. Instead, it corresponds to an app password generated specifically for use with 2FA.
  • If you change the email account password, all existing app passwords are automatically revoked. As a result, the previously configured SMTP password will no longer work.
  • After changing the email account password, you must generate a new app password and update the SMTP settings with the new value.
Authorizations:
SessionAuth
Request Body schema: application/json
object
name
string

Enter the SMTP server name.

description
string

Enter the description.

smtp_server_addr
string

Enter the SMTP server address. SMTP server address is the same form as 'smtp. Email Service Provider.com', and you can check it on the settings screen of email to use as an SMTP.

smtp_server_port
string

Enter the port number of the SMTP server. you can check it on the settings screen of email to use as an SMTP

smtp_username
string

Enter the user name of the SMTP server.

smtp_password
string <password>

Enter the password of the SMTP server.

smtp_security
string

Select the security type of the SMTP server.

smtp_sender
string

Enter the sender email address.

Responses

Request samples

Content type
application/json
{
  • "AlarmSmtp": {
    }
}

Update SMTP Setting

This API is used to update the SMTP (Simple Mail Transfer Protocol) for sending emails.

Note:

When using an SMTP server with an email account that has two-factor authentication (2FA) enabled, be aware of the following:

  • Once 2FA is set up, the SMTP password is not the same as the email account password. Instead, it corresponds to an app password generated specifically for use with 2FA.

  • If you change the email account password, all existing app passwords are automatically revoked. As a result, the previously configured SMTP password will no longer work.

  • After changing the email account password, you must generate a new app password and update the SMTP settings with the new value.

Authorizations:
SessionAuth
path Parameters
id
required
string

ID of the SMTP setting which will be updated.

Request Body schema: application/json
object
name
string

Enter the SMTP server name.

description
string

Enter the description.

smtp_server_addr
string

Enter the SMTP server address. SMTP server address is the same form as 'smtp. Email Service Provider.com', and you can check it on the settings screen of email to use as an SMTP.

smtp_server_port
string

Enter the port number of the SMTP server. you can check it on the settings screen of email to use as an SMTP

smtp_username
string

Enter the user name of the SMTP server.

smtp_password
string <password>

Enter the password of the SMTP server.

smtp_security
string

Select the security type of the SMTP server.

smtp_sender
string

Enter the sender email address.

Responses

Request samples

Content type
application/json
{
  • "AlarmSmtp": {
    }
}

Test SMTP Connection

This API is used to test SMTP connection by sending an email to the specified address.

Do note that the address input here need to be a complete email address.

Authorizations:
SessionAuth
Request Body schema: application/json
target_email
string

Target email address to send the test email.

Responses

Request samples

Content type
application/json
{
  • "target_email": "example@example.com"
}

Preference

System preferences and configuration

View Preference

This API is used to view preference information.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 1

ID of the user which preference will be viewed.

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/preferences/1 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Update Preference

This API is used to update preference configuration.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 1
Request Body schema: application/json
object
language
string

Preference language. Example - ko, en

date_format
string

Format of the date

time_format
string

Format of the time

time_long_term_format
string

Format for long term time

time_zone
string

Select the time zone that corresponds to your current location.

Time Zone ID Time Zone ID
UTC-12:00 0 UTC+03:30 17
UTC-11:00 1 UTC+04:00 18
UTC-10:00 2 UTC+04:30 19
UTC-09:30 3-1 UTC+05:00 20
UTC-09:00 3 UTC+05:30 21
UTC-08:00 4 UTC+05:45 22
UTC-07:00 5 UTC+06:00 23
UTC-06:00 6 UTC+06:30 23+1
UTC-05:00 7 UTC+07:00 24
UTC-04:30 8-1 UTC+08:00 25
UTC-04:00 8 UTC+08:30 25+1
UTC-03:30 9 UTC+08:45 25+2
UTC-03:00 10 UTC+09:00 26
UTC-02:00 11 UTC+09:30 27
UTC-01:00 12 UTC+10:00 28
UTC±00:00 13 UTC+10:30 28+1
UTC+01:00 14 UTC+11:00 29
UTC+02:00 15 UTC+12:00 30
UTC+03:00 16 UTC+12:45 30+1
UTC+13:00 31
UTC+14:00 32
dst1
string

ID of the first Daylight Saving Time applied. 0 for none.

dst2
string

ID of the second Daylight Saving Time applied. 0 for none.

depend_on_os
boolean
object

Responses

Request samples

Content type
application/json
{
  • "Preference": {
    }
}

Add Preference

This API is used to add preference configuration.

Authorizations:
SessionAuth
Request Body schema: application/json
object
language
string

Preference language. Example - ko, en

date_format
string

Format of the date

time_format
string

Format of the time

time_long_term_format
string

Format for long term time

time_zone
string

Select the time zone that corresponds to your current location.

Time Zone ID Time Zone ID
UTC-12:00 0 UTC+03:30 17
UTC-11:00 1 UTC+04:00 18
UTC-10:00 2 UTC+04:30 19
UTC-09:30 3-1 UTC+05:00 20
UTC-09:00 3 UTC+05:30 21
UTC-08:00 4 UTC+05:45 22
UTC-07:00 5 UTC+06:00 23
UTC-06:00 6 UTC+06:30 23+1
UTC-05:00 7 UTC+07:00 24
UTC-04:30 8-1 UTC+08:00 25
UTC-04:00 8 UTC+08:30 25+1
UTC-03:30 9 UTC+08:45 25+2
UTC-03:00 10 UTC+09:00 26
UTC-02:00 11 UTC+09:30 27
UTC-01:00 12 UTC+10:00 28
UTC±00:00 13 UTC+10:30 28+1
UTC+01:00 14 UTC+11:00 29
UTC+02:00 15 UTC+12:00 30
UTC+03:00 16 UTC+12:45 30+1
UTC+13:00 31
UTC+14:00 32
dst1
string

ID of the first Daylight Saving Time applied. 0 for none.

dst2
string

ID of the second Daylight Saving Time applied. 0 for none.

depend_on_os
boolean
object

Responses

Request samples

Content type
application/json
{
  • "Preference": {
    }
}

Virtual Device & Event Import

This feature allows external systems (e.g., mobile T&A apps) to send punch/access events directly to BioStar X without database-level integration.

To ensure data consistency, each event must be associated with a Virtual Device — a device record created inside BioStar X to represent the external source.

Notes:

  • Virtual Devices are non-functional placeholders and cannot be used for access control, doors, or Advanced AC features. Their only purpose is to logically link imported events to a known device identity.

  • BioStar X Event Log API license is required for the feature.

Step-by-Step: How to Use

Step 1: Create a Virtual Device

  • Use POST /api/v2/virtual_devices to create a new virtual device.

  • Usable ID range: 100001–999999

  • Ensure it’s not a duplicate ID or name.

  • Assign it to an existing device group.

Step 2: Verify Virtual Device

  • Use GET /api/v2/virtual_devices

to confirm your virtual device is registered and visible.

Step 3: Import Events

  • Prepare your event payload with the same packet_device_id as the virtual device ID.

  • Ensure all timestamps are in UTC.

  • Use POST /api/events/import to upload multiple events at once.

Step 4: Verify Event Import

  • After import, use existing endpoints such as:

    • POST /api/events/search

to confirm the events are visible in BioStar X event logs.

Step 5: Troubleshooting

If an error occurs:

  • Check that is_virtual_device is "true".

  • Confirm all user_ids exist.

  • Verify datetime formatting (YYYY-MM-DDTHH:mm:ssZ).

  • Ensure the event code is either 4088 or 6400.

Create a New Virtual Device

Registers a virtual device within BioStar X.

Each virtual device:

  • Must have a unique id (range: 100001–999999).

  • Cannot duplicate existing device IDs or names.

  • Appears in device lists when ?virtual=true is included in search queries.

Notes:

  • Virtual devices are non-functional placeholders (cannot control doors or perform access).

  • Once created, the device ID cannot be modified.

  • Virtual devices can be listed using GET /api/v2/devices/search?virtual=true.

Authorizations:
SessionAuth
Request Body schema: application/json
required
object (VirtualDeviceInput)

Root object containing virtual device details.

id
required
integer

Unique identifier for the virtual device. Must be within 100001–999999 and not duplicate any existing device ID.

name
required
string

Display name of the virtual device. Must be unique (no duplicate with existing devices).

description
string

Optional text description for internal reference.

required
object

Defines which device group this virtual device belongs to.

Responses

Request samples

Content type
application/json
{
  • "VirtualDevice": {
    }
}

Response samples

Content type
application/json
{
  • "VirtualDevices": [
    ],
  • "Response": {}
}

Fetch Registered Virtual Devices

Retrieve a list of registered virtual devices.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/v2/virtual_devices \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "VirtualDevices": [
    ],
  • "Response": {}
}

Delete Virtual Device

Deletes one or more virtual devices based on provided IDs.

Authorizations:
SessionAuth
query Parameters
id
integer
Example: id=100002

ID of the Virtual Devices which will be deleted. Use plus symbol (+) to delimit multiple IDs (e.g. 10001+10002)

Responses

Request samples 

curl --request DELETE \
  --url 'https://{baseurl}/api/v2/virtual_devices?id=100002' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{}

Modify Existing Virtual Device

Modify existing virtual device details. Only updatable fields need to be included.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 100001

ID of the Virtual Device which will be modified.

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "VirtualDevice": {
    }
}

Response samples

Content type
application/json
{
  • "VirtualDevices": [
    ],
  • "Response": {}
}

Import Events

Imports external access events into the system.

Allows batch import of Access Granted (4088) and Access Denied (6400) events generated by a Virtual Device.

This is typically used when an external app generates punch logs (e.g., mobile attendance).

Each imported event is stored as a normal BioStar X event, visible in event logs and reports.

Important Rules

  • packet_device_id and every events[].dev_id must match.

  • Only virtual devices are allowed.

  • Only event codes 4088 or 6400 are permitted.

  • datetime must be in UTC (convert local time accordingly).

  • All user_ids must exist in the system.

  • Each imported event will be logged individually (one row per event).

Authorizations:
SessionAuth
Request Body schema: application/json
required

Event import data containing device information and events array

packet_device_id
required
integer

Must match dev_id of all included events.

is_virtual_device
required
boolean

Indicates whether the device is virtual. Must be true for event imports.

required
Array of objects (ImportEventItem)

List of event objects to import.

Responses

Request samples

Content type
application/json
{
  • "packet_device_id": 100001,
  • "is_virtual_device": true,
  • "events": {
    }
}

Response samples

Content type
application/json
{}

Mobile Access

Delete Mobile Access Card in Airfob Portal: ALL on User ID

This API is used to delete Mobile Access Card in Airfob Portal.

There are three variations in using this API:

  1. Using Card ID

  2. Using User ID

  3. Using ALL parameter on User ID

  • To delete multiple card_id or user_id, separate each value with comma (,). Ex: ["1", "2", "3"]

  • This API only remove Mobile Access Card information from Airfob Portal. To remove Mobile Access credential from the user, use PUT /api/users/:id

Authorizations:
SessionAuth
Request Body schema: application/json
object
object
user_id
string

The use of ALL parameter will remove Airfob's Mobile Access Card from all user which have Mobile Access Card on their credential list.

card_id
Array of strings

List of Mobile Access Card's card ID.

object

Responses

Request samples

Content type
application/json
{
  • "MobileCollection": {
    }
}

Response samples

Content type
application/json
{}

Create Mobile Access Card in Airfob Portal

This API is used to create Mobile Access Card in Airfob Portal.

Note:

  • When creating mobile access cards, Airfob portal sites are divided into regular and dynamic
  • The startDate and endDate fields are used when the sites are dynamic sites

ToM

  • ToM uses Extend mode for personal authentication mode when creating a card
  • If another device supports ToM in the future, a value mapped to cardAuthMode (standard) and cardAuthModeEx (extend) should be added for compatibility with devices that do not support Extend
  • In API, if you put in the cardAuthModeEx value, the server internally maps the cardAuthMode value

Card AuthMode Mapping Table:

cardAuthModeEx cardAuthMode
21 - Card 2 - Card only
22 - Card + Face 3 - Card + Fingerprint
23 - Card + Fingerprint 3 - Card + Fingerprint
24 - Card + PIN 4 - Card + PIN
25 - Card + Face or Fingerprint 5 - Card + Fingerprint or PIN
26 - Card + Face or PIN 5 - Card + Fingerprint or PIN
27 - Card + Fingerprint or PIN 5 - Card + Fingerprint or PIN
28 - Card + Face or Fingerprint or PIN 5 - Card + Fingerprint or PIN
29 - Card + Face + Fingerprint 6 - Card + Fingerprint + PIN
30 - Card + Face + PIN 6 - Card + Fingerprint + PIN
31 - Card + Fingerprint + Face 6 - Card + Fingerprint + PIN
32 - Card + Fingerprint + PIN 6 - Card + Fingerprint + PIN
33 - Card + Face or Fingerprint + PIN 6 - Card + Fingerprint + PIN
34 - Card + Face + Fingerprint or PIN 6 - Card + Fingerprint + PIN
35 - Card + Fingerprint + Face or PIN 6 - Card + Fingerprint + PIN
Authorizations:
SessionAuth
Request Body schema: application/json
required
required
object
required
object
user_id
required
Array of strings

User ID

name
Array of strings or null

User Name

title
Array of strings or null

User's Title

department
Array of strings or null

Department Name

phone
Array of strings or null

Phone Number

email
required
Array of strings <email> [ items <email > ]

Email address

portraitData
Array of strings or null

Photo encoding data in Base64 format

card_id
required
Array of strings

Card ID

startDate
Array of integers or null <int64> [ items <int64 > ]

Start Date for Dynamic Site (timestamp in milliseconds, required for Dynamic Site)

endDate
Array of integers or null <int64> [ items <int64 > ]

End Date for Dynamic Site (timestamp in milliseconds, required for Dynamic Site)

startTime
required
Array of integers <int64> [ items <int64 > ]

User period start date (timestamp in milliseconds, required)

endTime
required
Array of integers <int64> [ items <int64 > ]

User period end date (timestamp in milliseconds, required)

issueCount
Array of integers or null

ToM card issue round (required for ToM)

duressMask
Array of strings or null

Duress value

useAlphanumericID
Array of integers or null
Items Enum: 0 1

ID type: 0 for Numeric, 1 for Alphanumeric

cardAuthModeEx
Array of integers
Items Enum: 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35

Extended card authentication mode (see mapping table in API description)

pin
Array of strings or null

PIN number

accessGroupId
Array of strings or null

Access Group ID

mobileCardType
required
Array of strings
Items Enum: "4" "14" "15"

Mobile card type (required): 4 for CSN Mobile, 14 for ToM_AoC, 15 for ToM_SCC

Responses

Request samples

Content type
application/json
{
  • "MobileCollection": {
    }
}

Response samples

Content type
application/json
{
  • "MobileCollection": {
    },
  • "Response": {}
}

View Deleted CSN Mobile

This API is used to fetch CSN Mobile information deleted from the list.

Authorizations:
SessionAuth
query Parameters
limit
integer
Example: limit=50

Limit the number of responses by n records. Remove this parameter to view all.

offset
integer

Offset the response shown by n records.

search_type
string
Example: search_type=DELETED_CSN_MOBILE

Filter the response by card type (DELETED_CSN_MOBILE).

Responses

Request samples 

curl --request GET \
  --url 'https://{baseurl}/api/v2/cards/mobile/search?limit=50&offset=0&search_type=DELETED_CSN_MOBILE' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "CardCollection": {
    },
  • "Response": {
    }
}

Delete CSN Mobile

This API is used to delete CSN Mobile information.

Authorizations:
SessionAuth
query Parameters
id
string
Example: id=18,19,20

Card UID value, separate using comma (,). Use asterisk (*) to select all.

Responses

Request samples 

curl --request DELETE \
  --url 'https://{baseurl}/api/v2/cards/mobile/enable?id=18%2C19%2C20' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{}

Count Deleted CSN Mobile

This API is used to count deleted CSN Mobile information.

Authorizations:
SessionAuth
Request Body schema: application/json
cardUids
required
string

List of Mobile Card UID(s) which will be counted, separated by comma (,).

Responses

Request samples

Content type
application/json
{
  • "cardUids": "11,12,13,16,17"
}

Response samples

Content type
application/json
{
  • "CardCollection": {
    },
  • "Response": {
    }
}

Events

Download CSV File

This API is used to download exported CSV files from BioStar X Server.

Supports downloading both user-related CSV files and events-related CSV files. The system automatically detects the file type based on the filename pattern.

Supported File Types:

  • User CSV files: Generated from POST /api/users/csv_export
  • Events CSV files: Generated from POST /api/events/export

Usage:

  1. Export data using the appropriate API (csv_export for users, export for events)
  2. Get the filename from the export response
  3. Use the filename as the path parameter in this download API
Authorizations:
SessionAuth
path Parameters
csv_filename
required
string
Examples:
  • User_Import_Error_20220124T143708.csv - User CSV file
  • Report_20220204T165145.csv - Events CSV file

Name of the CSV file to download (supports both user and events files)

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/download/User_Import_Error_20220124T143708.csv \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Fetch Event Image

When query events through Search Events (/api/events/search), events that contain image logs include the response fields. The image_data value can be used to retrieve the corresponding image file.

Authorizations:
SessionAuth
path Parameters
image_data
required
string

(String, Required) – The identifier of the image, obtained from the event search response.

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/events/images/{image_data} \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "image_id": {
    }
}

Search Thermal Events

This API is used to view events with thermal data.

Parameters on this API is the same as Search Events.

Authorizations:
SessionAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "Query": {
    }
}

Export as CSV

This API is used to export events to a .csv file. Exported .csv will be saved on BioStar X Server installation path. To get it from the server, use Download Events Exported CSV API.

Authorizations:
SessionAuth
query Parameters
time_offset
integer
Example: time_offset=480

Shift time on the exported file by n minutes

use_centigrade
boolean
Example: use_centigrade=true

Toggle for the use of centigrade

Request Body schema: application/json
object (ExportCSV)
Array of objects (QueryConditions)

A set of conditions to filter the response of the API. On this case, it's using the datetime field to filter according to the values given.

offset
integer

Offset the response's records by the specified value.

columns
required
Array of strings

List of columns which will be included on the CSV.

headers
required
Array of strings

Name of the header on the exported .csv file.

Responses

Request samples

Content type
application/json
{
  • "Query": {
    }
}

List All Alerts: Filter & Sort by Date

This example shows how to use the parameters on this API to filter responses according to the datetime of the alert events.

Authorizations:
SessionAuth
Request Body schema: application/json
object
Array of objects (QueryConditions)

A set of conditions to filter the response of the API. On this case, it's using the datetime field to filter according to the values given.

Array of objects

Responses

Request samples

Content type
application/json
{
  • "Query": {
    }
}

Update Alert History

This API is used to log alertable: true events (GET /api/event_types) to Alert Collection (POST /api/alerts/search)

Authorizations:
SessionAuth
path Parameters
alert_id
required
integer
Example: 1.643790735054372e+29

Unique ID recorded on hint parameter (POST /api/events/search)

Request Body schema: application/json
object
required
object
status
required
integer
Default: 1

Default: 1

required
object
ack_message
required
string

Custom message which will be recorded on the Alert Log

Responses

Request samples

Content type
application/json
{
  • "Alert": {
    }
}

View a Muster Zone Status

This API is used to view a muster zone status.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 32787
Request Body schema: application/json
object
limit
required
integer

Specify the number of records which shown on the response

Responses

Request samples

Content type
application/json
{
  • "Query": {
    }
}

Audit

Audit Search

This API is used to view Audit Trail logs.

It is possible to use multiple conditions in a request. Separate each condition using comma (,).

Example: [ {condition 1}, {condition 2}, .. ]

Authorizations:
SessionAuth
Request Body schema: application/json
required

Search criteria and pagination settings for audit trail logs

required
object

Search query configuration with conditions and pagination

offset
integer

Offset the response's records by the specified value.

limit
required
integer

Limit the number of response's records by the specified value.

total
boolean
Default: false

Toggle true to get total count of the Audit Trail based on condition(s) set.

Array of objects (AuditSearchCondition)

Array of search conditions to filter audit logs

Responses

Request samples

Content type
application/json
{
  • "Query": {
    }
}

Audit Search User

This API is used to filter user by the specified input.

Do note the API will only show records of user which have Audit Trail logs only.

Authorizations:
SessionAuth
Request Body schema: application/json
object (AuditSearchRequest)
search
string

Search term to filter with Audit Trail log. To show all which have Audit Trail logs, simply remove this parameter from the request.

limit
integer

Limit the number of response's records by the specified value.

offset
integer

Offset the response's records by the specified value.

Responses

Request samples

Content type
application/json
{
  • "Userlist": {
    }
}

Audit Search Operator Level

This API is used to filter Operator Level by the specified input.

Do note the API will only show records of Operator Level which have Audit Trail logs only.

Authorizations:
SessionAuth
Request Body schema: application/json
object (AuditSearchRequest)
search
string

Search term to filter with Audit Trail log. To show all which have Audit Trail logs, simply remove this parameter from the request.

limit
integer

Limit the number of response's records by the specified value.

offset
integer

Offset the response's records by the specified value.

Responses

Request samples

Content type
application/json
{
  • "Permlist": {
    }
}

Audit Search IP List

This API is used to filter IP records by the specified input.

Do note the API will only show records which have Audit Trail logs only.

Authorizations:
SessionAuth
Request Body schema: application/json
object (AuditSearchRequest)
search
string

Search term to filter with Audit Trail log. To show all which have Audit Trail logs, simply remove this parameter from the request.

limit
integer

Limit the number of response's records by the specified value.

offset
integer

Offset the response's records by the specified value.

Responses

Request samples

Content type
application/json
{
  • "Iplist": {
    }
}

Audit Search Target List

This API is used to filter Target records by the specified input.

Do note the API will only show records which have Audit Trail logs only.

Authorizations:
SessionAuth
Request Body schema: application/json
object (AuditSearchRequest)
search
string

Search term to filter with Audit Trail log. To show all which have Audit Trail logs, simply remove this parameter from the request.

limit
integer

Limit the number of response's records by the specified value.

offset
integer

Offset the response's records by the specified value.

Responses

Request samples

Content type
application/json
{
  • "Targetlist": {
    }
}

Audit CSV Export

This API is used to generate CSV file based on the parameters. Make use of Events\Download Events Exported CSV API to download the exported CSV.

Authorizations:
SessionAuth
query Parameters
time_offset
integer
Example: time_offset=480

Adjust the time value according to the required Time Zone. If the required TZ is UTC+8, then the value will be 480 (60 x 8).

Request Body schema: application/json
object (ExportCSV)
Array of objects (QueryConditions)

A set of conditions to filter the response of the API. On this case, it's using the datetime field to filter according to the values given.

offset
integer

Offset the response's records by the specified value.

columns
required
Array of strings

List of columns which will be included on the CSV.

headers
required
Array of strings

Name of the header on the exported .csv file.

Responses

Request samples

Content type
application/json
{
  • "Query": {
    }
}

Zones

Interlock: Create

Interlock zone monitors the status of two or more doors by door sensor and relay state to control that one door cannot be opened or close if other doors are open or unlocked. You can also disable access if a user stays within the zone.

  • An interlock zone can be configured with up to 4 doors.

  • An interlock zone can only set the doors with the devices connected to the CoreStation.

  • A device set as an interlock zone cannot be set to another zone.

  • A door set as an interlock zone cannot be set to another zone other than the fire alarm zone.

Authorizations:
SessionAuth
Request Body schema: application/json
required
object
name
required
string [ 1 .. 48 ] characters

Enter an interlock zone name.

description
string <= 255 characters

Enter an interlock zone description.

zone_type
required
integer

View the zone type.

is_global
required
integer

You can check the application range of the zone. Only Local mode is supported for interlock zone, and the zone can be set only with devices connected to the CoreStation and RS-485.

enable
required
integer

You can disable the interlock zone. input 1 to enable it.

required
object

Responses

Request samples

Content type
application/json
{
  • "Zone": {
    }
}

View Zones

This API is used to view zones.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/zones \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

APB: Clear APB

This endpoint allows administrators to reset the Anti-Passback state within a zone. It can be applied either to all users in the zone or to a specific set of users

Response Codes:

  • 200 OK: Request successful

  • 400 Bad Request (Code 671): Zone ID mismatch (zone not found)

  • 401 Unauthorized: Login required or invalid session token

Authorizations:
SessionAuth
Request Body schema: application/json
object
Array of objects

List of user objects with user_id. Required when UserType=2.

Responses

Request samples

Content type
application/json
{
  • "AntiPassBackConfig": {
    }
}

Response samples

Content type
application/json
{}

Zones: Update

This API is used to update a Zone.

Authorizations:
SessionAuth
path Parameters
id
required
string

ID of the Zone which will be updated.

Request Body schema: application/json
object
name
required
string [ 1 .. 48 ] characters

Enter the zone name.

description
string <= 255 characters

Enter the zone description.

zone_type
required
integer

View the zone type.

is_global
required
integer

You can check the application range of the zone. Only Local mode is supported for interlock zone, and the zone can be set only with devices connected to the CoreStation and RS-485.

enable
required
integer

You can disable the interlock zone. input 1 to enable it.

status
integer

View the zone status.

Responses

Request samples

Content type
application/json
{
  • "Zone": {
    }
}

Zones: Delete

This API is used to delete a Zone.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 32786

ID of the zone which will be deleted.

Responses

Request samples 

curl --request DELETE \
  --url https://{baseurl}/api/zones/32786 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

View a Zone Detail

This API is used to view a zone detailed information.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 32787

ID of the zone which will be viewed.

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/zones/32787 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Occupancy Limit

Occupancy: Create New

Create and manage occupancy limit zones to control population density in specific areas and prevent overcrowding.

You can monitor occupancy status and set alerts when zones reach capacity.

Capacity: Up to 100 occupancy limit zones can be added.

Compatible Devices:

  • FaceStation F2 firmware version 1.1.0 or later
  • FaceStation 2 firmware version 1.5.0 or later

Important Notes:

  • A device cannot be assigned to both entry and exit simultaneously
  • Maximum 128 entry and exit devices combined
  • Devices using Dual Authentication cannot be set as entry or exit devices
  • Auto Count Reset time is based on UTC for the zone's location
  • Alert values must be smaller than the limit value and different from each other
  • Count Bypass feature is not available when using Thermal & Mask Check Mode without authentication
  • Up to 16 bypass groups can be added
Authorizations:
SessionAuth
query Parameters
time_zone
integer
Default: 26
Example: time_zone=25

Time Zone ID for system operations. Affects timing calculations based on UTC offset.

Available Time Zones:

ID Offset Description ID Offset Description
0 -720 UTC-12:00 17 +210 UTC+03:30
1 -660 UTC-11:00 18 +240 UTC+04:00
2 -600 UTC-10:00 19 +270 UTC+04:30
3-1 -570 UTC-09:30 20 +300 UTC+05:00
3 -540 UTC-09:00 21 +330 UTC+05:30
4 -480 UTC-08:00 22 +345 UTC+05:45
5 -420 UTC-07:00 23 +360 UTC+06:00
6 -360 UTC-06:00 23+1 +390 UTC+06:30
7 -300 UTC-05:00 24 +420 UTC+07:00
8-1 -270 UTC-04:30 25 +480 UTC+08:00
8 -240 UTC-04:00 25+1 +510 UTC+08:30
9 -210 UTC-03:30 25+2 +525 UTC+08:45
10 -180 UTC-03:00 26 +540 UTC+09:00 (Default)
11 -120 UTC-02:00 27 +570 UTC+09:30
12 -60 UTC-01:00 28 +600 UTC+10:00
13 0 UTC±00:00 28+1 +630 UTC+10:30
14 +60 UTC+01:00 29 +660 UTC+11:00
15 +120 UTC+02:00 30 +720 UTC+12:00
16 +180 UTC+03:00 30+1 +765 UTC+12:45
31 +780 UTC+13:00
32 +840 UTC+14:00
Request Body schema: application/json
required
is_enabled
required
integer
Enum: 0 1

Deactivate the occupancy limit zone. If the zone is deactivated, both Count that refers to the number of users in the zone and Count Bypass settings will be initialized. Select Active to enable it. (1=Active, 0=Inactive)

name
required
string [ 1 .. 48 ] characters

Enter an occupancy limit zone name. Name can be up to 48 characters in length and cannot be set to the same name as other zones.

zone_type
required
integer

View the zone type.

status
required
integer

Current status of the zone

required
object

Responses

Request samples

Content type
application/json
{
  • "is_enabled": 1,
  • "name": "OccupancyZone1",
  • "zone_type": 11,
  • "status": 0,
  • "occupancy_detail": {
    }
}

Occupancy: Delete

This API is used to delete Occupancy Zone.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request DELETE \
  --url https://{baseurl}/api/v2/zones/occupancy \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Occupancy: List All

This API is used to list all configured Occupancy Zone.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/v2/zones/occupancy \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Occupancy: Update

This API is used to update occupancy zone configuration.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 32784

ID of the occupancy zone which will be updated.

query Parameters
time_zone
integer
Default: 26
Example: time_zone=25

Time Zone ID for system operations. Affects timing calculations based on UTC offset.

Available Time Zones:

ID Offset Description ID Offset Description
0 -720 UTC-12:00 17 +210 UTC+03:30
1 -660 UTC-11:00 18 +240 UTC+04:00
2 -600 UTC-10:00 19 +270 UTC+04:30
3-1 -570 UTC-09:30 20 +300 UTC+05:00
3 -540 UTC-09:00 21 +330 UTC+05:30
4 -480 UTC-08:00 22 +345 UTC+05:45
5 -420 UTC-07:00 23 +360 UTC+06:00
6 -360 UTC-06:00 23+1 +390 UTC+06:30
7 -300 UTC-05:00 24 +420 UTC+07:00
8-1 -270 UTC-04:30 25 +480 UTC+08:00
8 -240 UTC-04:00 25+1 +510 UTC+08:30
9 -210 UTC-03:30 25+2 +525 UTC+08:45
10 -180 UTC-03:00 26 +540 UTC+09:00 (Default)
11 -120 UTC-02:00 27 +570 UTC+09:30
12 -60 UTC-01:00 28 +600 UTC+10:00
13 0 UTC±00:00 28+1 +630 UTC+10:30
14 +60 UTC+01:00 29 +660 UTC+11:00
15 +120 UTC+02:00 30 +720 UTC+12:00
16 +180 UTC+03:00 30+1 +765 UTC+12:45
31 +780 UTC+13:00
32 +840 UTC+14:00
Request Body schema: application/json
required
is_enabled
required
integer
Enum: 0 1

Deactivate the occupancy limit zone. If the zone is deactivated, both Count that refers to the number of users in the zone and Count Bypass settings will be initialized. Select Active to enable it. (1=Active, 0=Inactive)

name
required
string [ 1 .. 48 ] characters

Enter an occupancy limit zone name. Name can be up to 48 characters in length and cannot be set to the same name as other zones.

zone_type
required
integer

View the zone type.

status
required
integer

Current status of the zone

required
object

Responses

Request samples

Content type
application/json
{
  • "is_enabled": 1,
  • "name": "OccupancyZone1",
  • "zone_type": 11,
  • "status": 0,
  • "occupancy_detail": {
    }
}

Occupancy: View Details

This API is used to view details of an Occupancy Zone.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 32784

ID of the Occupancy Zone which will be viewed.

query Parameters
time_zone
integer
Example: time_zone=25

Responses

Request samples 

curl --request GET \
  --url 'https://{baseurl}/api/v2/zones/occupancy/32784?time_zone=25' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Occupancy: Search by Name

This API is used to search Occupancy Zone by name.

Authorizations:
SessionAuth
path Parameters
id
required
string
Example: occ

Name of the Occupancy Zone which will be searched.

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/v2/zones/occupancy/search/occ \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Occupancy: List Dual Auth. Devices

This API is used to get a list of dual authentication devices.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/v2/zones/occupancy/devices/dual \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Occupancy: View Assigned Devices

This API is used to list assigned devices on a Occupancy Zone.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 32784

ID of the Occupancy Zone

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/v2/zones/occupancy/devices/32784 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Occupancy: Increase Count

This API is used to increase an occupancy count.

Count will be higher or equal to 0 and will be lower or equal to Count Limit.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 32784

ID of the Occupancy Limit.

Responses

Request samples 

curl --request PUT \
  --url https://{baseurl}/api/v2/zones/occupancy/count/increase/32784 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Occupancy: Decrease Count

This API is used to decrease an occupancy count.

Count will be higher or equal to 0 and will be lower or equal to Count Limit.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 32784

ID of the Occupancy Limit

Responses

Request samples 

curl --request PUT \
  --url https://{baseurl}/api/v2/zones/occupancy/count/decrease/32784 \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Occupancy: Set Count

This API is used to set and occupancy limit count.

Count value will be higher or equal to 0 and will be lower or equal to Count Limit.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 32784

ID of the Occupancy Limit.

Request Body schema: application/json
count
required
integer

Set count value

Responses

Request samples

Content type
application/json
{
  • "count": 85
}

Occupancy: Reset Count

This API is used to reset current counts and bypass counts of the occupancy limit zone.

Authorizations:
SessionAuth
Request Body schema: application/json
ids
Array of integers

List of Occupancy Zone IDs which will be reset.

Responses

Request samples

Content type
application/json
{
  • "ids": {
    }
}

Occupancy: Disable

This API is used to disable Occupancy Limit Zone.

Authorizations:
SessionAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "ids": {
    }
}

Occupancy: Enable

This API is used to enable Occupancy Limit Zone.

Authorizations:
SessionAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "ids": {
    }
}

Event Log

View Event Types

This API is used for listing event types recorded on BioStar X.

Authorizations:
SessionAuth
query Parameters
is_break_glass
boolean

Filter event types which is marked as break glass.

setting_alert
boolean

Toggle true to list events which will trigger alert. Marked by 'alertable' parameter on the event. 'enable_alert' is used for marking which event will show a pop up notice on BioStar X.

setting_all
boolean
Example: setting_all=true

Toggle true to list all events recorded on database.

Responses

Request samples 

curl --request GET \
  --url 'https://{baseurl}/api/event_types?is_break_glass=false&setting_alert=false&setting_all=true' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

Search Events Example

This example shows how to view event log from device with id: 543308153 (device timezone set as UTC+8) and log with datetime between 2022-06-01 00:05 to 2022-06-30 23:58.

Note that the datetime used on the API criteria is different from what the user would like to see. This is because the device was set to use UTC+8, so to view the correct log, use datetime which have been converted to UTC-0.

Authorizations:
SessionAuth
Request Body schema: application/json
object
limit
integer

Limit the number of responses by n records.

Array of objects
Array of objects

Responses

Request samples

Content type
application/json
{
  • "Query": {
    }
}

Create User

02 View BioStar Settings

After logged in, use this API to view the User ID setting of the BioStar X, is it AlphaNumeric or Number.

It can be seen on parameter use_alphanumeric, if the value is false then the current setting for User ID is Number, else it's AlphaNumeric.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/setting/biostar \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

03 Find Next Available UserID

After User ID setting of BioStar X is confirmed, use this API to get the next user_id for new user.

This API will only shows next available ID in number format.

Keep this ID for input on user_id parameter when creating new user.

Authorizations:
SessionAuth

Responses

Request samples 

curl --request GET \
  --url https://{baseurl}/api/users/next_user_id \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

04a Enroll Card Credential

Next step on creating a new user it to enroll the credential that the user will be using. Either it's Card, Face, Visual Face or Fingerprint.

This API is used to enroll card credential using the specified device.

Keep the card_id value on the response which shows after running this API to apply it to the user which will be created.

To view device(s) with capability to enroll a card, use View Device(s) Based on Enrollment Type API.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 543720368

ID of the device which will be used for enrollment

Responses

Request samples 

curl --request POST \
  --url https://{baseurl}/api/devices/543720368/scan_card \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

04b Enroll Face Credential

Use this API to enroll face credential from a device.

Set the pose_sensitivity to 0 if you're doing a Visual Face scan.

Keep the response of this API after running to apply it to the user which will be created.

To view device(s) with capability to enroll Face/Visual Face, use View Device(s) Based on Enrollment Type API.

Authorizations:
SessionAuth
path Parameters
id
required
integer
Example: 543408590

ID of the device which will be used to enroll

query Parameters
pose_sensitivity
integer
Example: pose_sensitivity=4

Set the sensitivity for the position, angle, and distance of a face when registering the face. Set the sensitivity high if you wish to obtain a detailed face template. 0-9

Responses

Request samples 

curl --request GET \
  --url 'https://{baseurl}/api/devices/543408590/credentials/face?pose_sensitivity=4' \
  --header 'bs-session-id: REPLACE_KEY_VALUE'

04c Enroll Fingerprint

Use this API to scan a fingerprint.

On calling this API, it is required to specify the device which will be used as fingerprint scanner. It is done by specifying Device ID on the API Path, which marked by :dev_id.

The procedure to add a fingerprint as follows:

  • Scan a finger using this API
  • Use POST /api/server_matching/identify_finger to check if it's already exist
  • If it's not exist, then run a second scan using this API for the same finger
  • Compare 1st and 2nd scan result using POST /api/devices/:dev_id/verify_fingerprint to make sure that 1st and 2nd scan are the same finger
  • After running Verify Fingerprint Scan, keep the value of template 0 and 1 to assign the enrolled finger to a user using POST|PUT /api/users/:id
Authorizations:
SessionAuth
path Parameters
dev_id
required
integer
Example: 544140034

Unique identifier of the device to perform fingerprint scanning

Request Body schema: application/json
required
object
noblockui
required
boolean

Responses

Request samples

Content type
application/json
{
  • "ScanFingerprintOption": {
    },
  • "noblockui": true
}

05 Create New User

After preparing available user_id and credential(s), use this API to create a new user using the basic configuration.

For applying configuration beyond this, such as credential(s) or custom fields, refer to the subsequent example.

When Setting > Server is set to Number, you can make use of endpoint /api/users/next_user_id to automatically get the next user_id.

Known validation errors:

  • name is more than 48 characters
  • Using single quote on name
  • Duplicate user_id, email, or login_id
  • Empty required fields
  • Using non-existent user_group_id
  • Password with 3 or more subsequent letter or number
  • Start and expiry date difference is more than 30 years
Authorizations:
SessionAuth
Request Body schema: application/json
required
required
object
user_id
required
string

ID of the User. Unique. When User ID Type in Setting → Server is set to Number, a number between 1 and 4294967295 can be entered.

When Alphanumeric is set, a combination of alphabetic characters and numbers can be entered. Do not use spaces when entering ID.

Numbers or Alphanumeric characters can be set for user_id. For more details, refer to Setting Section of this documentation.

name
string <= 48 characters

Name of the user. Up to 48 characters.

required
object

ID of the User Group that the user will be under Refer to User Group Section of this documentation for listing available User Groups.

disabled
boolean

Toggle User active or not; false for active, true for non-active

start_datetime
required
string <date-time>

Start active period for the User

expiry_datetime
required
string <date-time>

End active period for the User

email
string <email>

Email address of the User

department
string <= 64 characters

Department of the User. Up to 64 characters.

title
string

Title of the User

photo
string <base64>

Photo of the User (Base64 encoded)

phone
string

Phone number of the User

object

Operator Level of the User

Array of objects

ID of the Access Group that the User will have access. Refer to Access Group Section of this documentation for listing available Access Groups.
Can enter more than 1 Access Group.

login_id
string

Required when permission parameter is not removed.

password
string

Required when permission parameter is not removed.

user_ip
string

Limit the access of the User so he/she can only login from the registered IP Address. The user IP can be entered in the format xxx.xxx.xxx.xxx. Each octet can only be entered in numbers between 0 and 255. Users whose user IP is not registered can log in from any IP.

pin
integer <= 32 characters

PIN of the user. Maximum 32 digit.

Responses

Request samples

Content type
application/json
{
  • "User": {
    }
}