Online Identification Events

When an identification attempt occurs, the events described below are automatically sent by the device according to the online operating mode it is in: Pro Mode or Enterprise-mode. It is up to the external server to handle these events.

Biometric image event

Biometric identification attempt.

The HTTP method used is the POST. The contentType is the application/octet-stream. All parameters are passed through the query string, except the binary image.

This event is sent when the device operates in Enterprise Mode, that is, when the local_identification configuration is disabled, and only if the extract_template configuration is disabled.

POST /new_biometric_image.fcgi

Parameters

• device_id (int 64): Unique device ID.
• identifier_id (int): Identifier ID (Wiegand, RFID, biometrics), see identifier_id Formatting.
• width (int): Width, measured in pixels, of the image sent.
• height (int): Height, measured in pixels, of the image sent.
• session (string) : Session number.
• time (int) : Access time in Unix Timestamp.
• portal_id (int) : Portal identifier.
• uuid (string) : Universally Unique Identifier.
• variance (int) : Quality parameter of biometric identification.
• imagem (binary (octet-stream)): Binary image of the user biometrics. It is sent 1 byte per pixel in grayscale format (This is the only parameter sent in the request body).

Response

• result (JSON object) : Described in Return Message.

Biometric template event

Biometric identification attempt.

The HTTP method used is the POST. The contentType is the application/octet-stream. All parameters are sent through a query string, except the binary template.

This event is sent when the device operates in Enterprise Mode, that is, when the local_identification configuration is disabled, and only if the extract_template is enabled.

POST /new_biometric_template.fcgi

Parameters

• device_id (int 64): Unique device ID.
• identifier_id (int): Identifier ID (Wiegand, RFID, biometrics), see identifier_id Formatting.
• session (string) : Session number.
• time (int) : Access time in Unix Timestamp.
• portal_id (int) : Portal identifier.
• uuid (string) : Universally Unique Identifier.
• variance (int) : Quality parameter of biometric identification.
• Template (binary (octet-stream)) : Biometric template in Innovatrics format (This is the only parameter sent in the request body).

Response

• result (JSON object) : Described in Return Message.

Proximity card event

Identification attempt by proximity card.

The HTTP method used is the POST. The contentType is the application/x-www-form-urlencoded. All parameters are sent through a query string.

This event is sent when the device operates in Enterprise Mode, that is, when the local_identification configuration is disabled.

POST /new_card.fcgi

Parameters

• device_id (int 64): Unique device ID.
• identifier_id (int): Identifier ID (Wiegand, RFID, biometrics), see identifier_id Formatting.
• card_value (int 64): Card number.
• panic (int) : Indicates whether it is a panic card (1) or not (0).
• time (int) : Access time in Unix Timestamp.
• portal_id (int) : Portal identifier.
• uuid (string) : Universally Unique Identifier.
• block_read_error (int 64): If not 0, it means that an error happened in the block's reading. It will only be filled when mifare->read_block is not empty.
• block_read_data (string): Data read from a block in hex format (It is not possible to include base64 in an URL without losing some characters). It will only be filled when mifare->read_block is not empty.

Response

• result (JSON object) : Described in Return Message.

QR Code event

Identification attempt by QR Code.

The HTTP method used is the POST. The contentType is the application/x-www-form-urlencoded. All parameters are sent through a query string.

This event is sent when the device operates in Enterprise Mode, that is, when the local_identification configuration is disabled.

Observation: The device will send the QR Code event when the qrcode_legacy_mode_enabled parameter (from the barras module at V5 line devices, and face_id module at V6 line devices) is set to 0. If qrcode_legacy_mode_enabled is set to 1, QR Code readings will be interpreted the same way as cards readings.

POST /new_qrcode.fcgi

Parameters

• device_id (int 64): Unique device ID.
• identifier_id (int): Identifier ID (Wiegand, RFID, biometrics, etc), see identifier_id Formatting.
• qrcode_value (string): QR Code number.
• uuid (string) : Universally Unique Identifier.
• time (int) : Access time in Unix Timestamp.
• portal_id (int) : Portal identifier.

Response

• result (JSON object) : Described in Return Message.

UHF tag event

Identification attempt by UHF tag.

The HTTP method used is the POST. The contentType is the application/x-www-form-urlencoded. All parameters are sent through a query string.

This event is sent when the device operates in Enterprise Mode, that is, when the local_identification configuration is disabled.

POST /new_uhf_tag.fcgi

Parameters

• device_id (int 64) : Unique device ID.
• identifier_id (int) : Identifier ID (Wiegand, RFID, biometrics), see identifier_id Formatting.
• uhf_tag (string) : Value of UHF tag.
• uuid (string) : Universally Unique Identifier.
• time (int) : Access time in Unix Timestamp.
• portal_id (int) : Portal identifier.

Response

• result (Objeto JSON) : Described in Return Message.

ID and password event

Identification attempt by ID and password.

The HTTP method used is the POST. The contentType is the application/x-www-form-urlencoded. All parameters are sent through a query string.

This event is sent when the device operates in Enterprise Mode, that is, when the local_identification configuration is disabled.

POST /new_user_id_and_password.fcgi

Parameters

• device_id (int 64): Unique device ID.
• identifier_id (int): Identifier ID (Wiegand, RFID, biometrics), see identifier_id Formatting.
• user_id (int): ID typed by the user.
• password (string): Password typed by the user.
• time (int) : Access time in Unix Timestamp.
• portal_id (int) : Portal identifier.
• uuid (string) : Universally Unique Identifier.

Response

• result (JSON object) : Described in Return Message.

Identified user event

When the user identifies himself on the device, the device performs the identification locally and sends the ID of the identified user to the server. Then the server must process its access rules and grant or deny authorization.

Note that, using this method, the server must always keep users and their biometric data updated in the device, restricted to the limitation of existing records. This limitation is described in the topic Number of templates limitation.

The HTTP method used is the POST. The contentType is the application/x-www-form-urlencoded. All parameters are sent through a query string.

This event is sent when the device operates in Pro Mode, that is, when the local_identification is enabled.

POST /new_user_identified.fcgi

Parameters

• device_id (int 64): Unique device ID.
• identifier_id (int): Identifier ID (Wiegand, RFID, biometrics), see identifier_id formatting.
• component_id (int): ID of the component that performed the identification (exclusive for iDBlock Next), see identifier_id formatting.
• event (int): Identification response event, (e.g.: 3 for not identified).
• user_id (int): User ID.
• duress (int): This parameter returns an integer that indicates whether it is a panic finger or a simple identification (1 if panic finger or 0 for common identification).
• face_mask (bool): This parameter returns "true" if the identified user is wearing a mask or "false" otherwise.
• time (int) : Access time in Unix Timestamp.
• portal_id (int) : Portal identifier.
• uuid (string) : Universally Unique Identifier.
• block_read_data (string) : Value read from the indicated block of the card (only for MIFARE, when enabled).
• block_read_error (int) : Indicates if there was an error reading the value from block of the card (only for MIFARE, when enabled).
• card_value (int) : Value of the card used.
• qrcode_value (string) : Value of the QR Code used.
• uhf_tag (string) : Value of UHF tag.
• pin_value (string) : Value of the PIN used.
• user_has_image (int) : Indicates whether the user has an image (1) or not (2).
• user_name (string) : Username
• password (string) : Password provided by the user.
• confidence (int) : confidence parameter of the facial identification.
• log_type_id (int) : Send an attendance log type whenever there is an online identification event.

Response

• result (JSON object) : Described in Return Message.

Pushbutton access event

Indicates pushbutton access.

The HTTP method used is the POST. The contentType is the application/json. All sent parameters are available in the request body (JSON).

This event is sent when the device operates in Online Mode, that is, Enterprise Mode or Pro Mode.

POST /new_rex_log.fcgi

Parameters

• device_id (int 64): Unique device ID.
• rex_log (JSON object) : Object with the following parameters:
• • time (int): Time of the event in Unix Timestamp.
• • event (int): Opening event (11 for accesses made by pushbutton).
• • user_id (int 64): User ID.
• • portal_id (int 64): Corresponding portal ID.

Response

An empty response is expected (HTTP Status code OK).

identifier_id Formatting

The identifier_id field is present in the identification event requests sent by the access terminal. It contains an ID that represents the identifier mechanism (Wiegand, RFID, biometrics, etc) used and should be interpreted as follows:

The data type is a 32-bit integer. The three most significant bytes should be interpreted as ASCII characters, while the last byte should be interpreted as an integer value.

Example:

• "w" = 0x77 (ASCII)
• "i" = 0x69 (ASCII)
• "n" = 0x6E (ASCII)
• "0" = 0x00 (Binary)

The value "win0" represents Wiegand zero. Its conversion to the format described above produces the value 0x77696E00 in hexadecimal and becomes 2003398144 in decimal base.

Request user image from the server

The device will request the user's picture to the server whenever in the identification events responses, the parameter user_image is true (indicating that the user has a picture).

The HTTP method used is the GET. The contentType is the application/octet-stream. All parameters are sent through a query string.

GET /user_get_image.fcgi

Parameters

• user_id (int): User ID.

Response

• imagem (octet-stream) : Photo of the requested user in BMP, JPG/JPEG or PNG formats;

Check server availability

If the device fails to communicate with the server for three attempts in a row, it will enter contingency mode. The number of attempts is a configurable parameter.

In this mode, all identifications are made using only the device's local registers, which must be up-to-date.

Every minute, the device sends a new POST/device_is_alive request to the server with the number of logs available in the request body (JSON). Once it gets a response (HTTP status code OK), it returns to its original operation mode.

The HTTP method used is the POST. The contentType is the application/json.

POST /device_is_alive.fcgi

Parameters

• access_logs (int): The number of logs available.

Response

An empty response is expected (HTTP Status code OK).

Return Message

Return message from the server to the device after an identification attempt event.

result

Result of the analysis of the identification attempt.

Field	Type	Description
event	int	Type of event, it can be: Invalid device Invalid identification rule parameters Not identified Pending Identification Identification time expired Access Denied Access Granted Pending access (used when access depends on more than one person) User is not administrator (used when a user tries to access the menu but is not an administrator) Non-identified access (when the portal is opened through the API and the reason is not informed) Access via pushbutton switch Access through WEB interface Cancel entry (iDBlock exclusive) No response (no action taken) Intercom access (iDFace exclusive)
user_id	int	User ID, in identification cases.
user_name	string	Username, in identification cases
user_image	bool	Identified user has a photo or not.
user_image_hash	string	If the identified user has an image, it sends the image hash (SHA1).
portal_id	string	Corresponding portal ID.
actions	JSON object array	Actions that must be performed by the device. Example: [ {"action":"door", "parameters":"door=1"}, {"action":"door", "parameters":"door=2"} ]
duress	int	This parameter returns an integer that indicates whether it is a panic finger or a simple identification (1 if panic finger or 0 for common identification).
message	string	Message to be shown on the display upon access.

Response examples

Response for iDAccess, iDFit, and iDBox devices

Authorizes access:

{
    "result": {
        "event": 7,
        "user_id": 6,
        "user_name": "Neal Caffrey",
        "user_image": false,
        "portal_id": 1,
        "actions":[
            {"action": "door", "parameters": "door=1"},
            {"action": "door", "parameters": "door=2"}
        ]
    }
}

Response for iDFlex, iDAccess Pro, and iDAccess Nano devices

Authorizes access:

{
    "result": {
        "event": 7,
        "user_id": 6,
        "user_name": "Neal Caffrey",
        "user_image": false,
        "portal_id": 1,
        "actions": [
            {"action": "sec_box", "parameters": "id=65793, reason=1"}
        ]
    }
}

Note: The reason parameter, defines the reason for opening (0 = Unknown, 1 = Authorized, 2 = Buttonhole, and 3 = WEB Command).

Specific answer for iDBlock turnstile

Authorizes access:

{
    "result": {
        "event": 7,
        "user_id": 6,
        "user_name": "Danny Boy",
        "user_image": false,
        "portal_id": 1,
        "actions": [
            {"action": "catra", "parameters": "allow=clockwise"}
        ]
    }
}

Note: The "clockwise " parameter opens the turnstile clockwise. Other possible values are "anticlockwise " or "both " which open the turnstile counterclockwise or both, respectively.