COSEC Devices API

User Guide

SECURITY SOLUTIONS
 SECURITY SOLUTIONS

COSEC Devices API

User Guide
Documentation Disclaimer
Matrix Comsec reserves the right to make changes in the design or components of the product as engineering and
manufacturing may warrant. Specifications are subject to change without notice.

This is a general documentation for all variants of the product. The product may not support all the features and
facilities described in the documentation.

Information in this documentation may change from time to time. Matrix Comsec reserves the right to revise
information in this publication for any reason without prior notice. Matrix Comsec makes no warranties with respect
to this documentation and disclaims any implied warranties. While every precaution has been taken in the
preparation of this system manual, Matrix Comsec assumes no responsibility for errors or omissions. Neither is any
liability assumed for damages resulting from the use of the information contained herein.

Neither Matrix Comsec nor its affiliates shall be liable to the buyer of this product or third parties for damages,
losses, costs or expenses incurred by the buyer or third parties as a result of: accident, misuse or abuse of this
product or unauthorized modifications, repairs or alterations to this product or failure to strictly comply with Matrix
Comsec operating and maintenance instructions.

Copyright
All rights reserved. No part of this system manual may be copied or reproduced in any form or by any means
without the prior written consent of Matrix Comsec.

Version 22
Release date: March 5, 2024
 Contents
List of Tables ............................................................................................................................................................ iii
About the Document ..................................................................................................................................... 1
Document Conventions........................................................................................................................................ 1
Document Organization ....................................................................................................................................... 2
Who Can Use This Document.............................................................................................................................. 2
API Overview .................................................................................................................................................. 3
How It Works........................................................................................................................................................ 3
Supported Devices............................................................................................................................................... 4
General Features ................................................................................................................................................. 4
What the User Should Know ................................................................................................................................ 5
Prerequisite .......................................................................................................................................................... 5
Authentication ...................................................................................................................................................... 5
HTTP Request-Response .................................................................................................................................... 5
Communication Flow ...................................................................................................................................................................... 7
Request Format .............................................................................................................................................................................. 7
Response Format ........................................................................................................................................................................... 8
URL Syntax..................................................................................................................................................................................... 9
Common Actions .......................................................................................................................................................................... 10
Additional Information ........................................................................................................................................ 11
Supported APIs ............................................................................................................................................ 12
Device Configuration ................................................................................................................................... 13
Basic Device Configuration ................................................................................................................................ 14
Function Key Configuration................................................................................................................................ 18
Reader Configuration ......................................................................................................................................... 19
Finger Reader Parameter Configuration ............................................................................................................ 23
Palm Sensor Parameter Configuration .............................................................................................................. 25
Enrollment Configuration.................................................................................................................................... 26
Access Settings Configuration ........................................................................................................................... 28
Alarm Configuration ........................................................................................................................................... 29
Date and Time Configuration ............................................................................................................................. 30
Door Features Configuration.............................................................................................................................. 33
System Timers Configuration............................................................................................................................. 35
Special Function Configuration .......................................................................................................................... 36
Internal/External Reader Configuration.............................................................................................................. 38
Device Display Configuration ............................................................................................................................. 40
Device-LED & Buzzer Cadence Configuration................................................................................................... 43
Multi-Language Support..................................................................................................................................... 45
To Download/Upload Multi-Language File ......................................................................................................... 46
To Select the Mode of Wiegand Interface.......................................................................................................... 48
Temperature Logging Configuration .................................................................................................................. 49
Face Mask Compulsion...................................................................................................................................... 51
Smart Card Format ............................................................................................................................................ 52
Smart Card Key Change .................................................................................................................................... 60
FR Settings ........................................................................................................................................................ 62
User Configuration ...................................................................................................................................... 65
Setting/Retrieving User Configuration................................................................................................................ 66
Setting a User Photo .......................................................................................................................................... 69
Deleting a User .................................................................................................................................................. 71
Setting User Credentials .................................................................................................................................... 71
Retrieving User Credentials ............................................................................................................................... 73
Deleting User Credentials .................................................................................................................................. 77
Enrollment .................................................................................................................................................... 78

Table of Contents i
 Enrolling a User.................................................................................................................................................. 79
Enrolling Special Cards...................................................................................................................................... 83
Read/Write Card ................................................................................................................................................ 84
Test Enrollment .................................................................................................................................................. 90
Events ........................................................................................................................................................... 91
Retrieving Events ............................................................................................................................................... 92
Retrieving Events in the TCP Socket ................................................................................................................. 95
Sending Commands to Device ................................................................................................................... 97
Cafeteria Reset and Recharge .................................................................................................................. 102
Verify Biometric and Open Door .............................................................................................................. 104
Temperature Reading ................................................................................................................................ 105
Error Responses ........................................................................................................................................ 106
API Response Codes ................................................................................................................................. 108
Appendix .................................................................................................................................................... 111
Event Configuration Reference ........................................................................................................................ 112

ii Table of Contents
 List of Tables
Table: Device Configuration Parameters........................................................................................................ 14
Table: Function Key Configuration Parameters.............................................................................................. 18
Table: Reader Configuration Parameters (All doors except COSEC ARC Controller) ................................... 19
Table: Reader Configuration Parameters (COSEC ARC Controllers only) .................................................... 21
Table: Finger Reader Parameter Configuration - Parameters........................................................................ 23
Table: Finger Reader Parameter Configuration - Parameters........................................................................ 25
Table: Enrollment Configuration Parameters.................................................................................................. 26
Table: Access Settings Configuration Parameters ......................................................................................... 28
Table: Alarm Configuration Parameters ......................................................................................................... 29
Table: Date and Time Configuration Parameters ........................................................................................... 30
Table: Door Features Configuration Parameters............................................................................................ 33
Table: System Timers Configuration Parameters........................................................................................... 35
Table: Special Function Configuration Parameters ........................................................................................ 36
Table: Internal/External Reader Configuration Parameters............................................................................ 38
Table: Device Display Settings Parameters ................................................................................................... 40
Table: LED & Buzzer Cadence Configuration Parameters............................................................................. 43
Table: Multi-Language Support Parameters................................................................................................... 45
Table: Download/Upload Multi-Language File - Parameters .......................................................................... 46
Table: Wiegand Interface Mode Parameters .................................................................................................. 48
Table: Temperature Logging Configuration Parameters ................................................................................ 49
Table: Smart Card Format Parameters .......................................................................................................... 51
Table: Smart Card Format Parameters .......................................................................................................... 52
Table: Smart Card Configuration Parameters - iClass 2K2 ............................................................................ 53
Table: Smart Card Configuration Parameters - iClass 16K2 .......................................................................... 54
Table: Smart Card Configuration Parameters - iClass 16K16 ........................................................................ 55
Table: Smart Card Configuration Parameters - Mifare 4K.............................................................................. 56
Table: Smart Card Configuration Parameters - Mifare 1K.............................................................................. 57
Table: Smart Card Key Change Parameters .................................................................................................. 60
Table: Smart Card Key Change Response .................................................................................................... 60
Table: FR Settings .......................................................................................................................................... 62
Table: User Configuration Parameters ........................................................................................................... 66
Table: Setting a User Photo - Parameters...................................................................................................... 69
Table: Delete User - Parameters .................................................................................................................... 71
Table: Setting User Credentials - Parameters ................................................................................................ 71
Table: Retrieving User Credentials - Parameters ........................................................................................... 73
Table: Deleting User Credentials - Parameters .............................................................................................. 77
Table: Enrolling User - Parameters ................................................................................................................ 79
Table: Enroll Special Cards - Parameters ...................................................................................................... 83
Table: Read/Write Card Parameters .............................................................................................................. 84
Table: Write Card Response .......................................................................................................................... 86
Table: Read Card Response .......................................................................................................................... 86
Table: Retrieving Events - Parameters........................................................................................................... 92
Table: Value Range for Event Sequence Numbers........................................................................................ 92
Table: Retrieving Events in the TCP Socket - Parameters............................................................................. 95
Table: List of Commands to Device................................................................................................................ 97
Table: Get Credential Count Command - Parameters.................................................................................... 98
Table: Open Door Command - Parameters.................................................................................................. 100
Table: Deleting Credentials for All Users - Parameters ................................................................................ 100
Table: Activate Aux Relay command - Parameters ...................................................................................... 100
Table: Deactivate Aux Relay command - Parameters.................................................................................. 101
Table: Deny User Command- Parameters ................................................................................................... 101
Table: Door Panic Command - Parameters.................................................................................................. 101
Table: Cafeteria Reset-Recharge - Parameters ........................................................................................... 102
Table: Smart Card Key Change Response .................................................................................................. 102
Table: Verify biometric and Open door- Parameters .................................................................................... 104
Table: Arguments and Valid Values ............................................................................................................. 105
Table: API Response Codes ........................................................................................................................ 108
Table: Universal Time Zone Reference ........................................................................................................ 111
Table: List of Events ..................................................................................................................................... 112
Table: Size of Event Fields ........................................................................................................................... 115
Table: User Events ....................................................................................................................................... 115
Table: Special Function Codes Reference ................................................................................................... 118
Table: Information of Bit 0 and Bit 1 ............................................................................................................. 119
Table: Information of Bit 4 and Bit 9 ............................................................................................................. 119
Table: Field 3 Detail (User Events) Reference ............................................................................................. 119
Table: Alarm Events ..................................................................................................................................... 120
Table: System Events................................................................................................................................... 124
Table: Cafeteria Events ................................................................................................................................ 128
About the Document

Welcome to the COSEC Devices API User Guide. This document will provide you a comprehensive overview and
complete user-guidance for all COSEC Devices APIs. You can learn more about COSEC APIs, browse through
detailed descriptions of individual APIs and test them using sample scenarios.

Document Conventions
This API User Guide will follow a set of document conventions to make it consistent and easier for you to read.
These are as follows:

1. Text within angle brackets (e.g. “<request-type>”) denotes content in URL syntax and should be replaced
with either a value or a string. The angle brackets should be ommitted in all instances except those used to
denote “tags” within XML responses (e.g. “<name></name>”).

2. Cross-references and other links appear as follows: Document Conventions

For e.g. To learn more about APIs, please refer to section Who Can Use This Document

3. The term device used in this document, will refer only to direct doors.

4. Any expression resembling <x~y>, indicates that the field should be repeated for index values x to index
values y. This is to avoid duplicating the same parameter for multiple index numbers.

5. Additional information about any section appears in the form of notices. The following symbols have been
used for notices to draw your attention to important items.

Important: to indicate something that requires your special attention or to remind you of
something you might need to do when you are using the system.

Caution: to indicate an action or condition that is likely to result in malfunction or damage to the
system or your property.

Warning: to indicate a hazard or an action that will cause damage to the system and or cause
bodily harm to the user.

Tip: to indicate a helpful hint giving you an alternative way to operate the system or carry out a
procedure, or use a feature more efficiently.

Matrix COSEC Devices API User Guide 1

Document Organization
This document has been organized into the following topics:

1. About the Document

2. API Overview
3. Supported APIs
4. Details of APIs
5. Error Responses
6. API Response Codes
7. Appendix

Topics 1 and 2 will provide a general understanding of COSEC Devices APIs and the basic interface
communication. Topic 3 provides a list of all supported APIs. Topics 4 provide an overview of API categories with
detailed explanation of individual APIs. The following information has been provided on each request type:

• Description of the functionality.

• Action requested.
• Generic query syntax.
• Mandatory and optional parameters (argument-value table).
• Examples (Sample Request and Sample Response).

Topic 5 provides illustrations of error messages. Topic 6 provides a list of API Response Codes and their meaning.
The Appendix will provide additional material for the user’s reference.

For a list of all tables provided in the document, refer to List of Tables. Click on the links to view the
respective tables for the required data.

Who Can Use This Document

The COSEC Devices API User Guide is meant for third-party software developers who wish to operate COSEC
Devices via another remote application. This guide will provide information to users on how to request and receive
services from COSEC Devices using a COSEC API.

2 Matrix COSEC Devices API User Guide

API Overview

COSEC Devices APIs provide an interface for communication with COSEC Devices via HTTP methods. These
APIs will enable specific functions to be performed on your remote devices such as setting basic and advanced
device configurations, configuring users on device, performing enrollment of credentials, monitoring events and
sending commands to device. For a complete list of COSEC Device APIs, refer to Supported APIs.

How It Works
Following is an illustration of how the COSEC system typically communicates in a client-server based architecture.

Monitor Utility is only applicable

for COSEC Centra

COSEC
VMS Utility Devices Monitor
Utility
Enroll Utility

Identification
Ser vice

Integrate
Utility 5 Browser
4 Admin Por tal
1
via API

Browser
COSEC Web Other Utilities work similar to
Enroll U tility shown by pink
arrows.

2 3

Request Response with

for Ser vice URL
Ser vice URL
6
Visitor
Service
Any change in Tenant/DB/
License/Ser vice details will send refresh
Enroll Admin Portal
Service Web to relevant components.

Master Service
COSEC Alert
Web (Central Mapping Service)
Service

Start-up
Request
Response
with
Admin Portal list of
Service Monitor
tenants Service
and details

Tenant- License details

Admin Portal Database
Database details
Ser vice details.

Database Server

COSEC Database

Matrix COSEC Devices API User Guide 3

However, here the communication with COSEC devices occurs via the COSEC Web server. On the other hand,
Devices APIs enable a client application to access and monitor a remotely installed COSEC device directly, without
installing the COSEC server/Monitor.

HTTP Request

HTTP Response

Direct Door 3rd Party Application

Fig. Communication through COSEC API

Using APIs, the third party can send a simple HTTP request to configure, control or command a device. The device
then processes and executes this request to return an appropriate response.

Supported Devices
COSEC Devices APIs are dependant on the device type. Currently, Device APIs are supported on the following
COSEC Door Controllers and their variants:

• COSEC Direct Door V2

• COSEC Direct Door V3
• COSEC Direct Door V4
• COSEC Path Controller
• COSEC Wireless Door
• COSEC NGT Door
• COSEC PVR Door
• COSEC Vega Controller
• COSEC Argo Controller
• COSEC ARC Controller
• COSEC Door FMX
• COSEC ARGO FACE Door

General Features
All COSEC APIs -

• Are Web-based HTTP APIs.

• Use basic HTTP Request-Response for interface communication.

• Generate response in either text or XML (Extensible Markup Language) format.

• Use simple HTTP commands such as GET, SET, DELETE etc.

• Use a generic syntax for all queries.

• Support some predefined parameters and their corresponding values for each action. Each parameter will
either be mandatory or bear a system-defined default value (when no value is specified).

4 Matrix COSEC Devices API User Guide

 • Use a mandatory parameter action universally, which takes action values (such as get, set, delete etc.)
and specifies the action to be requested.

What the User Should Know

It is assumed that developers using this document have prior knowledge of:

• Basic functioning of the COSEC system

• Basic HTTP request-response communication

• XML

Prerequisite
In order to use a COSEC API, the user will require:

• A COSEC Device (pre-installed)

• A network enabled for accessing the COSEC Device.

• The credentials for API Authentication

For information on installing a COSEC device and assigning an IP address to it, please refer to the
respective device documentation.

Authentication
The device shall request basic authentication for granting access. Default username and password for HTTP
session authentication are:

Username: admin
Password: password set on device

HTTP Request-Response
Basic HTTP communication is based on a request-response paradigm. The message structure for both request
and response has a generic format.

HTTP-message = Request | Response ; HTTP/1.1 messages

Generic-message = start-line The start line

*(message-header CRLF) Zero or more header fields or ‘headers’

CRLF An empty line

[Message-body] A message-body (chunk or payload)

Matrix COSEC Devices API User Guide 5

Start-line = Request-Line | Status-Line

6 Matrix COSEC Devices API User Guide

Communication Flow
The communication takes place in the following manner:

1. The client checks availability of the device.

2. If available, the client issues a request for the device.

SER VER C LIEN T

C os ec 3 rd party
D ev ic e s oftw are

R E Q U E S T: w ith s y ntax, but no authentic ation / inv alid authentic ation

R E S P O N S E: denied
R es pons e s tatus c ode ( 4x x ) along w ith s ugges tions of s upported
authentic ation m ethod

R E Q U E S T: inv alid s y ntax but v alid authentic ation

R E S P O N S E: denied
R es pons e s tatus c ode (4x x )

R E Q U E S T: w ith s y ntax and s upported pas s w ord authentic ation

R E S P O N S E: s uc c es s ful
R eques ted M es s age body along w ith res pons e s tatus c ode i .e 2x x

R E Q U E S T: the s erv er is not

c onnec ted

Fig: c om m unic ation flow

3. The device parses the request for the action to be taken.

4. In case of an error (invalid syntax, invalid authentication etc.), the request is denied and an error response
is returned. Else, the requested data is returned with the appropriate response code.

Request Format

All HTTP Requests follow a generic message format. It consists of the following components:

This line is constituted by the following three elements which must be

separated by a space:

• The method type (GET, HEAD, POST, PUT etc.)

1. Request Line • The requested URL

• The HTTP version to use

For e.g.:

GET http://192.168.1.2/device.cgi/command?action=geteventcount HTTP/1.0

Matrix COSEC Devices API User Guide 7

 Add information about the request using these header fields:

• A General Header (<Header-name>:<value>).

2. Header Fields
• A Request Header (<Header-name>:<value>).

• An Entity Header (<Header-name>:<value>).

3 Empty Line This is an empty line separating headers from the message body.

4 Message Body This is the chunk or payload.

Example:

GET http://matrix.com/ HTTP/1.0

Accept: text/html
If-Modified-Since: Saturday, 15-January-2000 14:37:11 GMT
User-Agent: Mozilla/4.0 (compatible; MSIE 5.0; Windows 95)

Response Format
An HTTP response is a collection of lines sent by the server to the client. A generic HTTP response format will
resemble the following:

VERSION-HTTP CODE EXPLANATION<crlf>

HEADER: Value<crlf>
.
.
.
HEADER: Value<crlf>
Empty line<crlf>
BODY OF THE RESPONSE

It consists of the following components:

This line is constituted by the following three elements which must be

separated by a space:

1. A status line • The version of the protocol used (e.g. HTTP/1.0).

• The status code (indicates the status of the request being
processed).
• The explanation of the code.

These optional lines allow additional information to be added to the

response header. This information appears in the form of a name
2. The response header fields
indicating the header type followed by a value for the header type. The
name and value are separated by a colon (:).

3. The body of the response Contains the requested data.

8 Matrix COSEC Devices API User Guide

Example
When the server gets a request, it will respond with a standard HTTP status code as illustrated in the following
sample response:

HTTP/1.0 200 OK
Date: Sat, 15 Jan 2000 14:37:12 GMT
Server: Microsoft-IIS/2.0
Content-Type: text/HTML
Content-Length: 1245
Last-Modified: Fri, 14 Jan 2000 08:25:13
GMT

HTTP Status Codes: Status codes are 3-digit numeric codes returned in HTTP responses that enable
recipients to understand the successful or failed status of the request issued. In general, codes in the 1xx
range indicate an informational message only, 2xx codes indicate a successful request, 3xx codes indicate
an incomplete request that requires further action, 4xx codes point at client-side errors while 5xx codes
point at server-side errors.

URL Syntax
All COSEC APIs follow a common HTTP query syntax for the third party to generate a request. The generic URL is
stated below.

Syntax

http://<deviceIP:deviceport>/device.cgi/<request-type>?<argument>=<value>&<argument>=<value>......

Take a close look at the URL and its basic elements:

URL element Description

This is the protocol used to communicate with the client.

http://
Note: All HTTP commands are in plain text, and almost all HTTP requests
are sent using TCP port 80, though any port can be used.

This identifies the device with which communication is to be performed. It

consists of two components:
<deviceIP:deviceport>
deviceIP: Device IP address
deviceport: Device Port Number (Default- 80)

This is a mandatory entity required to specify the CGI directory for all the
device.cgi
device-related commands.

This specifies the type of API request. For the mandatory request types,
<request-type>
please refer to the individual API descriptions.

Matrix COSEC Devices API User Guide 9

 URL element Description

This defines a specific action or command depending on the function to be

performed.
A mandatory argument for all COSEC API functions is action. This
<argument>
argument always takes an action as its value (For eg. action=get).
For more information on the common HTTP actions used in COSEC APIs,
please refer to section Common Actions.

<value> These are argument values that determine the output.

Example

Let us assume that the target device has the IP address 192.168.x.y and the device port number is 80. The user
wants to fetch basic configured parameters for the device. In this case, a sample request would resemble the
following:

http://192.168.x.y:80/device.cgi/device-basic-config?action=get&format=xml

In this case, the query uses an action=get parameter which is commonly used to retrieve information from the
device-side. The URL takes another argument called format which specifies that the response returned should be
in the XML format.

• Special characters ( &, ‘, “, <, >, #, % and ;) will not be allowed in arguments or their values. Special
character “&” will be allowed as a separator between consecutive arguments and “?” will be allowed as
a separator between the request-type and an argument.

• The request line and headers must all end with <CR><LF> that is carriage return character followed by
a line feed character.

• The status line and header must all end with <CR><LF>.

• The empty line must consist of only <CR><LF> and no other white space.

Common Actions

The following actions are commonly used in COSEC APIs as values for the ‘action’ argument:

Action Use

GET To fetch required data from device.

SET To set required parameters for a given function.

This is used to get default the parameters of all/ specified

argument. If any argument is specified then default value of
GETDEFAULT
that particular argument is returned else default value of
complete group is returned.

This is used to default the parameters. If any argument is

SETDEFAULT specified then default that particular value else default
complete group

10 Matrix COSEC Devices API User Guide

 Action Use

DELETE To delete data from device.

ENROLL To enroll an entity to a device.

Additional Information
• Generally, all the commands will be supported in the GET Method and hence the arguments and valid
values will be expected in the URL. Wherever applicable POST method will be specified explicitly. For the
POST method, the parameters must be included in the body of the HTTP request.

• To set blank values in a particular field, a blank can follow the “=”. E.g. “argument=&”

• If the format is not specified then by default, the values should be returned in text format.

• For all arguments other than ‘action’, the position in the URL may be changed.

COSEC APIs use basic authentication and can be tested on any standard Web browser. Enter the request
URL in the address field of your browser and press the ‘Enter’ key to send query to the device. Enter the
authentication credentials when prompted. The response will be displayed on your browser in the specified
format.

Matrix COSEC Devices API User Guide 11

Supported APIs

COSEC Devices support the following groups of APIs categorized on the basis of functions to be performed:

• Device Configuration
• User Configuration
• Enrollment
• Events
• Sending Commands to Device
• Access Request on QR Scanning
• Cafeteria Reset and Recharge
• Get Random Key
• Verify Biometric and Open Door

12 Matrix COSEC System Manual

Device Configuration

This group of APIs enables users to perform the following types of device configuration:

• Basic Device Configuration

• Function Key Configuration

• Reader Configuration

• Finger Reader Parameter Configuration

• Palm Sensor Parameter Configuration

• Enrollment Configuration

• Access Settings Configuration

• Alarm Configuration

• Date and Time Configuration

• Door Features Configuration

• System Timers Configuration

• Special Function Configuration

• Internal/External Reader Configuration

• Device Display Configuration

• Device-LED & Buzzer Cadence Configuration

• Multi-Language Support

• To Download/Upload Multi-Language File

• To Select the Mode of Wiegand Interface

• Temperature Logging Configuration

• Face Mask Compulsion

• Smart Card Format

• Smart Card Key Change

• FR Settings

Matrix COSEC Devices API User Guide 13

Basic Device Configuration
Description: To set or retrieve basic configuration parameters for a device such as application type, name,
Additional Security Code and maximum number of finger templates on device.

Actions: get, set, getdefault, setdefault

Syntax: http://<deviceIP:deviceport>/device.cgi/device-basic-config?action=<value>&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Device Configuration Parameters

Argument Valid Values Mandatory Description

1, 2
To define the application.
app 1 = Advanced Access Control No
2 = Basic Access Control

Alphanumeric,
name No To identify/configure the device name.
Max. 30 characters

To configure an Additional Security Code

Numeric, 16 bits,
asc-code No (ASC). Should be non-zero. Not
1-65535 range
applicable for ARGO FACE200T.

Single Template/Finger: 0-9

where,
0 - 1 Finger
1 - 2 Fingers
2 - 3 Fingers
3 - 4 Fingers
4 - 5 Fingers
5 - 6 Fingers
6 - 7 Fingers
7 - 8 Fingers Maximum no. of finger templates that can
max-fingers No
8 - 9 Fingers be stored per user on this device.
9 - 10 Fingers

Dual Template/Finger: 0-4

where,
0 - 1 Finger
1 - 2 Fingers
2 - 3 Fingers
3 - 4 Fingers
4 - 5 Fingers

14 Matrix COSEC Devices API User Guide

Table: Device Configuration Parameters

Argument Valid Values Mandatory Description

0 - 1 Palm
1 - 2 Palms
2 - 3 Palms
3 - 4 Palms
4 - 5 Palms Maximum no. of palm templates that can
max-palms 5 - 6 Palms No be stored per user on this device.
6 - 7 Palms
7 - 8 Palms
8 - 9 Palms
9 - 10 Palms

0 - 1 Face
1 - 2 Face
2 - 3 Face
3 - 4 Face
4 - 5 Face
5 - 6 Face
6 - 7 Face
7 - 8 Face
8 - 9 Face
9 - 10 Face
10 - 11 Face
11 - 12 Face
12 - 13 Face
13 - 14 Face
14 - 15 Face Maximum no. of templates that can be
max-faces No
15 - 16 Face stored per user on this device.
16 - 17 Face
17 - 18 Face
18 - 19 Face
19 - 20 Face
20 - 21 Face
21 - 22 Face
22 - 23 Face
23 - 24 Face
24 - 25 Face
25 - 26 Face
26 - 27 Face
27 - 28 Face
28 - 29 Face
29 - 30 Face

generate-
0 - No To generate invalid user events when
invalid-user- No
1 - Yes invalid user is punched in.
events

generate-exit- 0 - No To generate exit switch events. Not

No
switch-events 1 - Yes applicable for ARGO FACE200T.

Matrix COSEC Devices API User Guide 15

Table: Device Configuration Parameters

Argument Valid Values Mandatory Description

To enable the custom key for mifare card

mifare-custom- 0 - Disable
No variants. Not applicable for ARGO
key-enable 1 - Enable
FACE200T.

Numeric To define custom keys for Mifare card

mifare-custom-
No variants. Not applicable for ARGO
key
6 Bytes (12 Hex Digits) FACE200T.

hid-iclass- To enable the custom key for hid-iclass

0 - Disable
custom-key- No variants. Not applicable for ARGO
1 - Enable
enable FACE200T.

To define custom keys for HID i-class

hid-iclass-
8 Bytes (16 Hex Digits) No card variants. Not applicable for ARGO
custom-key
FACE200T.

card-custom-
0 - Disable To enable the auto update of custom key.
key-auto- No
1 - Enable Not applicable for ARGO FACE200T.
update

To set the mode of the finger template.

0 - Proprietary
finger-format No By default, proprietary format will be
1 - ISO
selected.

manual-door- 0 - Disable To enable/disable the Door Mode

No
mode-selection 1 - Enable Selection feature

specifies the format in which the

format text, xml No
response is expected.

For parameters “mifare-custom-key” and “hid-iclass-custom-key”; “Get & get default action are not
applicable.

The Additional Security Code is a code that can be written on a smart card for adding an additional layer
of security check during door access.

To get the default values for any parameter, use the action= getdefault method. To restore configuration
parameters on device to default values, use the action= setdefault method.

For ARC IO800, Valid Parameters: action, name, format.

Example
Following are some test cases for your reference:

1. To get all parameters.

Sample Request

http://<deviceIP:deviceport>/device.cgi/device-basic-config?action=get

16 Matrix COSEC Devices API User Guide

 Sample Response

HTTP Code: 200 OK

Content-Type: <code>
Content-Length: <type>
Body:
app=1 name=NGT Direct Door-Device-11 asc-code=0 generate-invalid-user-events=0 generate-exit-switch-
events=0 max-fingers=1 finger-format=0

2. To get device name, when expected value is blank and the response format is in text.

Sample Request

http://<deviceIP:deviceport>/device.cgi/device-basic-config?action=get&name&app

Sample Response

HTTP Code: 200 OK

Content-Type: <code>
Content-Length: <type>
Body:
app=1 name=NGT Direct Door-Device-11

3. To get device name, when the expected value is blank and the response format is XML.

Sample Request

http://<deviceIP:deviceport>/device.cgi/device-basic-config?action=get&name&app&format=xml

Sample Response
HTTP Code: 200 OK
Content-Type: <code>
Content-Length: <type>
Body:
<COSEC_API>
<app>1</app>
<name>NGT Direct Door-Device-11</name>
</COSEC_API>

4. To set device name as blank – Valid argument.

Sample Request

http://<deviceIP:deviceport>/device.cgi/device-basic-config?action=set&name=

Sample Response
HTTP Code: 200 OK
Content-Type: <code>
Content-Length: <type>
Body: Response-Code=0

Matrix COSEC Devices API User Guide 17

Function Key Configuration
Description: To set or retrieve configuration of Function Keys on the Device keypad. COSEC enables its users to
map up to 4 special functions to the arrow keys on a Direct Door keypad. These functions can then be performed at
the door by using the keypad shortcuts. Use this API to specify which special functions are to be assigned shortcuts
on COSEC devices.

Actions: get, set, getdefault, setdefault

Syntax: http://<deviceIP:deviceport>/device.cgi/function-key?action=<value>&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Function Key Configuration Parameters

Argument Valid Values Mandatory Description

F1 0 = None
1 = Official IN
F2
2 = Official OUT
F3 3 = Short Leave IN
4 = Short Leave OUT Assigning special functions to
5 = Regular IN No respective function keys.
6 = Regular OUT
F4 7 = Post Break IN
8 = Pre - Break OUT
9 = Overtime IN
10 = Overtime OUT

Specifies the format in which the

format text, XML No
response is expected.

Example
1. To configure function key F1 as official work – IN.

Sample Request
http://<deviceIP:deviceport>/device.cgi/function-key?action=set&f1=1

Sample Response
HTTP Code: 200 OK
Content-Type: <type>
Content-Length: <length>
Body: Response-Code=0

18 Matrix COSEC Devices API User Guide

Reader Configuration
Description: To set or retrieve configuration parameters for internal and external readers such as reader type,
access mode, entry-exit mode and the tag re-detection delay time.

Actions: get, set, getdefault, setdefault

Syntax: http://<deviceIP:deviceport>/device.cgi/reader-config?action=<value>&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Reader Configuration Parameters (All doors except COSEC ARC Controller)

Argument Valid Values Mandatory Description

0 = None
1 = EM Prox Reader
To define the internal card
2 = HID Prox Reader
reader1 No reader. Not applicable for
3 = MiFare Reader
ARGO FACE200T.
4 = HID iCLASS-U Reader
5 = HID iCLASS-W Reader

0 = None To define the internal biometric

reader2 1 = Finger Reader No reader. Not applicable for
2 = Palm Vein Reader ARGO FACE200T.

0 = None
1 = EM Prox Reader
2 = HID Prox Reader
3 = MiFare U Reader
4 = HID iCLASS-U Reader
5 = Finger Reader
6 = HID iCLASS-W Reader
8 = UHF Reader To define the external reader.
reader3 9 = Combo Exit Reader No Not applicable for ARGO
10 = MiFare-W Reader FACE200T.
11= PIN-W-Reader
12=Card+Pin-W-Reader
13=CB-U-Reader
14=CB-W-Reader
15=ATOM-1
16=ATOM-2
17=ATOM-3

Matrix COSEC Devices API User Guide 19

Table: Reader Configuration Parameters (All doors except COSEC ARC Controller)

Argument Valid Values Mandatory Description

0 = Card
1 = Finger
2 = Card + PIN
3 = PIN + Finger
4 = Card + Finger
5 = Card + PIN + Finger
6 = Any
7 = Palm
8 = Palm + PIN
9 = Card + Palm To define the access mode
door-access-mode No
10 = Card + PIN + Palm applicable for door access.
11 = Palm + Group (Optional)
12 = Finger then Card
13 = Palm then Card
14= None
15= Face
16= Card & Face
17= PIN & Face
18= finger & Face
20= Card then Biometrics

To define the whether the

0 = Entry
door-entry-exit-mode No internal reader is to be set on an
1 = Exit
entry or exit mode.

To define the access mode

0 = Card
applicable for the external
1 = Biometric
reader.Not applicable for
2 = Card + PIN
ARGO FACE200T.
3 = Biometric + PIN
4 = Biometric + Card
reader-access-mode No reader-access-mode= 2, 3 and 5
5 = Biometric + Card + PIN
are only applicable for Vega,
6 = Any One
Argo, Argo Face and PathV2.
12 = Biometric then Card
19 = BLE
20 = Card then Biometrics

To define the whether the

external reader is to be set on an
0 = Entry
reader-entry-exit-mode No entry or exit mode. Not
1 = Exit
applicable for ARGO
FACE200T.

To define the tag re-detection

tag-re-detect-delay 00 - 3600 seconds No delay time. Not applicable for
ARGO FACE200T.

Specifies the format in which the

format text, XML No
response is expected.

20 Matrix COSEC Devices API User Guide

Table: Reader Configuration Parameters (COSEC ARC Controllers only)

Argument Valid Values Mandatory Description

0 = None
1 = EM Prox Reader
2 = HID Prox Reader
3 = MiFare Reader
4 = HID iCLASS-U Reader To define the RS-485 reader in
rs-485-readergrp1 No
5 = Combo Reader reader1 group.
13= CB-U Reader
15= ATOM-1
16= ATOM-2
17= ATOM-3

0 = None
To define the Wiegand reader in
1 = Short-Range Reader
reader1 group. PIN-W-Reader
2 = Long-Range Reader
wiegand-readergrp1 No and Card+ PIN-W Reader, Cb-W
11= PIN- W-Reader
Reader is applicable for ARC
12= Card +PIN-W Reader
DC 200 only.
14= CB -W Reader

readergrp1-entry-exit- 0 = Entry To define the mode (entry/exit)

No
mode 1 = Exit for reader1 group

0 = Card
1 = Finger
readergrp1-access- 4 = Card + Finger To define the access mode
No
mode 6 = Any applicable for reader1 group.
12 = Finger then Card
20= Card then Biometrics

0 = None
1 = EM Prox Reader
2 = HID Prox Reader
3 = MiFare Reader
4 = HID iCLASS-U Reader To define the RS-485 reader in
rs-485-readergrp2 No
5 = Combo Reader reader2 group.
13= CB-U Reader
15= ATOM-1
16= ATOM-2
17= ATOM-3

0 = None
To define the Wiegand reader in
1 = Short-Range Reader
reader2 group.PIN-W-Reader
2 = Long-Range Reader
wiegand-readergrp2 No and Card+ PIN-W Reader, Cb-W
11= PIN- W-Reader
Reader is applicable for ARC
12= Card +PIN-W Reader
DC 200 only.
14= CB -W Reader

readergrp2-entry-exit- 0 = Entry To define the mode (entry/exit)

No
mode 1 = Exit for reader2 group

0 = Card
1 = Finger
readergrp2-access- 4 = Card + Finger To define the access mode
No
mode 6 = Any applicable for reader2 group.
12 = Finger then Card
20= Card then Biometrics

Matrix COSEC Devices API User Guide 21

Table: Reader Configuration Parameters (COSEC ARC Controllers only)

Argument Valid Values Mandatory Description

To define the tag re-detection

tag-re-detect-delay 00 - 3600 seconds No
delay time.

Example

1. To configure internal card reader as an HID Prox reader and internal reader mode as entry.

Sample Request
http://<deviceIP:deviceport>/device.cgi/reader-config?action=set&reader1=2&door-access-mode=0

Sample Response
HTTP Code: 200 OK
Content-Type: <type>
Content-Length: <length>
Body: Response-Code=0

22 Matrix COSEC Devices API User Guide

Finger Reader Parameter Configuration
Description: To set the finger reader calibration for fingerprint enrollment.

Actions: get, set, getdefault, setdefault

Syntax: http://<deviceIP:deviceport>/device.cgi /finger-parameter?<argument>=<value>&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Finger Reader Parameter Configuration - Parameters

Argument Valid Values Mandatory Description

0 = Level 1 (Low)
1 = Level 2 To define the security type
2 = Level 3 while enrollment.
3 = Level 4 Note:
security Yes
4 = Level 5 (High) 0-4 is only applicable for FMX.
0-2 is applicable for suprema
Default = 0 (For Suprema device) based devices.
Default = 2 (For Lumidigm device)

0 = Out door
1 = In door To define the lighting condition.
lighting-condition No

Default =1

0 = Level 1 (Low)
1 = Level 2
2 = Level 3
To define the sensitivity levels
3 = Level 4
from low to high.
4 = Level 5
Note:
sensitivity 5 = Level 6 No
0-2 is only applicable for FMX.
6 = Level 7
0-7 is applicable for suprema
7 = Level 8 (High)
based devices.

Default = 7 (For Suprema device)

Default = 1 (For Lumidigm device)

0 = Mode 1 (Normal)
1 = Mode 2
2 = Mode 3
3 = Mode 4 To define the mode to be used
fast-mode 4 = Mode 5 No during enrollment.
5 = Mode 6 (Fastest)
6 = Auto

Default = 6

Matrix COSEC Devices API User Guide 23

Table: Finger Reader Parameter Configuration - Parameters

Argument Valid Values Mandatory Description

0 = Weak
1 = Moderate
To define the acceptable
2 = Strong
image-quality No image quality for enrollment.
3 = Strongest

Default = 1

Specifies the format in which

format text,xml No
the response is expected

24 Matrix COSEC Devices API User Guide

Palm Sensor Parameter Configuration
Description: To set the palm sensor calibration for palm enrollment.

Actions: get, set, getdefault, setdefault

Syntax: http://<deviceIP:deviceport>/device.cgi /palm-parameter?<argument>=<value>&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Finger Reader Parameter Configuration - Parameters

Argument Valid Values Mandatory Description

0 = Normal
1 = Highest
2 = High
To define the security type
security 3 = Low Yes
while enrollment.
4 = Lowest

Default = 2

0 to 9999 sec
palm-matching- To define the palm matching
No
timeout timeout.
Default = 15 sec

0 = Good
1 = Moderate
To define the acceptable
palm-temp-quality 2 = Poor No
image quality for enrollment.

Default = 1

Specifies the format in which

format text, XML No
the response is expected.

0 = Inactive
custom-palm-app-key- 1 = Active No
To enable the custom key.
enable
Default = 0

It specifies the custom key

Alphanumeric: No
custom-palm-app-key used for identification and
16 characters
verification.

Matrix COSEC Devices API User Guide 25

Enrollment Configuration
Description: To set or retrieve configuration parameters for enrollment of credentials on a device such as number
of credentials allowed, number of templates allowed per finger, enrollment mode etc.

Actions: get, set, getdefault, setdefault

Syntax: http://<deviceIP:deviceport>/device.cgi/enroll-options?action=<value>&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Enrollment Configuration Parameters

Argument Valid Values Mandatory Description

0 = Inactive To enable/disable the feature to enroll

enroll-on-device No
1 = Active through special function

To define the option to enroll the credential

using the user’s Reference No. or User ID,
for enrollment through special function.
0 = User ID
enroll-using No
1 = Reference No. Note: This parameter will not be valid for
NGT Direct Door and Vega Controller
where enrollment must be performed by
User ID.

0 = Single Template/
No To define the number of templates to be
temp-per-finger Finger
saved per finger.
1 = Dual Template/Finger

Single Template/Finger: 0-
9

where,
0 = 1 Finger
1 = 2 Fingers
2 = 3 Fingers
3 = 4 Fingers
4 = 5 Fingers No. of fingers allowed to be enrolled in one
5 = 6 Fingers enrollment cycle.
6 = 7 Fingers
enroll-finger-count 7= 8 Fingers No Note: For the action=set method, this
8 = 9 Fingers value should not be greater than the max-
9 = 10 Fingers finger value set in Basic Device
Configuration API.
Dual Template/Finger: 0-4

where,
0 = 1 Finger
1 = 2 Fingers
2 = 3 Fingers
3 = 4 Fingers
4 = 5 Fingers

26 Matrix COSEC Devices API User Guide

Table: Enrollment Configuration Parameters

Argument Valid Values Mandatory Description

0 = 1 Palm
1 = 2 Palms
2 = 3 Palms
3 = 4 Palms
No. of palms allowed to be enrolled in one
4 = 5 Palms
enroll-palm-count No enrollment cycle.
5 = 6 Palms
6 = 7 Palms
7 = 8 Palms
8 = 9 Palms
9 = 10 Palms

0 = 1 Card No. of special function cards allowed to be

1 = 2 Cards enrolled in one enrollment cycle. Not
enroll-card-count No
2 = 3 Cards applicable for ARGO FACE200T.
3 = 4 Cards

0 = Read Only Card

To define the enrollment mode for
1 = Smart Card
enrollment through device.
2 = Biometric
enroll-mode No enroll-mode=0 and 1, that is, Read Only
3 = Biometric then Card
Card and Smart Card is not applicable for
7 = Face
ARGO FACE200T.
8 =Duress Finger

To specify whether the enrollment is in

0 = Non-guide mode
palm-operation-mode No Guide mode or Non-guide mode for the
1 = Guide mode
COSEC PVR Door.

0=Basic Template To define whether PVR is running in

palm mode adaptive No
1=Compressed Template Adaptive mode or not

0 = Disable To enable/disable self-enrollment on

self-enrollment-enable No
1 = Enable device.

self-enrollment-retry- To specify the self-enrollment retry count

0 - 255 No
count for users.

Specifies the format in which the response

format text, XML No
is expected.

• If the temp-per-finger mode is changed, then the templates have to be restored to the device explicitly
by the third party software, else mismatch will occur in the module.
• If Single Template/Finger mode is selected on the device and some users are already enrolled
according to it and if abruptly the mode is changed to Dual Template/Finger then:

i. If the maximum finger count was greater than 5 fingers in Single Template/Finger mode, then after
changing the mode to the Dual Template/Finger, the finger count will set to 5.

ii. If the maximum finger count was less than 5 fingers in Single Template/Finger mode, then after
changing the mode to the Dual Template/Finger, the finger count will remain same.

• If the mode is changed back to Single Template/Finger, then finger count should not be changed. If
users want to increase the finger count they should mention it explicitly.
• The palm adaptive mode is by default disabled, if enabled, device will generate one additional
compressed palm template and store it as 11th palm template

Matrix COSEC Devices API User Guide 27

Access Settings Configuration
Description: To set or retrieve configuration parameters for enabling basic access control on a device for users.

Actions: get, set, getdefault, setdefault

Syntax: http://<deviceIP:deviceport>/device.cgi/access-setting?action=<value>&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Access Settings Configuration Parameters

Argument Valid Values Mandatory Description

sun (0) to sat (6)

To define the active working days. This
week-day<0~6> 0 = Inactive No parameter is repeated for each day of
1 = Active the week.

work-start-hh 00-23 No Define the work start time

work-start-mm 00-59 No Define the work start time

work-end-hh 00-23 No Define the work stop time

work-end-mm 00-59 No Define the work stop time

Specifies the format in which the

format text, xml No
response is expected

Example

1. To get data for all parameters in the text format.

Sample Request
http://<deviceIP:deviceport>/device.cgi/access-setting?action=get&format=xml

Sample Response

HTTP Code: 200 OK

Content-Type: <code>
Content-Length: <type>
Body:
week-day0=1 week-day1=1 week-day2=1 week-day3=1 week-day4=1 week-day5=1 week-day6=1 work-start-hh=0
work-start-mm=0 work-end-hh=23 work-end-mm=59

28 Matrix COSEC Devices API User Guide

Alarm Configuration
Description: To set or retrieve configuration parameters for enabling/disabling alarms and related functions on a
COSEC device such as Auto Alarm Acknowledgment.

Actions: get, set, getdefault, setdefault

Syntax: http://<deviceIP:deviceport>/device.cgi/alarm?action=<value>&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Alarm Configuration Parameters

Argument Valid Values Mandatory Description

0 = Inactive
alarm No To enable/disable alarm.
1 = Active

0 = Inactive To enable or disable the feature. Not

tamper-alarm No
1 = Active applicable for ARGO FACE200T.

For ARC Controllers reader group 1.

0 = NO
tamper-readergrp1 No To specify normal state as NO/NC to
1 = NC
generate tamper alarm.

For ARC Controllers reader group 2.

0 = NO
tamper-readergrp2 No To specify normal state as NO/NC to
1 = NC
generate tamper alarm.

0 = Inactive To enable or disable the Auto Alarm

auto-alarm-ack No
1 = Active Acknowledgement feature.

Specifies the format in which the

format text, XML No
response is expected.

To enable/ disable the “User Denied

0 = Inactive
thresh-temp-exceeded No – Threshold Temperature
1 = Active
Exceeded” alarm

0 = Inactive To enable/ disable the “User Denied

mask-not-detected No
1 = Active – Face Mask Not detected” alarm

Matrix COSEC Devices API User Guide 29

Date and Time Configuration
Description: To set or retrieve date and time configurations on a COSEC device. The user can configure the date
and time to be displayed on the device, the display format, the time update mode, the NTP server settings as well
as the Daylight Savings Time (DST) settings on the selected device.

Actions: get, set, getdefault, setdefault

Syntax: http://<deviceIP:deviceport>/device.cgi/date-time?action=<value>&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Date and Time Configuration Parameters

Argument Valid Values Mandatory Description

year 2009 to 2037 No To set year value

month 01 to 12 No To set month value

date 01 to 31 No To set date

hour 00 to 23 No To set hour

minute 00 to 59 No To set minutes

second 00 to 59 No To set seconds

Defines the time format to be

displayed on the device display.

0 = 24 hours
time-format No Note: This is applicable only for the
1 = 12 hours
time shown on the device display and
not for general date-time which will
always be in 24 hours format.

0 = Auto Defines whether the update mode is

update-mode No
1 = Manual manual or through NTP Server.

Defines whether the NTP server is a

0 = Predefined
ntp-server-type No predefined server or user-defined
1 = User Defined
server address.

00-74 (Tool supported by

Windows), default: GMT
(+05:30) Chennai, Kolkata,
Mumbai, New Delhi.
time-zone No To define the universal time zone.

Refer to “Table: Universal

Time Zone Reference” on
page 111

0 = ntp1.cs.wisc.edu
ntp-server 1 = time.windows.com No To define the NTP Address.
2 = time.nist.gov

Alphanumeric, Max. 40
user-defined-ntp No To define the user-defined NTP.
characters.

0 = Disable
dst-enable No To enable/disable DST.
1 = Enable

30 Matrix COSEC Devices API User Guide

Table: Date and Time Configuration Parameters

Argument Valid Values Mandatory Description

0 = January
1 = February
2 = March
3 = April
4 = May
5 = June
fwd-month
6 = July
7 = August
8 = September
9 = October
10 = November
11 = December
No Forward clock day
0 = 1st
1 = 2nd
fwd-week 2 = 3rd
3 = 4th
4 = Last

0 = Sunday
1 = Monday
2 = Tuesday
fwd-day 3 = Wednesday
4 = Thursday
5 = Friday
6 = Saturday

00 - 23 (24 hours format

fwd-time-hh No Forward clock time instance
only)

fwd-time-mm 00 - 59

0 = January
1 = February
2 = March
3 = April
4 = May
5 = June
rev-month No
6 = July
7 = August
8 = September Reverse clock day
9 = October
10 = November
11 = December

0 = 1st
1 = 2nd
rev-week 2 = 3rd No
3 = 4th
4 = Last

Matrix COSEC Devices API User Guide 31

Table: Date and Time Configuration Parameters

Argument Valid Values Mandatory Description

0 = Sunday
1 = Monday
2 = Tuesday
rev-day 3 = Wednesday No Reverse clock day
4 = Thursday
5 = Friday
6 = Saturday

00 - 23 (24 hours format

rev-time-hh No Reverse clock time instance
only)

rev-time-mm 00 - 59

00 - 23 (24 hours format Time by which clock should be

duration-hh
only) No forwarded or reversed.
duration-mm 00 - 59

Specifies the format in which the

format text,xml No
response is expected.

When user sets the time locally it should be GMT time. And in GET command also the time value to be
returned will be GMT time irrespective of the time displaying on the device.

While configuring Daylight Saving Parameters, users are responsible to define the forward and reverse
time properly.

For IO800: Valid Parameters are: action, year, month, date, hour, minute, second, time-format, time-zone,
update-mode, ntp-server-type, ntp-server, user-defined-ntp, format.

32 Matrix COSEC Devices API User Guide

Door Features Configuration
Description: To enable, disable, define or retrieve configuration parameters related to various door features such
as auto-relock, ASC, door sense, exit switch, greeting message display, voice guidance etc.

Actions: get, set, getdefault, setdefault

Syntax: http://<deviceIP:deviceport>/device.cgi/door-feature?action=<value>&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Door Features Configuration Parameters

Argument Valid Values Mandatory Description

To allow exit when door is locked.

0 = Inactive
allow-exit-when-locked No Not applicable for ARGO
1 = Active
FACE200T.

To enable/disable the Auto-relock

0 = Inactive
auto-relock No feature. Not applicable for ARGO
1 = Active
FACE200T.

To enable/disable the Additional

0 = Inactive
asc-active No Security Code (ASC). Not
1 = Active
applicable for ARGO FACE200T.

0 = Unmute
buzzer-mute No To mute/un-mute the buzzer.
1 = Mute

To enable/disable sensing of door

0 = Inactive
door-sense-active No states. Not applicable for ARGO
1 = Active
FACE200T.

To define the normal door state as

0 = NO as normally open (NO) or normally
door-sense No
1 = NC closed (NC). Not applicable for
ARGO FACE200T.

To enable/disable supervised
0 = Unsupervised sensing of door states (four-state
supervised No
1 = Supervised monitoring of door controllers). Not
applicable for ARGO FACE200T.

To enable/disable the exit switch.

0 = Inactive
exit-switch No Not applicable for ARGO
1 = Active
FACE200T.

To enable/disable aux output. Not

0 = Inactive
aux-output-enable No applicable for ARGO FACE/
1 = Active
ARGO FACE200T.

To enable/disable aux output. Not

0 = Inactive
aux-output-enable-2 No applicable for ARGO FACE/
1 = Active
ARGO FACE200T.

To enable/disable aux output. Not

0 = Inactive
aux-output-enable-3 No applicable for ARGO FACE/
1 = Active
ARGO FACE200T.

Matrix COSEC Devices API User Guide 33

Table: Door Features Configuration Parameters

Argument Valid Values Mandatory Description

To enable/disable aux output. Not

0 = Inactive
aux-output-enable-4 No applicable for ARGO FACE/
1 = Active
ARGO FACE200T.

To enable/disable aux output. Not

0 = Inactive
aux-output-enable-5 No applicable for ARGO FACE/
1 = Active
ARGO FACE200T.

To enable/disable aux output. Not

0 = Inactive
aux-output-enable-6 No applicable for ARGO FACE/
1 = Active
ARGO FACE200T.

To enable/disable aux output. Not

0 = Inactive
aux-output-enable-7 No applicable for ARGO FACE/
1 = Active
ARGO FACE200T.

To enable/disable aux output. Not

0 = Inactive
aux-output-enable-8 No applicable for ARGO FACE/
1 = Active
ARGO FACE200T.

0 = Inactive To enable/disable the display

greeting-msg-enable No
1 = Active greeting message.

Alphanumeric, Max. 21
greeting-msg<1~4> No
ASCII characters

greeting-start-time-
00-23 No
hh<1~4>
To define upto 4 display greeting
greeting-start-time- messages, the start time and the
00-59 No
mm<1~4> end time for displaying each
message.
greeting-end-time-
00-23 No
hh<1~4>

greeting-end-time-
00-59 No
mm<1~4>

0 = Inactive To enable/disable Voice Guidance

voice-guidance No
1 = Active (Only for NGT doors).

Specifies the format in which the

format text,xml No
response is expected.

• When greeting messages are defined in an order then first message will always have precedence
over second and second over third and so on. Hence, if two messages defined with overlapped
timing range, the first defined message between two will have the priority.

• Third party should always take care of setting the time range for different messages.

For IO800; Valid Parameters are: action, aux-output-enable-2,3,4,5,6,7,8, format.

34 Matrix COSEC Devices API User Guide

System Timers Configuration
Description: To set or retrieve configurations for the following system timers:

Auto Alarm Acknowledgment Timer Specifies the time period in seconds after which an unacknowledged
alarm will acknowledge itself automatically.

Inter Digit Wait Timer Specifies time period in seconds between two key inputs on the
device keypad. On the expiry of this timer, the system considers the
user input to be complete and is ready for the next input.

Multi Access Wait Timer Defines the time in seconds for which the system needs to wait for
the second credential input from a user when more than one
credential is required to grant access.

Palm Enrollment Time Out Timer Defines the time period in seconds within which a palm must be
enrolled after generating the enrollment command.

Door Open Pulse Timer Defines the time in seconds required for a door to be energized for a
valid credential. If the opened door does not return to its closed state
before the expiry of this timer, the door will generate a “Door
Abnormal Alarm”.

Special Function Timer Defines the time in minutes for which the Late-IN and Early-OUT special
functions will remain active after being enabled at the door controller.

Actions: get, set, getdefault, setdefault

Syntax: http://<deviceIP:deviceport>/device.cgi/system-timer?action=<value>&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: System Timers Configuration Parameters

Argument Valid Values Mandatory Description

alarm-ack-timer 10-65535 (sec) No To define the timer for Auto Alarm

Acknowledgment.

idwt 1-99 (sec) No To define the Inter Digit Wait Timer.

multi-access-wait-timer 3-99 (sec) No To define the Multi Access Wait Timer.

palm-enroll-time-out 3-99 (sec) No To define the Palm Enrollment Time

out Timer.

pulse-time 1-65535 (sec) No To define the Door Pulse time. Not

0.1-65535.0 (sec) for applicable for ARGO FACE200T.
ARGO, VEGA, ARGO
FACE, Path V2 and ARC
DC200

sp-function-timer 1-99 (mins) No To define the Special Function Timer.

auto-relock-timer 1-65535 (sec) No To define the auto relock timer. Not

applicable for ARGO FACE200T.

format text,xml No Specifies the format in which the

response is expected.

Matrix COSEC Devices API User Guide 35

Special Function Configuration
Description: COSEC enables its users to perform certain pre-defined operations directly from the COSEC device.
These are known as special functions. An RFID card can be encoded for a special function and the card-holder can
perform this function at the device just by showing this special card.

Use this API to enable, disable, define or retrieve Special Functions configuration on a device.

Actions: get, set, getdefault, setdefault

Syntax: http://<deviceIP:deviceport>/device.cgi/special-function?action=<value>&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Special Function Configuration Parameters

Argument Valid Values Mandatory Description

Sp-fn-Index 1 = Offical Work - IN Yes The index number of a special function.

2 = Official Work - OUT
3 = Short Leave - IN Sp-fn-Index=12,18,19 and 20 is not
4 = Short Leave - OUT applicable for ARGO FACE200T.
5 = Regular - IN
6 = Regular - OUT
7 = Post Break - IN
8 = Pre Break - OUT
9 = Over Time - IN
10 = Over Time - OUT
11 = Enroll User
12 = Enroll Special Card
13 = Delete Credentials
14 = Late IN - Start
15 = Late IN - Stop
16 = Early OUT - Start
17 = Early OUT- Stop
18 = Door Lock
19 = Door Unlock
20 = Door Normal
21 = Clear Alarm
22 = Sold Out
23 = Available

enable 0 = Disable No To enable/disable special functions on

1 = Enable the device.

card1 64 Bits (20 Numeric Digits No To define the special function card 1.
approx.)

card2 64 Bits (20 Numeric Digits No To define the special function card 2.
approx.)

card3 64 Bits (20 Numeric Digits No To define the special function card 3.
approx.)

card4 64 Bits (20 Numeric Digits No To define the special function card 4.
approx.)

36 Matrix COSEC Devices API User Guide

Table: Special Function Configuration Parameters

Argument Valid Values Mandatory Description

format text, XML No Specifies the format in which the

response is expected.

Matrix COSEC Devices API User Guide 37

Internal/External Reader Configuration

Internal/External Reader Configuration is not applicable for ARGO FACE200T.

Description: To define custom card format for internal/external reader.

FC = Facility Code
O = Odd Parity
CSN = Card Serial No.
E = Even Parity

Actions: get, set, getdefault, setdefault

Syntax:

Internal Reader Card format:

http://<deviceIP:deviceport>/device.cgi/internal-card-format?action=<value>&<argument>=<value>….

External Reader Card format:

http://<deviceIP:deviceport>/device.cgi/external-card-format?action=<value>&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Internal/External Reader Configuration Parameters

Argument Valid Values Mandatory Description

Format-id 1- 5 No To specify which format index is to be

used

max-no-of-bits 1 - 128 bits No To specify no. of bits to be read by card

reader.

card-structure 1 - max value No To specify structure of the card format by

the selection of even parity, odd parity,
0 = Blank card serial no., facility code etc.
1 = Facility Code
2 = Odd Parity e.g. 26 bits card format
3 = Card Serial No.
4 = Even Parity 4111111113333333333333332
where,
1 = FC
3 = Card ID
4 = Even Parity
2 = Odd Parity

Blank is not a part of configuring card

structure. It is to store the default card
structure.

card-read-order 0 = Forward No To specify the order in which the card is

1 = Reverse bitwise to be read by the reader. By default, card
2 = Reverse bytewise is read in forward order.

38 Matrix COSEC Devices API User Guide

Table: Internal/External Reader Configuration Parameters

Argument Valid Values Mandatory Description

Include-facility-code 0 = Disable No To specify whether facility code is a part

1 = Enable of card ID or not. By default it is enabled.

Seq-of-operation 0,1 No To specify which seq to use

0 = Reading order then bit configuration
1 = Bit Configuration then reading order

Matrix COSEC Devices API User Guide 39

Device Display Configuration
Description: To customize the device display on COSEC PVR Doors. The COSEC PVR carries a DOT Matrix LCD
display. This API can be used to configure the various display elements at the time of accessing the device or when
the device is in the Idle mode.

Actions: get, set, getdefault, setdefault

Syntax: http://<deviceIP:deviceport>/device.cgi/device-display?action=<value>&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Device Display Settings Parameters

Argument Valid Values Mandatory Description

To give message ID.

Note: Two message IDs having same

value of user field & user-id for same
date & day will not be allowed.

message-id Numeric, 1 to 100 Yes

e.g. if some message is configured for
1st nov to 1st dec for 3 days Monday,
Tuesday, Wednesday for all users,
then another message cannot be
configured for same date range for
say, Thursday, Friday and Saturday.

0 = Idle
mode 1 = Access Allowed/ Yes To specify the display mode.
Denied

0 = Disable To enable/disable the message.

enable No
1 = Enable

This field shall be used to select

0 = All
user No whether message is to be shown to all
1 = User ID
users or random users. NA to idle.

Alphanumeric, 15 This will be used only if a random user

user-id No
characters. is selected in “user” field.

Sunday(0) to Saturday(6)
To define the active working days. This
week-day<0~6> No parameter is repeated for each day of
0 = Inactive
the week.
1 = Active

from-date-dd Date:1-31;
Month: 1-12; This field shall be used to store date
from-date-mm No
Year:2009-2037 from which this message is to be
displayed.
from-date-yyyy
Default Value: 1/1/2009

to-date-dd Date:1-31;
Month: 1-12; This field shall be used to store date
to-date-mm No
Year:2009-2037 up to which this message is to be
displayed.
to-date-yyyy
Default Value: 1/1/2009

40 Matrix COSEC Devices API User Guide

Table: Device Display Settings Parameters

Argument Valid Values Mandatory Description

Alphanumeric,
This field shall be used to store the
duration for which message is to be
duration Sec:00-59 No
displayed at the time of access
allowed/denied. NA to idle
Default Value: 3

This field shall be used to configure

the message that is to be displayed.
One for each line.
126 chars(21*6)
message0=line 2
ASCII Set:
message1=line 3
message<0~5> A-Z No
message2=line4
a-z
message3=line5
0-9
message4=line6
-_.,():@!$*+/\
message5=line7

Default value: Blank

Example

1. To set message that is to be shown in the Idle mode.

Sample Request
http://<deviceIP:deviceport>/device.cgi/device-display?action=set&mode=0&message-
id=1&enable=1&week-day6=1&from-date-dd=22&from-date-mm=7&from-date-yyyy=2014&to-date-
dd=22&to-date-mm=7&to-date-yyyy=2014&message0=Merry Christmas

Sample Response

Response-code=0

Output on Screen:

line 1 <Reserved>

line 2 M e r r y C h r i s t m a s

line 3

line 4

line 5

line 6

line 7

line 8 <Reserved>

Matrix COSEC Devices API User Guide 41

 2. To set message that is to be shown in the Idle mode.

Sample Request
http://<deviceIP:deviceport>/device.cgi/device-display?action=set&mode=0&message-
id=1&enable=1&week-day6=1&from-date-dd=22&from-date-mm=7&from-date-yyyy=2014&to-date-
dd=25&to-date-mm=7&to-date-yyyy=2014&message0=________________Merry Christmas

Sample Response

Response-code=0

Output on Screen:

line 1 <Reserved>

line 2 M e r r y

line 3

line 4

line 5

line 6

line 7

line 8 <Reserved>

3. To delete a specific message.

Sample Request
http://<deviceIP:deviceport>/device.cgi/device-display?action=setdefault&message-id=1

Sample Response

Response-code=0

The message on the message-ID =1 will be defaulted that is equivalent to delete, as message is blank by default.

4. To delete all messages.

Sample Request
http://<deviceIP:deviceport>/device.cgi/device-display?action=setdefault

Sample Response

Response-code=0

All the messages will be defaulted to blank.

42 Matrix COSEC Devices API User Guide

Device-LED & Buzzer Cadence Configuration
Description: To configure LED and Buzzer cadence for COSEC PVR Doors.

Actions: get, set, getdefault, setdefault

Syntax: http://<deviceIP:deviceport>/device.cgi/device-led-buzzer?action=<value>&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: LED & Buzzer Cadence Configuration Parameters

Argument Valid Values Mandatory Description

state 0 = Idle online Yes

1 = Idle offline
2 = Degraded mode
3 = Wait
4 = Success This specifies the state for which LED
5 = Deny and buzzer cadence is to be shown.
6 = Time out
7 = Alarm minor
8 = Alarm major
9 = Alarm crtical

led 0 = Off No This is to specify “on-off “status for

1 =On LED. By default it is set to “on”.

buzzer 0 = Disable No This is to enable or disable the door

1 = Enable buzzer. By default, it is set to “enable”.
(This is not applicable for states: idle
online, idle offline and degraded
mode, because only LED cadence is
shown for these states ) For other
states, buzzer should be active till LED
cadence is shown.

on-off Numeric. No This is to specify the on-off duration for

each state. If not configured, default
200-3000 ms (only in values should be considered for that
multiple of 200 and both state.
together should be in
summation equal to 3000 Default values for states:
ms)
Idle online - 200 ON/2200 OFF
Note: Mention the value of Idle offline - 200 ON/2200 OFF
“on-off” as “x-y” where x= Degraded - 200 ON/2200 OFF
on time in milliseconds and Wait - 200 ON/1000 OFF
y= off time in milliseconds. Success - 1200 ON/0000 OFF
Deny - 200 ON/200 OFF (3 cycles)
Time out - 200 ON/200 OFF
Alarm minor - 200 ON/1000 OFF
Alarm major - 400 ON/800 OFF
Alarm critical - ON till Reset

Matrix COSEC Devices API User Guide 43

Table: LED & Buzzer Cadence Configuration Parameters

Argument Valid Values Mandatory Description

cycles 0 - 254 No This specifies the no. of cycles for

which cadence is to be shown for each
state.’0’ indicates the infinite cycle.

Default values for states:

Success - 1
Deny - 3
Time out - 3
Others - 0

In case of online state for device, if cycle is changed from infinite to limited no. of cycle, the response will be
effective as soon as values are saved but vice-versa is not possible, if user changes the cycle from limited no. of
cycle to infinite, it will be effective only after event for the same state will be generated.

1. To show buzzer cadence only for a state.

Sample Request
http://<deviceIP:deviceport>/device.cgi/device-led-
buzzer?action=set&state=4&led=0&buzzer=1&on-off=400-400&cycles=3

Sample Response

Response-code=0

Output

The buzzer cadence will be played on the device for 400 ms on and 400 ms off for 3 cycles for wait state and Led cadence
will not be shown.

2. To show led and buzzer cadence for a state.

Sample Request
http://<deviceIP:deviceport>/device.cgi/device-led-
buzzer?action=set&state=4&led=1&buzzer=1&on-off=200-1000&cycle=0

Sample Response

Response-code=0

Output

The Led and buzzer cadence will be played on the device for 200 ms on and 1000 ms off for infinite cycle till user allowed
state.

44 Matrix COSEC Devices API User Guide

Multi-Language Support
Description: To enable/disable multiple language support for custom message display on supported COSEC
devices (Door V3, NGT Controller. PVR Door, Vega Controller).

Languages supported are: English, Spanish, Albanian, Thai, Vietnamese

Actions: get, set, getdefault, setdefault

Syntax: http://<deviceIP:deviceport>/device.cgi/multi-language?action=<value>&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Multi-Language Support Parameters

Argument Valid Values Mandatory Description

0 - Inactive To enable/disable multi-language

multi-language-support No
1 - Active support.

multi-language-input- 0 - Inactive To enable the multi-language for data

No
data 1 - Active input

Matrix COSEC Devices API User Guide 45

To Download/Upload Multi-Language File
Description: To download/upload multi-language file for custom message display on supported COSEC devices
for which muti-language support has been enabled.

File uploaded can be in XLS or CSV format only.

Actions: get, set, getdefault

Syntax: http://<deviceIP:deviceport>/device.cgi/multi-language-file?action=<value>&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Download/Upload Multi-Language File - Parameters

Argument Valid Values Mandatory Description

action get Yes To download the multi-language file.

To download the sample multi-

action getdefault Yes
language file.

action set Yes To upload a custom message file.

Example

1. To download file.

Sample Request

http://<deviceIP:deviceport>/device.cgi/multi-language-file?action=get

Sample Response
Body:
Response-Code=0

Custom Message File

The method used in this case should be POST method as it consists of raw/hex data in the data portion of
the request and the response.

2. To get sample file.

Sample Request

http://<deviceIP:deviceport>/device.cgi/multi-language-file?action=getdefault

Sample Response
Body:
Response-Code=0

Custom Message File

46 Matrix COSEC Devices API User Guide

 3. To upload a file.

Sample Request

http://<deviceIP:deviceport>/device.cgi/multi-language-file?action=set

Sample Response
Body: Response-Code=0

Matrix COSEC Devices API User Guide 47

To Select the Mode of Wiegand Interface

Wiegand Interface Mode is not applicable for ARGO FACE200T.

Description: To set the Wiegand interface mode for supported COSEC doors (PVR Door, PATH Controller) for
reader input or output to third party panel.

Actions: get, set, getdefault, setdefault

Syntax: http://<deviceIP:deviceport>/device.cgi/wiegand-interface?action=<value>&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Wiegand Interface Mode Parameters

Argument Valid Values Mandatory Description

This specifies whether Wiegand

interface is configured as a reader
0 = Reader Input
enable No input or as an output to 3rd party
1 = Output to 3rd party panel
panel. By default, it is in reader input
mode.

This specifies whether the door should

wait for response from the 3rd party
0 = Inactive
enable-signal-wait No panel before unlocking the door after
1 = Active
user verification. By default it is
disabled.

This specifies the time duration for

signal-wait-timer 0 - 255 sec No which the door should wait for the 3rd
party panel signal

0 = 26 Bit
This specifies the format in which the
output-format 1 = Actual No
output is to be sent to 3rd party panel.
2 = 37 Bit

0 = MSB Bit
send-from No Send MSB or LSB first
1 = LSB Bit

48 Matrix COSEC Devices API User Guide

Temperature Logging Configuration
Description: To set the temperature parameters like temperature unit, temperature sensors, threshold temperature
value etc in devices.

Actions: get, set, getdefault, setdefault

Syntax: http://<deviceIP:deviceport>/device.cgi/temp-log?<argument>=<value>[&<argument>=<value>….]

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Temperature Logging Configuration Parameters

Argument Valid Values Mandatory Description

To enable or disable Temperature

0= Inactive
enable No Logging feature. By default it is
1= Active
disabled

To set the temperature unit in which

0= Fahrenheit the user temperature will be
temp-unit No
1=Celsius measured. By default it is
Fahrenheit

0=AST
1= Web-based To allow user to select the thermal
sensor-type 2=Reserved No sensor type. By default it is
3=FEVOBOT FEVOBOT.

To allow user to select the interface.

0= RS-232 HTTP/S is applicable only when
sensor type is Web-Based. By
1=USB
interface No default it is “USB”. For non USB
2=HTTP/S
devices default value is “RS – 232”.
For sensor type FEVOBOT only
USB is applicable.

0=Soft To allow user to switch the

restriction 1=Hard No restriction between Soft and Hard.
By default it is Soft

0=Disable To give provision of bypass if sensor

bypass 1=Enable No is disconnected. By default it is
disable

To allow user to enter the Threshold

97.0 – 110.0 °F
thresh-temp No temperature value. By default it is
36.0 – 43.0 °C
99.5°F or 37.5°C

To calibrate the temperature with

calibration-para -5.0 to 5.0 No increment of 1. By default it is 0. Not
applicable for FEVOBOT

To set the emissivity parameter for

emissivity 0.95-0.98 No AST sensor. Default is 0.95. Not
Applicable for FEVOBOT

Specifies the format in which the

format text, XML No
response is expected

Matrix COSEC Devices API User Guide 49

 • temp-unit and thresh-temp are interrelated fields.
For setdefault/getdefault: temp-unit is Fahrenheit so the thresh-temp will be 99.5.

For set:
If both the fields are passed and the thresh-temp value is not as per temp-unit then API will fail.

If temp-unit is only passed then if the temp-thresh value in device is not according to temp-unit
passed then temp-thresh value will get defaulted as per temp-unit.

If thresh-temp is only passed, temp-unit value already set in device will be checked and if mismatch
is found then API will fail.

• Sensor-type and interface are interrelated fields:

For setdefault/getdefault: sensor-type is 0 and the interface is 1 for devices that support USB and
the interface is 0 for devices that don’t support USB.

• For set:
If both the fields are passed and sensor-type is web-based then the interface value should be
HTTP/S. If any other interface value is sent then API will fail.

If both the fields are passed and sensor-type is FEVOBOT then the interface value will be USB. If
any other interface value is sent then API will fail

If both the fields are passed and sensor-type is not web-based then the interface value should not
be HTTP/S. If HTTP/S interface value is sent then API will fail.

For devices which don’t support USB if interface value is passed as USB, the API will fail
If only sensor-type is passed then the interface value will be checked.

• Sensor-type is passed as Web-based and interface value is not HTTP/S in device then the interface
value will be set as HTTP/S.

• If sensor-type is passed as AST and interface value is HTTP/S in device then the interface value will
be set as USB if device supports USB else it will be set as RS-232.

• If sensor-type is passed as FEVOBOT and interface value is other than USB in device then the
interface value will be set as USB.

• If only interface is passed, then sensor-type value will be checked.

• Interface is passed as HTTP/Sand sensor-type value in device is not Web-based then API will fail.

• Interface is passed as USB and device doesn’t support USB then API will fail.

• Interface is passed as USB and sensor-type is Web-based in device then API will fail.

• Interface is passed as RS-232 and sensor-type is Web-Based in device then API will fail.

• Interface is passed as RS-232 and sensor-type is Web-Based/FEVOBOT in device then API will fail

50 Matrix COSEC Devices API User Guide

Face Mask Compulsion
Description: Face Mask Compulsion feature is used to enforce users to wear masks while they are within the
premises

Actions: get, set, getdefault, setdefault

Syntax: http://<deviceIP:deviceport>/device.cgi/face-mask?<argument>=<value>[&<argument>=<value>….]

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Smart Card Format Parameters

Argument Valid Values Mandatory Description

To enable or disable Face Mask

0= Inactive
enable No Compulsion Feature. By default it is
1= Active
disabled

To set the approach to camera wait-

approach-cam-timer 0.0 to 15.0s No
timer. By default it is 3.0s

1 to 99 s To set time-out for face mask

detection-timeout No
detection. By default it is 4s

0=Soft To allow user to switch the

restriction 1=Hard No restriction between Soft and Hard.
By default it is Soft

To specify the threshold value below

which the mask status will be
detection-threshold-
1.00 to 99.99 No returned as 0 ie. Not detected for
identification
identification. By default the value is
set as 98.00

To specify the threshold value below

which the mask status will be
detection-threshold-
1.00 to 99.00 No returned as 0 ie. Not detected for
enrollment
enrollment. By default the value is
set as 10.00

Specifies the format in which the

format text, XML No
response is expected

Matrix COSEC Devices API User Guide 51

Smart Card Format

Smart Card Format is not applicable for ARGO FACE200T.

Description: To personalize the smart card format by configuring user-defined fields and defining their location on
the available card memory as per card type selected. This API will not be applicable for Path Controllers and Arc
Controllers due to memory constraints.

Actions: get, set, setdefault

Syntax: http://<deviceIP:deviceport>/device.cgi/smart-card-format?action=<value>&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Smart Card Format Parameters

Argument Valid Values Mandatory Description

Indexed.

1 = iClass 2K2
card-type 2 = iClass 16K2 Yes To specify the card type.
3 = iClass 16K16
4 = Mifare 1K
5 =Mifare 4K

Boolean.
To specify the mode of reading/writing
mode No
0 = Default a card.
1 = Custom

Numeric

card-no 0 = CSN
1 = UID
2 = Custom

Boolean. To decide whether to read CSN

when card id gets failed to read.
read-csn No
0 = Inactive Only applicable when card id is
1 = Active custom.

52 Matrix COSEC Devices API User Guide

Table: Smart Card Format Parameters

Argument Valid Values Mandatory Description

To specify the index number of the

field to be configured. This field is not
index Yes
mandatory if we want to just change
the mode of a particular card type.

To specify the field type of the field to

field-type No
be configured.

date-format No To specify the date format.

separator No To specify the separator

To specify the date field format i.e.

date-field-type No
BCD/ASCII/Hex

Refer the respective card To specify the start sector for mifare
start-sector No
type tables for values as 1K and 4K.
provided below. To specify the start block in iclass
start-block No
2K2, 16K2, 16K16 and mifare 1K , 4K

To specify the start page for iclass

start-page No
16K16.

To specify the start byte for iclass 2K2,

start-byte No
16K2, 16K16 and mifare 1K , 4K

To specify the start bit for iclass 2K2,

start-bit No
16K2, 16K16 and mifare 1K , 4K

To specify the order in which the field

read-from No
has to be read

length No To specify the Length of the field.

Specifies the format in which the

format Text, XML No
response is expected

Table: Smart Card Configuration Parameters - iClass 2K2

Argument Valid Values Mandatory Description

card-type 1 = iClass 2K2 Yes To specify the card type.

To specify the index number of the

Numeric.
field to be configured. This field is not
index Yes
mandatory if just the mode of a
1-99
particular card type is to be changed.

0 = Text
1 = Numeric To specify the field type of the field to
field-type No
2 = Date be configured.
3 = Raw

Matrix COSEC Devices API User Guide 53

Table: Smart Card Configuration Parameters - iClass 2K2

Argument Valid Values Mandatory Description

0 = ddmmyy
1 = ddmmyyyy
2 = ddmmmyy
3 = ddmmmyyyy
date-format No To specify the date format.
4 = mmddyy
5 = mmddyyyy
6 = yymmdd
7 = yyyymmdd

0 = none
separator 1=- No To specify the separator
2=/

0 = Hex
To specify the date field format i.e.
date-field-type 1 = BCD No
BCD/ASCII/Hex
2 = ASCII

start-sector 0 No -

To specify the start block in iClass

start-block 19 - 31 No
2K2.

start-page 0 No -

start-byte 0-7 No To specify the start byte for iclass 2K2.

start-bit 0-7 No -

length 0 - 104 No To specify the Length of the field.

Table: Smart Card Configuration Parameters - iClass 16K2

Argument Valid Values Mandatory Description

card-type 2 = iClass 16K2 Yes To specify the card type.

To specify the index number of the

Numeric.
field to be configured. This field is not
index Yes
mandatory if just the mode of a
1-99
particular card type is to be changed.

0 = Text
1 = Numeric To specify the field type of the field to
field-type No
2 = Date be configured.
3 = Raw

0 = ddmmyy
1 = ddmmyyyy
2 = ddmmmyy
3 = ddmmmyyyy
date-format No To specify the date format.
4 = mmddyy
5 = mmddyyyy
6 = yymmdd
7 = yyyymmdd

0 = none
separator 1=- No To specify the separator
2=/

54 Matrix COSEC Devices API User Guide

Table: Smart Card Configuration Parameters - iClass 16K2

Argument Valid Values Mandatory Description

0 = Hex
To specify the date field format i.e.
date-field-type 1 = BCD No
BCD/ASCII/Hex
2 = ASCII

start-sector 0 No -

To specify the start block in iClass

start-block 19 - 255 No
16K2.

start-page 0 No -

To specify the start byte for iClass

start-byte 0-7 No
16K2.

start-bit 0-7 No -

length 0 - 1896 No To specify the Length of the field.

Table: Smart Card Configuration Parameters - iClass 16K16

Argument Valid Values Mandatory Description

card-type 3 = iClass 16K16 Yes To specify the card type.

To specify the index number of the

Numeric.
field to be configured. This field is not
index Yes
mandatory if just the mode of a
1-99
particular card type is to be changed.

0 = Text
1 = Numeric To specify the field type of the field to
field-type No
2 = Date be configured.
3 = Raw

0 = ddmmyy
1 = ddmmyyyy
2 = ddmmmyy
3 = ddmmmyyyy
date-format No To specify the date format.
4 = mmddyy
5 = mmddyyyy
6 = yymmdd
7 = yyyymmdd

0 = none
separator 1=- No To specify the separator
2=/

0 = Hex
To specify the date field format i.e.
date-field-type 1 = BCD No
BCD/ASCII/Hex
2 = ASCII

start-sector 0 No -

For Page 0,
applicable blocks = 19-31
To specify the start block in iclass
start-block No
16K16.
For Pages 1-6,
applicable blocks = 6-31

Matrix COSEC Devices API User Guide 55

Table: Smart Card Configuration Parameters - iClass 16K16

Argument Valid Values Mandatory Description

To specify the start page for iClass

start-page 0-6 No
16K16.

To specify the start byte for iClass

start-byte 0-7 No
16K16.

start-bit 0-7 No -

length 0 - 1352 (bytes) No To specify the Length of the field.

Table: Smart Card Configuration Parameters - Mifare 4K

Argument Valid Values Mandatory Description

card-type 5 = Mifare 4K Yes To specify the card type.

To specify the index number of the

Numeric.
field to be configured. This field is not
index Yes
mandatory if we want to just change
1-99
the mode of a particular card type.

0 = Text
1 = Numeric To specify the field type of the field to
field-type No
2 = Date be configured.
3 = Raw

0 = ddmmyy
1 = ddmmyyyy
2 = ddmmmyy
3 = ddmmmyyyy
date-format No To specify the date format.
4 = mmddyy
5 = mmddyyyy
6 = yymmdd
7 = yyyymmdd

0 = none
separator 1=- No To specify the separator
2=/

0 = Hex
To specify the date field format i.e.
date-field-type 1 = BCD No
BCD/ASCII/Hex
2 = ASCII

To specify the start sector for Mifare

start-sector 0-39 No
4K.

For sector 0,
applicable blocks = 1,2

For sector 1-31,

start-block No To specify the start block in Mifare 4K.
applicable blocks = 0-2

For sector 32-39,

applicable blocks = 0-14

start-page 0 No -

start-byte 0 - 15 No To specify the start byte for Mifare 4K.

56 Matrix COSEC Devices API User Guide

Table: Smart Card Configuration Parameters - Mifare 4K

Argument Valid Values Mandatory Description

start-bit 0-7 No -

length 0 - 3440 No To specify the Length of the field.

Table: Smart Card Configuration Parameters - Mifare 1K

Argument Valid Values Mandatory Description

card-type 4 = Mifare 4K Yes To specify the card type.

To specify the index number of the

Numeric.
field to be configured. This field is not
index Yes
mandatory if just mode of a particular
1-99
card type is to be changed.

0 = Text
1 = Numeric To specify the field type of the field to
field-type No
2 = Date be configured.
3 = Raw

0 = ddmmyy
1 = ddmmyyyy
2 = ddmmmyy
3 = ddmmmyyyy
date-format No To specify the date format.
4 = mmddyy
5 = mmddyyyy
6 = yymmdd
7 = yyyymmdd

0 = none
separator 1=- No To specify the separator
2=/

0 = Hex
To specify the date field format i.e.
date-field-type 1 = BCD No
BCD/ASCII/Hex
2 = ASCII

To specify the start sector for Mifare

start-sector 0-15 No
1K.

For sector 0,
applicable blocks = 1,2
To specify the start block in iclass
start-block No
2K2, 16K2, 16K16 and mifare 1K , 4K
For sector 1-15,
applicable blocks = 0-2

start-page 0 No -

start-byte 0 - 15 No To specify the start byte for Mifare 1K.

start-bit 0-7 No -

length 0 - 752 bytes No To specify the Length of the field.

Matrix COSEC Devices API User Guide 57

 • For mode set as “default”, no other parameters are not be configured other than “card-type”.

• For action= setdefault, card-type & index are only the required parameters. If “card-type” parameter
is given in setdefault API then all the parameters of a particular card-type will be defaulted. If “index”
is also provided with “card-type” as parameter, then all the properties of that specific index field will
be set to default.

• For action=get, if the mode of the device is default mode, then the parameters shown in the
response will contain parameters applicable according to the default mode. i.e. all the Matrix
predefined fields and their corresponding parameters.

• For action = set, all the parameters will be configurable.

Example

1. To set the fields for Mifare 1K in custom mode.

Sample Request
http://<deviceIP:deviceport>/device.cgi/smart-card-formatl?action=set&card-
type=3&mode=1&index=22&field-type=1&start-sector=8&start-block=1&start-byte=1&length=4

Sample Response
HTTP Code: 200 OK
Content-Type: <type>
Content-Length: <length>
Body: <response code>

2. To set the mode for Mifare 1K.

Sample Request
http://<deviceIP:deviceport>/device.cgi/smart-card-formatl?action=set&card-type=3&mode=1

Sample Response
HTTP Code: 200 OK
Content-Type: <type>
Content-Length: <length>
Body: <response code>

In the above example, this API will set the mode of the Mifare 1K card type as custom globally, irrespective of the
field type. Setting the mode of a card is only dependent upon the card type and not the index.

3. To default Mifare 1K.

Sample Request
http://<deviceIP:deviceport>/device.cgi/smart-card-formatl?action=setdefault&card-type=3

58 Matrix COSEC Devices API User Guide

 Sample Response
HTTP Code: 200 OK
Content-Type: <type>
Content-Length: <length>
Body: <response code>

Matrix COSEC Devices API User Guide 59

Smart Card Key Change

Smart Card Key Change is not applicable for ARGO FACE200T.

Description: This API will enable to change the key of the Smart card. The key-type parameter will decide which
key i.e. matrix predefined key or the custom key is to be written on the shown smart card.

Actions: set

Syntax: http://<deviceIP:deviceport>/device-cgi/key-change?action=set[&<argument>=<value>….]

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Smart Card Key Change Parameters

Argument Valid Values Mandatory Description

0 = matrix key
To specify the type of key to be written
new-key-type 1 = custom key stored in the Yes
on the card shown.
device

0 = matrix key
To specify the type of key currently
old-key-type 1 = custom key stored in the Yes
written on the card shown.
device

This key will be verified with the old

old-key 8 Bytes (16 Hex digits) Yes
key written in the card.

Specifies the format in which the

format Text, XML No
response is expected

•This API will only change the key for a single card shown.
•Using this API only key can be changed. Key verification is not supported by this API.
•Server shall send the old key type written in the card along with key value. The old key value should be
sent as blank if the old key type is matrix key.

Table: Smart Card Key Change Response

Field Valid Values Response

0 = success
16 = Device Busy
24 = Feature not configured
Response-code -
28 = Read/Write Failed
29 = Wrong Card Type
30 = Key mismatch

60 Matrix COSEC Devices API User Guide

Table: Smart Card Key Change Response

Field Valid Values Response

1.In CP if card no= CSN; device will

read the csn of the card and send the
same as response in this parameter.
2.In cp if card no= custom;
device will write the value received in
the card-no parameter in the field22 and
card-no 0-18446744073709551615; 8 bytes send the same as response in this
parameter
3.This value will be sent has zero if card
no is failed to be read.
*Note: card no will represent CSN /
field22 as per card no parameter
defined in CP

1 = iclass2K2
2 = iclass16K2
3 = iclass16K16 Read only card will be send if the read
Card-type
4 = Mifare 1K card is a HID prox card or EM prox card
5 = Mifare 4K
6 = Read Only Card

Matrix COSEC Devices API User Guide 61

FR Settings
Actions: set, get, setdefault, getdefault

Syntax: http://<deviceIP:deviceport>/device.cgi/fr-settings?<argument>=<value>[&<argument>=<value>….]

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: FR Settings

Argument Valid Values Mandatory Description

0 = Disable
1 = Enable To enable or disable Face
enable No
Recognition.
Default = 0

Only Local mode is applicable for FR

Settings.
mode 0 = Local No
For Server Assisted Mode, the API will
be handled by the Server.

0 = Tap & Go
1 = Free Scan To allow user to switch the mode
capturing-mode No
between tap & go and free scan mode.
Default = 0

0 = Disable
enable-freescan- 1 = Enable This will allow user can set the free
No
timeout scan timeout
Default = 0

5 to 999 seconds
If free scan timeout is enabled, this will
freescan-timeout No
set the timer value.
Default: 30 seconds

1-99 s
This is the timeout value for tap and go
identification-timeout No
mode.
Default: 4seconds

0 = Disable
1 = Enable To enable or disable Group Face
group-fr No
Recognition.
Default = 0

0 = Disable
1 = Enable To enable or disable Capture Face of
unidentified-face No
Unidentified User.
Default = 0

Specifies the format in which the

format Text,xml No
response is expected

0 = Disable
To enable or disable Conflict Checking
1 = Enable
conflict-check No with other users during Face
Enrollment
Default = 1

62 Matrix COSEC Devices API User Guide

Table: FR Settings

Argument Valid Values Mandatory Description

This is the Matching Threshold used to

conflict-matching-
1.0 - 99.99 No check conflict with other users during
threshold
Face Enrollment.

0 = Disable
1 = Enable This flag defines whether Face Anti-
face-anti-spoofing No
Spoofing feature is enabled or not.
Default = 0

This parameter defines the minimum

1.00 - 99.99
face-anti-spoofing- required value of identified user's face
No
threshold liveness for considering him/her as
Default: 58.50
real person

0 = Disable
adaptive-face- 1 = Enable To enable or disable Adaptive Face
No
enrollment Enrollment
Default = 0

0.0 - 10.0 This parameter defines the threshold

threshold-deviation No value from which the value can be
Default: 2.0 deviated.

0.0 - 10.0 This parameter defines the deviation

multi-user-matching-
No expected in Matching Score from Multi
score-deviation
Default: 2.0 - User.

0 = Disable
confirm-before- To enable or disable Asking for user
1 = Enable
adaptive-face- No confirmation before Adaptive Face
enrollment Enrollment.
Default = 0

0.0 - 100.0
This parameter defines the Matching
face-matching-score No
of Face.
Default = 94.0

0 - 100 This parameter defines the threshold

threshold-face-
No that should be maintained for face
detection
Default = 60 detection.

1-10 This parameters defines the number of

adaptive-face-
No adaptive face templates that can be
templates-per-user
Default = 60 stored against a user.

0 = Disable
Unidentified-face- 1 = Enable To enable or disable Show Feedback
No
feedback for Unidentified Face.
Default = 0

0 = Disable
Unidentified-face- 1 = Enable To enable or disable Generate
No
event Unidentified Face Event.
Default = 0

Matrix COSEC Devices API User Guide 63

Table: FR Settings

Argument Valid Values Mandatory Description

0 = Disable
1 = Enable To enable or disable Allow Access via
Access-via-qr No
QR.
Default = 0

64 Matrix COSEC Devices API User Guide

User Configuration

The various COSEC devices have capacity to support the following number of users

No. of Users
S. No. COSEC Device
Supported

1 Direct Door V1 500

2 Direct Door V2 2000

3 Direct Door V3 50,000

4 Direct Door V4 50,000

5 NGT Direct Door 10,000

6 Wireless Door 50,000

7 PVR Door 10,000

8 PATH Door 10,000

9 ARC Door 10,000

10 ARC IO 800 NA

11 Panel 10,000

12 Panel-Lite 25,000

13 Panel200 25,000

14 Vega Controller 50,000

15 Door FMX 50,000

16 MODE Device 50,000

17 ARGO 50,000

18 ARGO FACE 50,000

This group of APIs enables users to add or delete users, set user photographs, add or fetch various configurations
related to users on or from a device as well as synchronize credentials with device. The following functions can be
called:

• Setting/Retrieving User Configuration

• Setting a User Photo
• Deleting a User
• Setting User Credentials
• Retrieving User Credentials
• Deleting User Credentials

Matrix COSEC Devices API User Guide 65

Setting/Retrieving User Configuration
Description: To set basic user configuration parameters on a device using the action= set parameter and retrieve
configuration details using action= get.

Actions: get, set

Syntax: http://<deviceIP:deviceport>/device.cgi/users?action=<value>&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: User Configuration Parameters

Argument Valid Values Mandatory Description

To set or retrieve the

alphanumeric user ID for the
selected user.

user-id Maximum 15 characters Yes

Note: If a set request is sent
against an existing user ID, then
configuration for this user will be
updated with the new values.

Direct Door V2= 1 - 2,000

Path Controller = 1 - 2,000
Path V2= 1 - 50,000
Wireless Door = 1 - 50,000
PVR = 1 - 10,000
NGT = 1 - 10,000
To identify the index number for
Vega Controller = 1 - 50,000
user-index No the selected user ID (only get
Door FMX = 1 - 50,000
parameter)
Panel Lite V2= 1 - 25,000
Panel/ Panel Lite= 1 - 25,000
V4 DOOR= 1 - 50,000
ARGO= 1 - 50,000
ARGO FACE= 1 - 50,000
ARC DC 200= 1 - 50,000

Yes (Not
To select the numeric user ID on
mandatory
ref-user-id Maximum 8 digits which the specified operation is
for the get
to be done.
action)

name Alphanumeric. Max. 15 characters No To define the user name

0 = Inactive
user-active No to activate or deactivate a user.
1 = Active

To define a user as VIP.

0 = Inactive
vip No Note: A VIP user is a user with
1 = Active
the special privilege to access a
particular door.

0 = Inactive To enable/disable the user

validity-enable No
1 = Active validity.

66 Matrix COSEC Devices API User Guide

Table: User Configuration Parameters

Argument Valid Values Mandatory Description

validity-date-dd 1-31 No
To define the end date for user
validity-date-mm 1-12 No
validity.
validity-date-yyyy 2000-2099 No

To set the user PIN or get the

event from user PIN.
user-pin 1 to 15 Digits No
Note: The user-pin can be set to
a blank value.

0 = Inactive To enable/disable the bypass

by-pass-finger No
1 = Active finger option.

0 = Inactive To enable/disable the bypass

by-pass-palm No
1 = Active palm option.

64 Bits (8 bytes) (max value -

card1 No
18446744073709551615) It defines the value of access
64 Bits (8 bytes) (max value - card 1 and 2.
card2 No
18446744073709551615)

0 = Enable To enable/disable the display of a

dob-enable No
1 = Disable birthday message.

dob-dd 1-31
No To set or delete the date of birth
dob-mm 1-12
for a user.
dob-yyyy 1990-2037

To set the user group number.

Note: A user can be assigned to

any user group ranging from 1 to
user-group 0-999 No 999. User group number can be
set/update via “Set” action. To
remove a user from an assigned
user group, user group should be
set to 0.

self-enrollment- 0 = Disable To enable/disable self-enrollment

No
enable 1 = Enable for user.

0 = Disable To enable/disable face

enable-fr No
1 = Enable recognition for a user.

Specifies the format in which the

format text, xml No
response is expected.

Matrix COSEC Devices API User Guide 67

 • For set requests only one user’s complete data should be sent at a time. Attempting to set data for
multiple users at a time will return an error response. For more examples of error responses, see
Error Responses.

• To create a new user on device, both user-id and ref-user-id are mandatory parameters to be
provided, and these should be unique for each user.

• If a user is already configured in the system and admin wants to update the user with new
information/data, only Alphanumeric User ID is sufficient but if the reference user ID is also
mentioned then it would be verified whether this belongs to the same user or not.

• Whenever an event is generated related to a user, the required user ID field upon calling the event
will always show user’s reference user ID. Whereas if “Get” action is sent to call user configuration
then it will show alphanumeric user ID.

Example

1. To get user data for user-id = 1

Sample Request

http://192.168.104.114:80/device.cgi/users?action=get&user-id=1

Sample Response
user-id=1 user-index=2 ref-user-id=1 name=Chirag user-active=1 vip=0 validity-enable=0 validity-date-
dd=1 validity-date-mm=1 validity-date-yyyy=2009 user-pin= card1=3280168263 card2=0 self-enrollment-
enable=0 by-pass-finger=0

68 Matrix COSEC Devices API User Guide

Setting a User Photo
Description: To set, fetch or delete a photograph against a user’s profile on the device using a third party
application.

Actions: get, set, delete

Syntax: http://<deviceIP:deviceport>/device.cgi/userphoto?action=<value>&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Setting a User Photo - Parameters

Argument Valid Values Mandatory Description

user-id Maximum 15 characters Yes To specify the alphanumeric user ID

for the user whose photo is to be set.

To get, set or delete the user photo.

This should be done in the data
user-photo N/A Yes portion of the request /
response.(applicable only for VEGA
and NGT doors)

0 = jpeg
1 = jpg Yes (only for set To define the format for the
photo-format
2 = png parameter) photograph.
3 = bmp

Specifies the format in which the

format text,xml No
response is expected.

Example
Following are some test cases for your reference:

1. To add an image file in .jpeg format for user-id 1.

Sample Request

http://<deviceIP:deviceport>/device.cgi/userphoto?action=set&user-id=1&photo-format=0
Data:
Image data

Sample Response

HTTP Code: 200 OK

Content-Type: <code>
Content-Length: <type>
Body: Response-Code=0

2. To fetch the user photo for the same user.

Sample Request

http://<deviceIP:deviceport>/device.cgi/userphoto?action=get&user-id=1

Matrix COSEC Devices API User Guide 69

Sample Response

HTTP Code: 200 OK

Content-Type: image/jpeg
Content-Length: 12345
Body:

<JPEG Image Data>

This is an example only. The actual response will vary depending on product model and configuration.

70 Matrix COSEC Devices API User Guide

Deleting a User
Description: To delete a user from a device. Deleting a user will result in deletion of the credentials of that user
along with all the other configurations set on the device.

Actions: delete

Syntax: http://<deviceIP:deviceport>/device.cgi/users?action=delete&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Delete User - Parameters

Argument Valid Values Mandatory Description

user-id Maximum 15 characters Yes To specify the alphanumeric user ID

for the user to be deleted.

format text,xml No Specifies the format in which the

response is expected.

Setting User Credentials

Description: To set a user’s biometric or card credentials on a device.

Actions: set

Syntax: http://<deviceIP:deviceport>/device.cgi/credential?action=set&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Setting User Credentials - Parameters

Argument Valid Values Mandatory Description

1 = Finger To define the user credentials

2 = Card type.
3 = Palm
type Yes
4 = Palm template with guide mode Type= 5 and 6 are applicable only
5 = Face Template for ARGO FACE.
6 = Face image

To select the user-id for which the

user-id Alphanumeric (Max 15 characters) Yes
credential is to be fetched.

64 Bits (8 bytes) (max value -

card1 No
18446744073709551615) It defines the value of access
64 Bits (8 bytes) (max value - card 1 and 2.
card2 No
18446744073709551615)

Matrix COSEC Devices API User Guide 71

Table: Setting User Credentials - Parameters

Argument Valid Values Mandatory Description

Specifies the format in which the

format text,xml No
response is expected.

This is the data of respective

credential type, which is to be
data - No
stored at given index number for
the respective user id.

Example:
The API for setting user credential on device is mentioned in URL field of 3rd party application as shown below:
http://192.168.104.114:80/device.cgi/credential?action=set&type=1&user-id=101

The User Name and Password are the device login credentials.
Click Browse button to select the credential template file say finger template which is required to set on the device.

Now click Send Request to set the finger template on device.The success response of API will be shown as below.

72 Matrix COSEC Devices API User Guide

Retrieving User Credentials
Description: To retrieve a user’s credential information from a device.

Actions: get

Syntax: http://<deviceIP:deviceport>/device.cgi/credential?action=get&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Retrieving User Credentials - Parameters

Argument Valid Values Mandatory Description

1 = Finger
To define the user credentials
2 = Card
type.
3 = Palm
type Yes
4 = Palm template with guide mode
Type= 5 and 6 are applicable only
5 = Face Template
for ARGO FACE.
6 = Face Image

To select the user-id for which the

user-id Alphanumeric (Max. 15 characters) Yes
credential is to be fetched.

64 Bits (8 bytes) (max value -

card1
18446744073709551615) It defines the value of access
64 Bits (8 bytes) (max value - card 1 and 2.
card2
18446744073709551615)

1 = 1 Finger
2 = 2 Fingers
3 = 3 Fingers
4 = 4 Fingers
5 = 5 Fingers
finger-index No
6 = 6 Fingers
7 = 7 Fingers Identifies the number of finger
8 = 8 Fingers templates/palm/ face templates/
9 = 9 Fingers face image to be set or retrieved,
10 = 10 Fingers on or from the device. The
template/image will be set and
1 = 1 Palm retrieved from the data portion of
2 = 2 Palms the request and response.
3 = 3 Palms
4 = 4 Palms Face-index is applicable for both
5 = 5 Palms type= 5 and type=6.
palm-index 6 = 6 Palms No
7 = 7 Palms
8 = 8 Palms
9 = 9 Palms
10 = 10 Palms
11 = 11 Palms

Matrix COSEC Devices API User Guide 73

Table: Retrieving User Credentials - Parameters

Argument Valid Values Mandatory Description

1 - 1 Face
2 - 2 Face
3 - 3 Face
4 - 4 Face
5 - 5 Face
6 - 6 Face
7 - 7 Face
8 - 8 Face
9 - 9 Face
10 - 10 Face
11 - 11 Face
12 - 12 Face
13 - 13 Face
14 - 14 Face
15 - 15 Face
16 - 16 Face
17 - 17 Face Identifies the number of finger
18 - 18 Face templates/palm/ face templates
19 - 19 Face to be set or retrieved, on or from
20 - 20 Face the device. The template will be
face-index No
21 - 21 Face set and retrieved from the data
22 - 22 Face portion of the request and
23 - 23 Face response.
24 - 24 Face
25 - 25 Face
26 - 26 Face
27 - 27 Face
28 - 28 Face
29 - 29 Face
30 - 30 Face
31 - 31 Face
32 - 32 Face
33 - 33 Face
34 - 34 Face
35 - 35 Face
36 - 36 Face
37 - 37 Face
38 - 38 Face
39 - 39 Face
40 - 40 Face

Specifies the format in which the

response is expected.
format text,xml No

Applicable only for type=2

This is the data of respective

credential type, which is to be
data - No
stored at given index number for
the respective user id.

74 Matrix COSEC Devices API User Guide

 • Credential parameters to be applied will depend on the credential type selected.

• At a time only finger print or palm can be get/set. Both cannot be set at the same time.

• The set command is basically similar to adding and duplication of finger template will not be verified
by the device. It is expected to be handled by the 3rd party software. See example in Setting User
Credential.

• The method used in this case should be POST method as it consists of raw/ hex data in the data
portion of the request and the response.

• Finger/palm index fields are not mentioned as mandatory fields because if user selects credential
type card then there is no need to specify the finger or palm index, similarly if credential type is
finger then palm index in not a mandatory field and vice versa.

• Compressed palm template will be given with index 11.

• If the user passes the argument: Face-index and type=5/6 in the Credentials API with action=GET,
then device should return the face template/ face image present at that specific face-index in
response.

• At a time only one face image can be obtained via action=GET and passing the face-index.

• In data field, if data of 832 bytes is received then only the data will be treated as compressed palm
template and stored.

• At a time only one face image can be set. Multiple face images cannot be set a time.

• For type=6, maximum size allowed= 200Kb and supported file format= jpg only.

Example1
1. To get finger credential of user-id = 1

Sample Request

http://192.168.104.114:80/device.cgi/credential?action=get&type=1&user-id=1&finger-index=1

Sample Response

Matrix COSEC Devices API User Guide 75

76 Matrix COSEC Devices API User Guide
Deleting User Credentials
Description: To delete selected credentials of a user from a device.

Actions: delete

Syntax: http://<deviceIP:deviceport>/device.cgi/credential?action=delete&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Deleting User Credentials - Parameters

Argument Valid Values Mandatory Description

user-id Alphanumeric (Max. 15 characters) Yes To delete the credential of a

particular user.

type 0 = All Yes Defines the credential type to be

1 = Finger deleted.
2 = Card Note: For the selected type, all
3 = Palm credentials will be deleted.
4 = Palm template with guide mode
5 = Face Template Type= 5 and 6 are applicable only
6 = Face Image for ARGO FACE.

NOTE- For delete if type is all then

all card, biometric and face
credentials should be deleted.

For type= 5/6, both face images

and face templates will be deleted.

format text,xml No Specifies the format in which the

response is expected.

Example

1. To delete finger templates of user id 1.

Sample Request

http://deviceIP:deviceport/device.cgi/credential?action=delete&user-id=1&type=1

Sample Response

HTTP Code: 200 OK

Content-Type: <type>
Content-Length: <length>
Body: Response-Code=0

Matrix COSEC Devices API User Guide 77

Enrollment

The Enrollment APIs can be used to generate an enrollment request for a device. Once the enrollment request is
successfully sent on the device, the device will initiate the enrollment process and request credentials to be
provided physically, as per the credential type and sequence specified.

Perform the enrollment function on a remote door controller using these enrollment APIs:

• Enrolling a User
• Enrolling Special Cards
• Read/Write Card
• Test Enrollment

78 Matrix COSEC Devices API User Guide

Enrolling a User
Description: To command a device to initiate enrollment for a user based on parameters specified.

Actions: enroll

Syntax: http://<deviceIP:deviceport>/device.cgi/enrolluser?action=enroll&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Enrolling User - Parameters

Argument Valid Values Mandatory Description

type 0 = Read Only Card Yes Defines the credential to be

1 = Smart Card enrolled.
2 = Biometric type=0 and 1, that is, Read Only
3 = Biometric Then Card Card and Smart Card is not
4 = Mobile Device applicable for ARGO FACE200T.
7 = Face
8 = Duress Finger

user-id Maximum 15 characters Yes Defines the alphanumeric User ID

of the user whose credential is to
be enrolled.

enroll-using 0 = Reader Group 1 No To specify on which reader the

1 = Reader Group 2 enrollment is to be done. Only
2 = Device applicable for ARC DC 100 and
ARC DC 200.

finger-count Single Template/Finger: 0-9 No To specify the number of fingers to

be enrolled.
where,
0 = 1 Finger
1 = 2 Fingers
2 = 3 Fingers
3 = 4 Fingers
4 = 5 Fingers
5 = 6 Fingers
6 = 7 Fingers
7= 8 Fingers
8 = 9 Fingers
9 = 10 Fingers

Dual Template/Finger: 0-4

where,
0 = 1 Finger
1 = 2 Fingers
2 = 3 Fingers
3 = 4 Fingers
4 = 5 Fingers

card-count 0 = 1 Card No To specify the number of cards to

1 = 2 Cards be enrolled.
2 = 3 Cards
3 = 4 Cards

Matrix COSEC Devices API User Guide 79

Table: Enrolling User - Parameters

Argument Valid Values Mandatory Description

palm-count 0 = 1 Palm No To specify the number of palms to

1 = 2 Palms be enrolled.
2 = 3 Palms
3 = 4 Palms
4 = 5 Palms
5 = 6 Palms
6 = 7 Palms
7 = 8 Palms
8 = 9 Palms
9 = 10 Palms

face-count 0 - 1 Face No To specify the number of faces to

1 - 2 Face be enrolled.
2 - 3 Face
3 - 4 Face
4 - 5 Face
5 - 6 Face
6 - 7 Face
7 - 8 Face
8 - 9 Face
9 - 10 Face
10 - 11 Face
11 - 12 Face
12 - 13 Face
13 - 14 Face
14 - 15 Face
15 - 16 Face
16 - 17 Face
17 - 18 Face
18 - 19 Face
19 - 20 Face
20 - 21 Face
21 - 22 Face
22 - 23 Face
23 - 24 Face
24 - 25 Face
25 - 26 Face
26 - 27 Face
27 - 28 Face
28 - 29 Face
29 - 30 Face

w-asc 0 = Inactive No To enable/disable the Additional

1 = Active Security Code (ASC) to be written
on the Smart Card.

w-fc 0 = Inactive No To enable/disable the Facility Code

1 = Active (FC) to be written on the Smart
Card.

w-ref-user-id 0 = Inactive No To enable/disable the User ID to be

1 = Active written on the Smart Card.

80 Matrix COSEC Devices API User Guide

Table: Enrolling User - Parameters

Argument Valid Values Mandatory Description

w-name 0 = Inactive No To enable/disable the User Name to

1 = Active be written on the Smart Card.

w-designation 0 = Inactive No To enable/disable the designation

1 = Active to be written on the Smart Card.

w-branch 0 = Inactive No To enable/disable the branch name

1 = Active to be written on the Smart Card.

w-department 0 = Inactive No To enable/disable the department

1 = Active name to be written on the Smart
Card.

w-bg 0 = Inactive No To enable/disable the blood group

1 = Active to be written on the Smart Card.

w-contact 0 = Inactive No To enable/disable Emergency

1 = Active Contact information to be written on
the Smart Card.

w-medical-history 0 = Inactive No To enable/disable the medical

1 = Active history to be written on the Smart
Card.

w-fp-template 0 = No Templates No To enable/disable the finger

1 = 1 Finger Template templates to be written on the
2 = 2 Finger Templates Smart Card.

w-palm-template 0= No No To enable/disable the finger

1=Yes templates to be written on the
Smart Card.

name Alphanumeric, 15 Chars, ASCII No Defines the values for the

Code respective fields to be written on the
designation
Smart Card.
branch

department

Matrix COSEC Devices API User Guide 81

Table: Enrolling User - Parameters

Argument Valid Values Mandatory Description

bg Maximum 4 characters. Valid No Defines the values for the

Values: respective fields to be written on the
A+ Smart Card.
A-
B+ Note: ‘bg’ stands for blood group of
B- the user.
AB+
AB-
O+
O-
A1-
A1+
A1B-
A1B+
A2-
A2+
A2B-
A2B+
B1+

contact Alphanumeric, 15 Chars, ASCII No

Code

medical-history Alphanumeric, 15 Chars, ASCII No

Code

format text, XML No Specifies the format in which the

response is expected.

• This is only to send enrollment command, if the credential is to be retrieved then it has to be
retrieved explicitly using the get and set credential command.

• By default, if count is not specified for enroll command then consider it as one and perform the
enroll operation.

• This enrollment has no links to the parameter configured on the device for “enroll through special
function”.

Example

1. To start enrollment of two fingers for user id 45.

Sample Request

http://deviceIP:deviceport/device.cgi/enrolluser?action=enroll&user-id=45&type=2&finger-count=1

Sample Response
HTTP Code: 200 OK
Content-Type: <type>
Content-Length: <length>
Body: Response-Code=0

82 Matrix COSEC Devices API User Guide

Enrolling Special Cards

Enrolling Special Cards is not applicable for ARGO FACE200T.

Description: A Special Card is an RFID card which can be encoded for a special function. This API enables the
user to perform enrollment of special cards on the selected device based on specified parameters such as special
function ID and number of cards to be enrolled as special cards.

Actions: enroll

Syntax: http://<deviceIP:deviceport>/device.cgi/enrollspcard?action=enroll&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Enroll Special Cards - Parameters

Argument Valid Values Mandatory Description

sp-fn-id All configured Special Functions Yes Defines the special function
(special function ID) identification number.

card-count 0 = 1 Card No To specify the number of cards to be

1 = 2 Cards enrolled.
2 = 3 Cards
3 = 4 Cards

format text, XML No Specifies the format in which the

response is expected.

Matrix COSEC Devices API User Guide 83

Read/Write Card

Read/Write Card is not applicable for ARGO FACE200T.

Description: This API will be used to read and write a card. The API will only read/write values from the card/on
the card. No values will be permanently stored on the device.

Actions: read, write

Syntax: http://<deviceIP:deviceport>/device.cgi/card-read-write?<argument>=<value>[&<argument>=<value>….]

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Read/Write Card Parameters

Argument Valid Values Mandatory Description

ref-user-id 0-9; 8 digits No To specify the numeric User-ID.

user-id 15 char, Alphanumeric No To specify the alpha-numeric User-ID.

name 15 char, Alphanumeric No To specify the user name.

To specify the additional security

asc 1-65535 No
code.

fc 1-65535 No To specify the facility code.

designation No To specify the designation of the user.

branch 15 char, ASCII Code No To specify the branch of the user.

department No To specify the department of the user.

0- NA
1- A+
2- A-
3- B+
4- B-
5- AB+
6- AB-
7- O+
8- O-
bg No To specify the blood-group of the user.
9- A1-
10- A1+
11- A1B-
12- A1B+
13- A2-
14- A2+
15- A2B-
16- A2B+
17- B1+

To specify the emergency contact of

contact 15 char, ASCII Code No
the user.

To specify the medical-history of the

medical-history 15 char, ASCII Code No
user.

84 Matrix COSEC Devices API User Guide

Table: Read/Write Card Parameters

Argument Valid Values Mandatory Description

pin 0-9; 6 digits No To specify the user pin.

0- Inactive
VIP No To specify the user as VIP or not.
1- Active

0=Inactive To specify the user has authority to

bypass-palm No
1= Active bypass palm verification

0- Inactive To specify the user has authority to

bypass-fp No
1- Active bypass finger print verification or not

validity-date-dd 1-31 No To specify the validity date

validity-date-mm 1-12 No To specify the validity month

validity-date-yyyy 2000-2037 No To specify the validity year

To specify the access level of user for

access-level 1-15 No
smart identification

0-18446744073709551615;
card-no No To specify CSN/Card ID of the card
8 bytes

0=not present To specify if FP template1 is to be

fp1 No
1=present written on card or not.

0=not present To specify if FP template2 is to be

fp2 No
1=present written on card or not.

0=not present To define whether the palm

palm No compressed template is to be written
on the card [field-25] or not.

To specify the format in which

format Text, XML No
response is needed

To identify whether the template

fp-index 1 or 2 Yes received is 1st template or second
template

Smart-access-route- 1-99 When Smart Access Route is enabled

No
id for SI user

Smart-access-user- 1-75 When Smart Access Route is enabled

No
level for SI user

Action= Write
• For this action device will write the values received in the API into the respective fields in the card.
• Note that all the values that are to be written in the card should be received in the API.
• Device is not expected fetch the values from the deice configuration and write them into the card.
• Card no:
If valid card no parameter is received and card no in CP configuration = default: device will ignore this
parameter, write the card and return the CSN in the card no parameter of the API response.

Matrix COSEC Devices API User Guide 85

 • Server shall send the old key type written in the card along with key value. The old key value should be
sent as blank if the old key type is matrix key.

Table: Write Card Response

Field Valid Values Response

0 = success
16 = Device Busy
26 = Parameters not applicable as per
card type defined.
Response-code -
27 = Time-Out
28 = Read/Write Failed
29 = Wrong Card Type
30 = Key mismatch

4.In CP if card no= CSN; device will

read the csn of the card and send the
same as response in this parameter.
5.In cp if card no= custom;
device will write the value received in
the card-no parameter in the field22 and
card-no 0-18446744073709551615; 8 bytes send the same as response in this
parameter
6.This value will be sent has zero if card
no is failed to be read.
*Note: card no will represent CSN /
field22 as per card no parameter
defined in CP

1 = iclass2K2
2 = iclass16K2
3 = iclass16K16 Read only card will be send if the read
Card-type
4 = Mifare 1K card is a HID prox card or EM prox card
5 = Mifare 4K
6 = Read Only Card

Action= Read
• If any parameters received in the API are not configured in the CP configuration then API will be failed with
reason 26.
• After reading the values, device will send the read values in the API response and No further action will be
taken at the device.
• Device will not store the read values in its memory.Test Enrollment

Table: Read Card Response

Field Valid Values Response

0 = success
16 = Device Busy
27 = Time-Out
Response-code -
28 = Read/Write Failed
29 = Wrong Card Type
30 = Key mismatch

86 Matrix COSEC Devices API User Guide

Table: Read Card Response

Field Valid Values Response

1.In CP if card no= CSN; device will

read the csn of the card and send the
same as response in this parameter.
2.In cp if card no= custom;
device will write the value received in
the card-no parameter in the field22 and
card-no 0-18446744073709551615; 8 bytes send the same as response in this
parameter
7.This value will be sent has zero if card
no is failed to be read.
*Note: card no will represent CSN /
field22 as per card no parameter
defined in CP

1 = iclass2K2
2 = iclass16K2
3 = iclass16K16 Read only card will be send if the read
Card-type
4 = Mifare 1K card is a HID prox card or EM prox card
5 = Mifare 4K
6 = Read Only Card

Matrix COSEC Devices API User Guide 87

Table: Read Card Response

Field Valid Values Response

Value read from the respective field

ref-user-id
from the card

Value read from the respective field

user-id
from the card

Value read from the respective field

name
from the card

Value read from the respective field

asc
from the card

Value read from the respective field

fc
from the card

Value read from the respective field

designation
from the card

Value read from the respective field

branch
from the card

Value read from the respective field

department
from the card

Value read from the respective field

bg If the corresponding fields are not
from the card
configured in the CP [for CP card format
Value read from the respective field = custom] or if the debug field of
contact
from the card respective field = o [for CP card format
= default] then that respective field
Value read from the respective field
medical-history should not be a part of the response.
from the card

Value read from the respective field

pin
from the card

Value read from the respective field

vip
from the card

Value read from the respective field

bypass-fp
from the card

Value read from the respective field from

bypass-palm
the card

Value read from the respective field

validity-date-dd
from the card

Value read from the respective field

validity-date-mm
from the card

Value read from the respective field

validity-date-yyyy
from the card

Value read from the respective field

access-level
from the card

88 Matrix COSEC Devices API User Guide

Table: Read Card Response

Field Valid Values Response

Value read from the respective field

card-no If the corresponding fields are not
from the card
configured in the CP [for CP card format
Value read from the respective field = custom] or if the debug field of
Smart-access-route-id
from the card respective field = o [for CP card format
= default] then that respective field
Value read from the respective field
Smart-access-user-level should not be a part of the response.
from the card

1.For card format in cp = default

Return 0 if both FP debug fields = 0
Return 1 if any FP debug field = 1
Return 2 if both FP debug field = 1
fp-count 0,1,2
2.For card format in cp = custom
Always return [device side limitation]

For card format in cp = default

Return 0 if palm debug fields = 0
Return 1 if palm debug field = 1
palm-count 0,1
For card format in cp = custom
Always return [device side
limitation]

Matrix COSEC Devices API User Guide 89

Test Enrollment
Description: This API will be used to know whether the device is applicable to be used as a enrollment device or
not. There is a requirement from the COSEC ENROLL that it should check whether the device is online or not. To
confirm the same the following API must be fired from the COSEC Enroll.

Actions: get

Syntax: http://<deviceIP:deviceport>/device.cgi /check-enrollment?<argument>=<value>[&<argument>=<value>….]

90 Matrix COSEC Devices API User Guide

Events

Any action that occurs or is performed using a live COSEC device is referred on the COSEC system as an Event. A
client application can directly request event logs to be fetched from a specific device or be fed with live events data
via the device listening port. The functions available in this API group are as follows:

• Retrieving Events
• Retrieving Events in the TCP Socket

Matrix COSEC Devices API User Guide 91

Retrieving Events
Description: To request all or specified events from a device.

Actions: getevent

Syntax: http://<deviceIP:deviceport>/device.cgi/events?action=getevent&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Retrieving Events - Parameters

Argument Valid Values Mandatory Description

roll-over-count 0 to 65535 Yes This identifies the first event that is to

be sent to the 3rd party from a set of
seq-number Yes
Refer to “Table: Value Range for events sent in this response. If the
Event Sequence Numbers” for the “no-of-events” field value is 1, then
this will be the only event sent to the
valid values on different devices.
server.

no-of-events 1 to 5 (for Direct Door V2, Path No Specifies the number of events to be
Controller, IO Controller) fetched.
1 to 100 (for all other Direct Doors)

format text, XML No Specifies the format in which the

response is expected.

Table: Value Range for Event Sequence Numbers

Door Event Sequence Number

V2 1 to 50,000

CDC 1 to 50,000

Wireless 1 to 5,00,000

NGT 1 to 1,00,000

PVR 1 to 1,00,000

Vega Controller 1 to 5,00,000

ARC Controller 1 to 1,00,000

IO Controller 1 to 1,00,000

Door FMX 1 to 5,00,000

ARGO FACE 1 to 5,00,000

ARGO 1 to 5,00,000

• For different kind of events, different fields are required, to understand the functionality of an event,
which are denoted as Detail fields.

• The Detail field in the response depends on the type of device. For further information, refer to
relevant tables in the Event Configuration Reference (Appendix).

92 Matrix COSEC Devices API User Guide

Example
1. To request specific events with roll over count = 0 and sequence number = 1. No. of events
requested is 3, for an NGT door.

Sample Request

http://deviceIP:deviceport/device.cgi/events?action=getevent&roll-over-count=0&seq-number=1&no-of-events=3

Sample Response
HTTP Code: 200 OK
Content-Type: xml
Content-Length: 12345
Body:
<COSEC_API>
<Events>
<roll-over-count>0</roll-over-count>
<seq-No>1</seq-No>
<date>16/4/2014</date>
<time>14:56:20</time>
<event-id>457</event-id>
<detail-1>0</detail-1>
<detail-2>0</detail-2>
<detail-3>6</detail-3>
<detail-4>0</detail-4>
<detail-5>0</detail-5>
</Events>
<Events>
<roll-over-count>0</roll-over-count>
<seq-No>2</seq-No>
<date>16/4/2014</date>
<time>14:56:20</time>
<event-id>453</event-id>
<detail-1>0</detail-1>
<detail-2>0</detail-2>
<detail-3>0</detail-3>
<detail-4>0</detail-4>
<detail-5>0</detail-5>
</Events>
<Events>
<roll-over-count>0</roll-over-count>
<seq-No>3</seq-No>
<date>16/4/2014</date>
<time>14:57:28</time>
<event-id>453</event-id>
<detail-1>0</detail-1>
<detail-2>0</detail-2>
<detail-3>0</detail-3>
<detail-4>0</detail-4>
<detail-5>0</detail-5>
</Events>
</COSEC_API>

For example if an enrollment event is called in which three fingers have been enrolled with the dual template per finger then the detail
fields will be as follows:
For first finger:
• Event-ID: 405 (code for enrollment event)
• Detail-1: user-id
• Detail-2: 9 (code for finger credential)
• Detail-3: 12
• Detail-4: 0
• Detail-5: 0

For second finger:

• Event-ID: 405 (code for enrollment event)
• Detail-1: user-id
• Detail-2: 9 (code for finger credential)
• Detail-3: 24
• Detail-4: 0

Matrix COSEC Devices API User Guide 93

• Detail-5: 0

For third finger:

• Event-ID: 405 (code for enrollment event)
• Detail-1: user-id
• Detail-2: 9 (code for finger credential)
• Detail-3:36
• Detail-4: 0
• Detail-5: 0

If the template per finger mode was selected as single template per finger then the respective values for detail 3 will be 11, 22 and 33,
where LSB denotes the template index.

94 Matrix COSEC Devices API User Guide

Retrieving Events in the TCP Socket
Description: To receive all or specific events through the TCP listening port of the device.

Actions: getevent

Syntax: http://<deviceIP:deviceport>/device.cgi/tcp-events?action=getevent&<argument>=<value>….

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Retrieving Events in the TCP Socket - Parameters

Argument Valid Values Mandatory Description

1: Start It is used to start and stop the

trigger No
0: Stop process

It is used to send the events

0: inactive No
keep-live-events continuously or till the maximum
1: active
limit.

ipaddress IP address and port number Defines the IP Address and the
Yes
validations are same as for network listening port on which the events
port configuration settings. are to be sent.

It is used to specify the exact

Yes
sequence number of an event stored
roll-over-count 0 to 65535 No; if keep-
at any port.
live-events=1

It is used to specify the sequence

Refer to “Table: Value Range for Yes
number of any event. The maximum
seq-number Event Sequence Numbers” for the No; if keep-
value for this can be from 1 to the
valid values on different devices. live-events=1
event log capacity of that device.

To specify the response time to wait

response-time 3 - 15 seconds No for a confirmation of established
network.

Specifies the interface.

0 = Ethernet
interface 1 = WiFi No
Note: If no interface is defined,
2 = Mobile Broadband
Ethernet will be tried by default.

Specifies the format in which the

format text, XML No
response is expected.

Due to memory constraints, this API is not supported on Direct Door V2.

Matrix COSEC Devices API User Guide 95

Example
1. To request to send the events continuously on the TCP port from event seq 1 and roll over count 0
on IP address 192.168.102.42 and tcp listening port 80.

Sample Request

http://deviceIP:deviceport/device.cgi/tcp-events?action=getevent&ipaddress=192.168.102.42&port=80&roll-over-
count=0&seq-number=1

Sample Response

HTTP Code: 200 OK

Content-Type: <type>
Content-Length: <length>
Body: Response-Code=0

• The default TCP protocol acknowledgment should be used to send the next event. If in case any
event is missed in between, then it is the responsibility of the 3rd party to re-request for that event.
This shouldn’t be done via TCP port but missed events can be re-requested through HTTP API.

• If during the event transferring if reboot occurs then the prior command (to send events) will no
longer be valid and client must re-request events. In such a case, the events which have already
been sent, will be overwritten by the same.

• The user ID against which an event is stored must be the Reference ID for a user. This being
numeric (max. 8 digits), will enable efficient utilization of storage space on devices, especially those
having high event logging capacity (up to 5,00,000 events).

96 Matrix COSEC Devices API User Guide

Sending Commands to Device

It is possible to send CGI commands to a device in order to perform certain functions.

The generic URL for these commands:

http://<deviceIP:deviceport>/device.cgi/command?action=<value>&<argument>=<value>….

Table: List of Commands to Device

S.No. Command to Device Action Description

1 Clear Alarm clearalarm To command the device to clear an alarm.

To get the count of already enrolled templates

and credentials for a user on the selected
Get Credential Count for Enrolled device.
2 getcount
Credentials
For parameters, refer Table: Get Credential
Count Command - Parameters below.

To command the device to acknowledge an

3 Acknowledge Alarm acknowledgealarm
alarm without clearing it.

To command the door to return to a locked

4 Lock Door lockdoor
state. Not applicable for ARGO FACE200T.

To command the door to return to an unlocked

5 Unlock Door unlockdoor
state. Not applicable for ARGO FACE200T.

To command the door to return to a normal

6 Normalize Door normalizedoor
state. Not applicable for ARGO FACE200T.

To open the door. The door should be opened

only for the defined pulse time. Not applicable
for ARGO FACE200T.
7 Open Door opendoor
For parameters, refer Table: Open Door
Command - Parameters below.

To obtain the total number of users added on a

8 Get User Count on Device getusercount
device.

To get the current event sequence number and

9 Get Current Event Sequence Number geteventcount
roll over count in a device.

To set all the configurations on the device to

10 Default the System Configuration systemdefault
default status.

To delete all biometric credentials of users from

device.
11 Delete Credentials for All Users deletecredential
For parameters, refer Table: Deleting
Credentials for All Users - Parameters below.

12 Activate the Aux Relay activateauxrelay To activate the Aux Relay.

13 De-activate the Aux Relay deactivateauxrelay To de-activate the Aux Relay.

To deny a user.
14 Deny User denyuser
For parameters, refer Table: Deny User
Command- Parameters below.

Matrix COSEC Devices API User Guide 97

Table: List of Commands to Device

S.No. Command to Device Action Description

To create door panic situation when some

number is entered by user from his extension.
15 Door Panic door panic
For parameters, refer Table: Door Panic
Command - Parameters below.

For action= getcount

For valid values of this action, refer to the following argument-value table.

Table: Get Credential Count Command - Parameters

Argument Valid Values Mandatory Description

user-id 1 to max. User ID in the door Yes Defines the numeric ID of the user
(2 bytes) whose data is to be fetched.

card-count 0 = 1 Card No To get the number of cards enrolled.

1 = 2 Cards
2 = 3 Cards
3 = 4 Cards

finger-count Single Template/Finger: 0-9 No To get the number of fingers

enrolled.
0 = 1 Finger
1 = 2 Fingers
2 = 3 Fingers
3 = 4 Fingers
4 = 5 Fingers
5 = 6 Fingers
6 = 7 Fingers
7 = 8 Fingers
8 = 9 Fingers
9= 10 Fingers

Dual Template/Finger: 0-4

0 = 1 Finger
1 = 2 Fingers
2 = 3 Fingers
3 = 4 Fingers
4 = 5 Fingers

palm-count 0 = 1 Palm No To get the number of palms enrolled.

1 = 2 Palms
2 = 3 Palms
3 = 4 Palms
4 = 5 Palms
5 = 6 Palms
6 = 7 Palms
7 = 8 Palms
8 = 9 Palms
9 = 10 Palms

98 Matrix COSEC Devices API User Guide

Table: Get Credential Count Command - Parameters

Argument Valid Values Mandatory Description

face-count 0 - 1 Face No To get the number of faces enrolled.

1 - 2 Face
2 - 3 Face Currently applicable for ARGO
3 - 4 Face FACE only
4 - 5 Face
5 - 6 Face
6 - 7 Face
7 - 8 Face
8 - 9 Face
9 - 10 Face
10 - 11 Face
11 - 12 Face
12 - 13 Face
13 - 14 Face
14 - 15 Face
15 - 16 Face
16 - 17 Face
17 - 18 Face
18 - 19 Face
19 - 20 Face
20 - 21 Face
21 - 22 Face
22 - 23 Face
23 - 24 Face
24 - 25 Face
25 - 26 Face
26 - 27 Face
27 - 28 Face
28 - 29 Face
29 - 30 Face

format text,xml No Specifies the format in which the

response is expected.

• If no parameter is requested then all the count values will be returned by default (of supported
credential types e.g. for PVR door, only card and palm template count will be returned).

• Palm template count and finger template counts depend on the device type i.e. Palm template
count is only applicable for PVR doors and FP template counts are applicable for other devices. The
specified credential should be applicable for the device on which the command is sent.

Example
Following are some sample cases for your reference:

1. To get the current rollover count and sequence number of events in the device.

Sample Request
http://<deviceIP:deviceport>/device.cgi/command?action=geteventcount&format=xml

Matrix COSEC Devices API User Guide 99

 Sample Response
HTTP Code: 200 OK
Content-Type: <xml>
Body:
<COSEC_API>
<Roll-over-count>1</roll-over-count>
<seq-number>1</seq-number>
</COSEC_API >

For action=opendoor

For valid values of this action, refer to the following argument-value table.

Table: Open Door Command - Parameters

Argument Valid Values Mandatory Description

This field is kept mandatory to

extra-info1 4 ASCII bytes Yes
identify the source of the command.

extra-info2 2 ASCII bytes No -

extra-info3 0 to 65535 No -

0 = Do not display audio/video

To enable/disable display of audio/
show-a/v-response (default value) No
video.

1 = Display audio/video

The valid values in the “extra-info” fields are numeric values which can be replaced for valid enumerated
codes and can be included in the event by the third party requesting the command.

For action=deletecredential

For valid values of this action, refer to the following argument-value table.

Table: Deleting Credentials for All Users - Parameters

Argument Valid Values Mandatory Description

type 0 = All Yes To specify the type of credential to

1 = Finger be deleted.
2 = Palm
3 = Face (Currently applicable for
ARGO FACE only)

For action=activateauxrelay

For valid values of this action, refer to the following argument-value table.

Table: Activate Aux Relay command - Parameters

Argument Valid Values Mandatory Description

port-no 1 to 8 No To select the Aux port. This

parameter is applicable only for IO
controller.

100 Matrix COSEC Devices API User Guide

For action=deactivateauxrelay

For valid values of this action, refer to the following argument-value table.

Table: Deactivate Aux Relay command - Parameters

Argument Valid Values Mandatory Description

port-no 1 to 8 No To select the Aux port. This

parameter is applicable only for IO
controller.

For action=denyuser

For valid values of this action, refer to the following argument-value table.

Table: Deny User Command- Parameters

Argument Valid Values Mandatory Description

extra-info1 4 ASCII bytes Yes This field is kept mandatory to

identify the source of the command.

extra-info2 2 ASCII bytes No -

extra-info3 0 to 65535 No -

show-a/v-response No
0 = Do not display audio/video
To enable/disable display of audio/
(default value)
video.

1 = Display audio/video

For action=doorpanic

For valid values of this action, refer to the following argument-value table.

Table: Door Panic Command - Parameters

Argument Valid Values Mandatory Description

extra-info1 4 ASCII bytes Yes This field is kept mandatory to

identify the source of the command.

extra-info2 2 ASCII bytes No -

extra-info3 0 to 65535 No -

Matrix COSEC Devices API User Guide 101

Cafeteria Reset and Recharge

Cafeteria Reset and Recharge is not applicable for ARGO FACE200T.

Description: This API will be used to recharge/reset the cafeteria balance on card.

Actions: read, write

Syntax: http://<deviceIP:deviceport>/device.cgi/cafeteria-reset-recharge?<argument>=<value>[&<argu-
ment>=<value>….]

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Cafeteria Reset-Recharge - Parameters

Argument Valid Values Mandatory Description

card-no1 0-18446744073709551615; 8 bytes Yes To define the CSN/Card ID of the

user.

card-no2 0-18446744073709551615; 8 bytes Yes To define the CSN/Card ID of the

user.

balance 4 bytes No To specify the available cafeteria

balance of the user.

format text,xml No Specifies the format in which the

response is expected.

Table: Smart Card Key Change Response

Field Valid Values Response

0 = success
16 = Device Busy
26 = Parameters not applicable as per
card type defined.
Response-code -
28 = Read/Write Failed
29 = Wrong Card Type
30 = Key mismatch
31 = Invalid card

1.In CP if card no= CSN; device will

read the csn of the card and send the
same as response in this parameter.
2.In cp if card no= custom;
device will write the value received in
the card-no parameter in the field22 and
card-no 0-18446744073709551615; 8 bytes send the same as response in this
parameter
3.This value will be sent has zero if card
no is failed to be read.
*Note: card no will represent CSN /
field22 as per card no parameter
defined in CP

102 Matrix COSEC Devices API User Guide

Table: Smart Card Key Change Response

Field Valid Values Response

1 = iclass2K2
2 = iclass16K2
3 = iclass16K16 Read only card will be send if the read
Card-type
4 = Mifare 1K card is a HID prox card or EM prox card
5 = Mifare 4K
6 = Read Only Card

Matrix COSEC Devices API User Guide 103

Verify Biometric and Open Door

Description: When this API is fired; device will prompt for User finger and it will be compared with the finger
templates received from APIs.

Actions: set

Syntax: http://<deviceIP:deviceport>/device.cgi/verify-open-door?<argument>=<value>[&<argument>=<value>….]

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Verify biometric and Open door- Parameters

Argument Valid Values Mandatory Description

user-id 15 Alphanumeric characters Yes The user ID on which the specified

operation is to be done.

name 15 Alphanumeric characters with Yes The name of the user

space

operation 0-2 Yes 0-Verify and open

1-Only Verify
2-Only open

Format Text, XML No Specifies the format in which the

response is expected.

Finger data must be sent in JSON format only.

JSON object names must be fp1, fp2,…, fp10 only.

If operation = 0; device will verify scanned finger with received fingers in the API and if verified then device will open the
door.

If operation =1 then device will verify the scanned finger with received fingers in the API and if verified device will send
success response but door will not be opened.

If operation = 2 then device will directly open the door.

104 Matrix COSEC Devices API User Guide

Temperature Reading

Description: This API will be used by 3rd Party Thermal Sensors to send temperature readings to the device.

Actions: set

Syntax: http://<deviceIP:deviceport>/device.cgi/temp-reading?<argument>=<value>[&<argument>=<value>….]

Parameters: All arguments for this query and their corresponding valid values are listed below:

Table: Arguments and Valid Values

Argument Valid Values Mandatory Description

temp-value 6 characters (0-9 and dot (.) only) Yes The temperature value recorded
by sensor

temp-unit 0=Fahrenheit Yes The unit in which the temperature

1= Celsius value is recorded by sensor
2=Kelvin

Format Text, XML No Specifies the format in which the

response is expected.

Matrix COSEC Devices API User Guide 105

Error Responses

These are some possible error response types obtained from incorrect API requests.

• Argument is mentioned in request but valid value is not assigned.

Sample Response

HTTP code: <code>

Content-type: <type>
Body:
Request failed: Incomplete command “<argument>=”

• Invalid value is assigned to argument in request.

Sample Response

HTTP code: <code>

Content-type: <type>
Body:
Request failed: Invalid command “<argument>=<invalid value>”

• Syntax of request is incorrect or any unexpected arguments are received.

Sample Response

HTTP code: <code>

Content-type: <type>
Body:
Request failed: Invalid syntax “<entire request>”

• Mandatory fields are not mentioned in request.

Sample Response

HTTP code: <code>

Content-type: <type>
Body:
Request failed: Incomplete command “<entire request>”

106 Matrix COSEC Devices API User Guide

 • Syntax of request is valid but no data found.

Sample Response

HTTP code: <code>

Content-type: <type>
Body:
Request failed: No record found “<argument>=<value>”

Matrix COSEC Devices API User Guide 107

API Response Codes

These numerical codes will be returned with an API response. These response codes shall indicate the result of a
particular request made by the client. For e.g. the response code ‘0’ will indicate that the requested action was
performed successfully. Refer to the given table for a list of response codes and their meanings.

Table: API Response Codes

Response Code Description Test Condition

0 Successful -

Failed - Invalid Login

1 On every Authentication/Verification while logging In
Credentials

Date and time – manual set

2 If unable to set the RTC for date and time API
failed

In User API, if validity-date or date of birth is set wrong.

3 Invalid Date/Time
If the starting time and end time of a shift is configured as same.

Maximum users are already

4 On every set command for user API
configured.

5 Image – size is too big On every set command for user API

Image – format not

6 On every set command for user API
supported

Card 1 and card 2 are

7 On every set command for user API and set credential API
identical

On every set command for user API and set credential API, Set
8 Card ID exists
Special Function API

Finger print template/ Palm

template/ Face template
9 Set credential API
already exists/ Face Image
already exists

Event sequence number and roll over count not found, user id not
10 No Record Found
found in Set User API

Template size/ format If the expected template size is not as per the required size, format or
11
mismatch any checksum error etc. in Set credential API

12 FP Memory full In Set credential API, if the max FP template is set in the module.

In enroll user command if user id is not available in the device and in

13 User id not found User Configuration API, to update a user if provided reference user ID
doesn’t belong to that user verified with alphanumeric user ID.

14 Credential limit reached In enroll user command, if max no. of credentials is already enrolled.

The enroll request is for smart card and the device has proximity
Reader mismatch/ Reader
15 reader or if enroll request has palm template but door has finger reader
not configured
and similar cases.

All cases of enrollment when the device is unable to process a request

16 Device Busy
as it is in a different menu state

Internal error like configuration, firmware or event or calibration failure

17 Internal process error
occur

18 PIN already exists Set User API: PIN is already assigned to another user

Get FP/Palm/ Face template or Face Image command is sent but

19 Credential not found
template/ image is not present.

108 Matrix COSEC Devices API User Guide

Table: API Response Codes

Response Code Description Test Condition

In case memory card is not connected, and a command related to

20 Memory Card Not Found
getting an image (user photo) is sent.

When an already existing User ID is entered against a user having

21 Reference User ID exists
unique User ID.

For enrolling user, if writing FP template on smart card is enabled, but

no fingerprint is enrolled.
22 Wrong Selection
When palm/finger/card count exceeds the maximum number of
available places.

Palm template mode In Set Credentials API, when palm template with particular mode does
23
mismatch not match with the selected mode.

In configuration, if a particular parameter is not enabled and is required

for the process.
Feature not enabled in the
24
configuration On Set Credential API- for Face Image, if the device's FR is disabled
Or On Set Credential API- for Face Image/ Face Template, if the
device's FR Mode is server-assisted.

Message already exists for In Device Display API, if message is configured for same date and
25
same user for same date same user that is already configured.

Invalid smart card format/ If any of the entered values are incorrect as per specified range./ If any
26 Parameters not applicable parameter received in the API is configured in the CP configuration of
as per card type defined. the device.

27 Time Out If the card is not shown on the device.

If the card has been failed to read/write due to any reason like: key
28 Read/Write failed
mismatch, wrongly placed card etc

If the card shown on the device is not as per the reader set on the
device for example, if write operation is to be done & read only card is
29 Wrong Card Type
shown or reader is set as HID i-class & mifare card has been shown
etc

30 key mismatch If the old key written in the card mismatches with the read old key.

This should be sent whenever the cafeteria card shown is a wrong

31 invalid card
card for recharge/reset API.

When the finger/palm scanning fails dues to reason like improper

32 Scan failed
finger/palm placement or bad quality template in scan template API

If the value of the parameters passed in the API is not applicable.

33 Invalid value
Example if template format is passed as 0/1 for FMX door

If finger templates received in the API and scanned templates does not
34 Credential does not match
match.

Fail to find any FP template/image for FP Template API

35 Failure
Applicable for Face Image Upload via Web API

On Set Credential API- for Face Image, if the received face image fails
36 Face Not Detected
face detection

On Set Credential API- for Face Image, if the received face image is
37 User Conflict
already enrolled against any other user

On Set Credential API- for Face Image, if for the user any previously
38 Enroll Conflict enrolled images exist and the received face image doesn't match with
the previously enrolled face images

On Set Credential API- for Face Image, if the received face image has
39 Face Mask Detected
face with mask worn.

Matrix COSEC Devices API User Guide 109

Table: API Response Codes

Response Code Description Test Condition

On Set Credential API- for Face Image, if the received face image fails
40 Full Face Not Visible
Full Face Visible conditions

On Set Credential API- for Face Image, if the extracted face from the
41 Face Not Straight
received face image is not straight

110 Matrix COSEC Devices API User Guide

Appendix

Table: Universal Time Zone Reference

Index=0 Text="(GMT-12:00) International Date Line West"

Index=1 Text="(GMT-11:00) Midway Island, Samoa"
Index=2 Text="(GMT-10:00) Hawaii"
Index=3 Text="(GMT-09:00) Alaska"
Index=4 Text="(GMT-08:00) Pacific Time (Us & Canada); Tijuana"
Index=5 Text="(GMT-07:00) Arizona"
Index=6 Text="(GMT-07:00) Chihuahua, La Paz, Mazatlan"
Index=7 Text="(GMT-07:00) Mountain Time (Us & Canada)"
Index=8 Text="(GMT-06:00) Central America"
Index=9 Text="(GMT-06:00) Central Time (Us & Canada)"
Index=10 Text="(GMT-06:00) Guadalajara, Mexico City, Monterrey"
Index=11 Text="(GMT-06:00) Saskatchewan"
Index=12 Text="(GMT-05:00) Bogota, Lima, Quito"
Index=13 Text="(GMT-05:00) Eastern Time (Us & Canada)"
Index=14 Text="(GMT-05:00) Indiana (East)"
Index=15 Text="(GMT-04:00) Atlantic Time (Canada)"
Index=16 Text="(GMT-04:00) Caracas, La Paz"
Index=17 Text="(GMT-04:00) Santiago"
Index=18 Text="(GMT-03:30) Newfoundland"
Index=19 Text="(GMT-03:00) Brasilia"
Index=20 Text="(GMT-03:00) Buenos-Aires, Georgetown"
Index=21 Text="(GMT-03:00) Greenland"
Index=22 Text="(GMT-02:00) Mid-Atlantic"
Index=23 Text="(GMT-01:00) Azores"
Index=24 Text="(GMT-01:00) Cape Verde Is"
Index=25 Text="(GMT) CASABLANCA, MONROVIA"
Index=26 Text="(GMT) Dublin, Edinburgh, Lisbon, London"
Index=27 Text="(GMT+01:00) Amsterdam, Berlin, Bern, Rome, Stockholm, Vienna"
Index=28 Text="(GMT+01:00) Belgrade, Bratislava, Budapest, Ljubljana, Prague"
Index=29 Text="(GMT+01:00) Brussels, Copenhagen, Madrid, Paris"
Index=30 Text="(GMT+01:00) Sarajevo, Skopje, Warsaw, Zagreb"
Index=31 Text="(GMT+01:00) West Central Africa"
Index=32 Text="(GMT+02:00) Athens, Beirut, Istanbul, Minsk"
Index=33 Text="(GMT+02:00) Bucharest"
Index=34 Text="(GMT+02:00) Cairo"
Index=35 Text="(GMT+02:00) Harare, Pretoria"
Index=36 Text="(GMT+02:00) Helsinki, Kyiv, Riga, Sofia, Tallinn, Vilnius"
Index=37 Text="(GMT+02:00) Jerusalem"
Index=38 Text="(GMT+03:00) Baghdad"
Index=39 Text="(GMT+03:00) Kuwait, Riyadh"
Index=40 Text="(GMT+03:00) Moscow, St Petersburg, Volgograd"
Index=41 Text="(GMT+03:00) Nairobi"
Index=42 Text="(GMT+03:30) Tehran"
Index=43 Text="(GMT+04:00) Abu Dhabi, Muscat"
Index=44 Text="(GMT+04:00) Baku, Tbilisi, Yerevan"
Index=45 Text="(GMT+04:30) Kabul"
Index=46 Text="(GMT+05:00) Ekaterinburg"
Index=47 Text="(GMT+05:00) Islamabad, Karachi, Tashkent"
Index=48 Text="(GMT+05:30) Chennai, Kolkata, New Delhi, Mumbai"
Index=49 Text="(GMT+05:45) Kathmandu"
Index=50 Text="(GMT+06:00) Almay, Novosibirsk"
Index=51 Text="(GMT+06:00) Astana, Dhaka"
Index=52 Text="(GMT+06:00) Sri Jayewardenepura"
Index=53 Text="(GMT+06:30) Rangoon"
Index=54 Text="(GMT+07:00) Bangkok, Hanoi, Jakarta"
Index=55 Text="(GMT+07:00) Krasnoyarsk"
Index=56 Text="(GMT+08:00) Beijing, Chongqing, Hong Kong, Urumqi"
Index=57 Text="(GMT+08:00) Irkutsk, Ulaanbataar"
Index=58 Text="(GMT+08:00) Kuala Lumpur, Singapore"
Index=59 Text="(GMT+08:00) Perth"
Index=60 Text="(GMT+08:00) Taipei"

Matrix COSEC Devices API User Guide 111

Table: Universal Time Zone Reference

Index=61 Text="(GMT+09:00) Osaka, Sapporo, Tokyo"

Index=62 Text="(GMT+09:00) Seoul"
Index=63 Text="(GMT+09:00) Yakutsk"
Index=64 Text="(GMT+09:30) Adelaide"
Index=65 Text="(GMT+09:30) Darwin"
Index=66 Text="(GMT+10:00) Brisbane"
Index=67 Text="(GMT+10:00) Canberra, Sydney, Melbourne,"
Index=68 Text="(GMT+10:00) Guam, Port Moresby"
Index=69 Text="(GMT+10:00) Hobart"
Index=70 Text="(GMT+10:00) Vladivostok"
Index=71 Text="(GMT+11:00) Magadan, Solomon Is, New Caledonia"
Index=72 Text="(GMT+12:00) Auckland, Wellington"
Index=73 Text="(GMT+12:00) Fiji, Kamchatka, Marshall Is"
Index=74 Text="(GMT+13:00) Nuku'alofa"

Event Configuration Reference

Table: List of Events

Event ID Event Description

101 User Allowed

102 User Allowed – with Duress

103 User Allowed – Anti-Pass Back-soft

104 User Allowed - Dead-man Zone

105 User Allowed – Door Not open

106 User Allowed – Smart Secure Access

107 User Allowed – Smart card based route access - soft

108 User Allowed – Panel route access - soft

109 User Allowed – two person rule - primary user

110 User Allowed – two person rule - secondary user

111 Visitor Allowed

112 User Allowed – Multi-Level Access

151 User Denied – User Invalid

152 User Denied – Occupancy Control

153 User Denied – 2-Person Rule

154 User Denied – Time Out

155 User Denied – Visitor Escort Rule

156 User Denied – Anti-Pass Back

157 User Denied – Disabled User

158 User Denied – Blocked User

159 User Denied – First IN User

160 User Denied – DND Enabled

161 User denied – Control zone

112 Matrix COSEC Devices API User Guide

Table: List of Events

Event ID Event Description

162 User Denied – Door Lock

163 User Denied – Invalid Access Group

164 User Denied – Validity date expired

165 User Denied – Invalid Route Access

166 User Denied – Invalid Shift Access

167 User Denied – Invalid Access Cluster

171 Visitor Denied

172 User Denied – FP sensor busy

201 Door Status changed

202 Dead-man timer changed

203 DND status changed

204 Aux input status changed

205 Aux output status changed

206 Door sense input status

207 Door Controller Communication status

208 Door Open/ Close

209 Lock relay status changed

301 Dead-man timer expired Alarm– User IN

302 Duress detection

303 Panic Alarm

304 FP Memory Full – Alarm

305 Door Held open too long

306 Door Abnormal

307 Door force open

308 Door Controller Offline

309 Door Controller -Fault

310 Tamper Alarm

311 Master Controller Mains fail Alarm

312 Master Controller Battery fail

313 Master Alarm – MC Alarm input

314 RTC

315 Event Buffer Full

317 Intercom - panic

318 Occupancy Violated Alarm

319 Tail- Gating Alarm

320 Man Trap Timer Violated Alarm

Matrix COSEC Devices API User Guide 113

Table: List of Events

Event ID Event Description

321 Access Denied Aalrm

322 Multiple Unauthorized Access Alarm

323 Custom Alarm 1

324 Custom Alarm 2

325 Custom Alarm 3

326 User Unidentified

327 Anti-Pass Back Violated Alarm

328 Access Route Violated Alarm

329 Raise Alarm

351 Alarm acknowledged

352 Alarm cleared

353 Alarm Re-issued

401 User Block/Restore

402 Login to ACS

403 Message transaction confirmation to ACMS

404 Guard Tour-status

405 Enrolment

406 Master Alarm sense input status

407 Master Aux Output status

408 Input Output Group Link status

409 Credentials Deleted

410 Time Triggered Function

411 Time Stamping Function

412 Guard tag

413 Camera Event for time stamp

451 Configuration Change

452 Roll over of events

453 Master Controller Power ON

454 Configuration Defaulted

455 Soft Override

456 Backup and Update

457 Default System

458 Sensor Calibration

459 User Denied – invalid card

460 User PIN Change

114 Matrix COSEC Devices API User Guide

 Some of the events listed are applicable only on Panels/Panel Doors and not on Direct Doors. Refer the
respective event tables to see the applicable doors for each event.

Table: Size of Event Fields

Door Field 1 Field 2 Field 3 Field 4 Field 5 Event Log Capacity

Direct Door V2 4 bytes 2 bytes 2 bytes N.A. N.A. 50,000 events

Path Controller 4 bytes 2 bytes 2 bytes N.A. N.A. 50,000 events

Wireless Door 4 bytes 2 bytes 2 bytes 4 bytes 4 bytes 5,00,000 events

NGT Direct Door 4 bytes 2 bytes 2 bytes 4 bytes 4 bytes 1,00,000 events

PVR Door 4 bytes 2 bytes 2 bytes 4 bytes 4 bytes 1,00,000 events

Vega Controller 4 bytes 2 bytes 2 bytes 4 bytes 4 bytes 5,00,000 events

Panel200 4 bytes 2 bytes 2 bytes 4 bytes 4 bytes 5,00,000 events

ARC 4 bytes 2 bytes 2 bytes N.A. N.A. 1,00,000 events

IO Controller 4 bytes 2 bytes 2 bytes N.A. N.A. 1,00,000 events

Door FMX 4 bytes 2 bytes 2 bytes 4 bytes 4 bytes 5,00,000 events

Direct Door V3 4 bytes 2 bytes 2 bytes 4 bytes 4 bytes 5,00,000 events

Direct Door V4 4 bytes 2 bytes 2 bytes 4 bytes 4 bytes 5,00,000 events

ARGO 4 bytes 2 bytes 2 bytes 4 bytes 4 bytes 5,00,000 events

Table: User Events

Event Details Applicable Devices

(Field
(Field (Field Wire Panel/
(Field 4)
1) 3) less Panel- Direct
2) and Direct Path Vega
Event Door NGT PVR Lite/ Door Door
(Field Door Contr Contr ARC ARGO
ID / Door Door Standalo FMX V4
Special 5) V2 oller oller
User Entry/ Door ne
Code
ID Exit V3 Panellite

User Allowed Events

Xxxx

(user Special
101 ID=0 Functio Detail           
for n code
REX
input)

Special 
102 Xxxx Functio Detail          
n code

Special
103 Xxxx Functio Detail           
n code

Special
104 Xxxx Functio Detail           
n code

Matrix COSEC Devices API User Guide 115

Table: User Events

Event Details Applicable Devices

(Field
(Field (Field Wire Panel/
(Field 4)
1) 3) less Panel- Direct
2) and Direct Path Vega
Event Door NGT PVR Lite/ Door Door
(Field Door Contr Contr ARC ARGO
ID / Door Door Standalo FMX V4
Special 5) V2 oller oller
User Entry/ Door ne
Code
ID Exit V3 Panellite

Special
105 Xxxx Functio
n code
Detail           
Special
106 Xxxx Functio Detail           
n code

Special
107 Xxxx Functio Detail           
n code

Special
108 Xxxx Functio
n code
Detail           
Special
109 Xxxx Functio Detail           
n code

Special
110 Xxxx Functio Detail           
n code

First
four
last two
bytes
bytes of
111
of
extensi
extensi Detail           
on
on
number
numbe
r

0=
Door
112 Xxxx
unlock
1=
Detail           
Door
lock

User Denied Events

(User
Special
ID = 0
Functio
151 if not
n code
Detail           
identifi
ed)

152 Xxxx Detail           

153 Xxxx Detail           

154 Xxxx Detail           

155 Xxxx Detail           

156 Xxxx Detail           

157 Xxxx Detail           

158 Xxxx Detail           

116 Matrix COSEC Devices API User Guide

Table: User Events

Event Details Applicable Devices

(Field
(Field (Field Wire Panel/
(Field 4)
1) 3) less Panel- Direct
2) and Direct Path Vega
Event Door NGT PVR Lite/ Door Door
(Field Door Contr Contr ARC ARGO
ID / Door Door Standalo FMX V4
Special 5) V2 oller oller
User Entry/ Door ne
Code
ID Exit V3 Panellite

159 Xxxx Detail           

160 Xxxx Detail       

161 Xxxx Detail           

162 Xxxx Detail           

163 Xxxx Detail       

164 Xxxx Detail           

0=Door
Not in
Sequen
ce
          
1=Door
Not in
Route

2=Door
Not in
Sequen
ce for
Smart
card
based
Route

3=Door
Not in
Smart
card           
based
Route

4=Cred
165 Xxxx ential Detail
Invalid
for
Smart
card
based
Route
Access

5=Door
cannot
be
accese
d now
due to
time           
zone
inside
access
route
violatio
n

6=Door
is not
assigne           
d

Matrix COSEC Devices API User Guide 117

Table: User Events

Event Details Applicable Devices

(Field
(Field (Field Wire Panel/
(Field 4)
1) 3) less Panel- Direct
2) and Direct Path Vega
Event Door NGT PVR Lite/ Door Door
(Field Door Contr Contr ARC ARGO
ID / Door Door Standalo FMX V4
Special 5) V2 oller oller
User Entry/ Door ne
Code
ID Exit V3 Panellite

0=Outsi
de
working
hours           
1=Holid
ay

166 Xxxx Detail

2=Wee
k off

3=Field
Break           
4=Rest
Day

167 Xxxx Detail           

First
four
last two
bytes
bytes of
171
of
extensi
extensi Detail           
on
on
number
numbe
r

172 Xxxx Detail           

Table: Special Function Codes Reference

Applicable for Allowed Applicable for Denied

S.No. Special Function Name Special Function Code
Events Events

1
Official Work-IN Marking in
1 

T&A

2
Official Work-OUT Marking
2 

in T&A

3
Short Leave-IN Marking in
3 

T&A

4
Short Leave-OUT Marking
4 

in T&A

5 Clock - IN Marking in T&A 5 



6
Clock - OUT Marking in
6 

T&A

7
Post Lunch-IN Marking in
7 

T&A

8
Pre Lunch -OUT Marking
8 

in T&A

118 Matrix COSEC Devices API User Guide

Table: Special Function Codes Reference

Applicable for Allowed Applicable for Denied

S.No. Special Function Name Special Function Code
Events Events

9
Over time – IN Marking in
9 

T&A

10
Over time – OUT Marking
10 

in T&A

11
Late –IN Allowed Marking
11 

in T&A

12
Early - OUT Allowed
12 

Marking in T&A

Access in Degrade Mode

13 99  
Marking

14 Smart Identification 98  

15 e-Canteen 97  

Table: Field 3 Detail (User Events) Reference

Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0

API Entry/
RFU Group Palm Finger Card PIN RFU RFU
Exit

Table: Information of Bit 0 and Bit 1

Credential Bit 1 Bit 0 Value

Entry 0 0 0 

Exit 0 1 1 

Entry with Time Stamp Active 1 0 2 

Exit with Time Stamp Active 1 1 3 

Table: Information of Bit 4 and Bit 9

Credential Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Value

PIN 0 0 0 0 0 1 1

Card 0 0 0 0 1 0 2

Card + PIN 0 0 0 0 1 1 3

Finger 0 0 0 1 0 0 4

Finger + PIN 0 0 0 1 0 1 5

Finger + Card 0 0 0 1 1 0 6

Finger + Card + PIN 0 0 0 1 1 1 7

Matrix COSEC Devices API User Guide 119

Table: Information of Bit 4 and Bit 9

Credential Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Value

Palm 0 0 1 0 0 0 8

PIN + Palm 0 0 1 0 0 1 9

Card + Palm 0 0 1 0 1 0 10

PIN + Card + Palm 0 0 1 0 1 1 11

Group + Palm 0 1 1 0 0 0 24

API 1 0 0 0 0 0 32

API + Finger 1 0 0 1 0 0 36

API + Palm 1 0 1 0 0 0 40

API + PIN 1 0 0 0 0 1 33

Group + Finger 0 1 0 1 0 0 20

Table: Alarm Events

Event Details Applicable Devices

(Field
4) Direct Path Wirel Vega Panel/ Direct ARC
Event (Field (Field (Field NGT PVR Door
and Door Contr ess Contro Panel ARGO Door Contro
ID 1) 2) 3) Door Door FMX
(Field V2 oller Door ller Lite V4 ller
5)

Refer Alarm
301
ence
ID
1=
Critical
Seque-
nce           
Xxxx Number

Refer
Same
302
ence
ID
1=
Critical
as           
above
Xxxx

120 Matrix COSEC Devices API User Guide

Table: Alarm Events

Event Details Applicable Devices

(Field
4) Direct Path Wirel Vega Panel/ Direct ARC
Event (Field (Field (Field NGT PVR Door
and Door Contr ess Contro Panel ARGO Door Contro
ID 1) 2) 3) Door Door FMX
(Field V2 oller Door ller Lite V4 ller
5)

Refer
Same
303
ence
ID
1=
Critical
as           
above
Xxxx

1=
Intern
Same
304
al
2=
3=
Minor
as           
above
Exter
nal

Same
305
3=
Minor
as           
above

Same
2=
306
Major
as           
above

Same
307
1=
Critical
as           
above

Same
308
2=
Major
as           
above

Same
2=
309
Major
as           
above

Same
1=
310
Critical
as           
above

Same
311
2=
Major
as           
above

Matrix COSEC Devices API User Guide 121

Table: Alarm Events

Event Details Applicable Devices

(Field
4) Direct Path Wirel Vega Panel/ Direct ARC
Event (Field (Field (Field NGT PVR Door
and Door Contr ess Contro Panel ARGO Door Contro
ID 1) 2) 3) Door Door FMX
(Field V2 oller Door ller Lite V4 ller
5)

Same
312
1=
Critical
as
above
          
Same
313
1=
Critical
as
above
          
1=
Powe
r ON/
OFF
Detec
ted
(time
not in
sync)
2=
Major Same
314
2=
low
1= as           
Critical above
batter
y
detec
ted

3=
RTC
Not
Detec
ted

2=
Same
315 0
Major
1=
as           
above
Critical

First
four Last
bytes two
Same
317
of
Exten
bytes of
extensi
as           
above
sion on
numb number
er

Refer
Same
318
ence
ID
2=
Major
as           
above
Xxxx

Refer
Same
319
ence
ID
2=
Major
as
above
          
Xxxx

122 Matrix COSEC Devices API User Guide

Table: Alarm Events

Event Details Applicable Devices

(Field
4) Direct Path Wirel Vega Panel/ Direct ARC
Event (Field (Field (Field NGT PVR Door
and Door Contr ess Contro Panel ARGO Door Contro
ID 1) 2) 3) Door Door FMX
(Field V2 oller Door ller Lite V4 ller
5)

Refer
Same
320
ence
ID
2=
Major
as           
above
Xxxx

Refer
Same
321
ence
ID
2=
Major
as
above
          
Xxxx

Refer
Same
322
ence
ID
2=
Major
as           
above
Xxxx

Same
323
2=
Major
as
above
          
Same
324
2=
Major
as
above
          
Same
325
2=
Major
as           
above

Same
326
2=
Major
as           
above

Refer
Same
327
ence
ID
2=
Major
as
above
          
Xxxx

Refer
Same
328
ence
ID
2=
Major
as           
above
Xxxx

Refer
Same
329
ence
ID
2=
Major
as           
above
Xxxx

4=
SysInte
rlock
5=
User_J Same
351 eeves as           
6= above
User_A
CMS
9=
Auto

4=
SysInte
rlock
5=
User_J
eeves Same
352 6= as           
User_A above
CMS
7=
Special
Functio
n

Same
353 as           
above

Matrix COSEC Devices API User Guide 123

Table: System Events

Event Details Applicable Devices

Panel/
(Field Wirele
Panel
4) Direct Path ss Vega IO ARC Direct
Event (Field (Field (Field NGT PVR Door Lite/
and Door Contr Door/ Contr Contr Contr ARGO Door
ID 1) 2) 3) Door Door FMX Standalo
(Field V2 oller Door oller oller oller V4
ne Panel
5) V3
lite

0=
Unuse
d
(Resto
re
User)

1=Abs
entee
Rule

2=Una
uthoriz
ed
access

3=Usa
ge
count 1=
Block
User 4=Inva ed
401 ID:
xxxx
lid PIN
0=
           
5=Tail Restor
Gating ed

6=Man
Trap
Timer
Violate
d

7=Occ
upanc
y
Violate
d

8=Anti
-Pass
Back
Violate
d

5= SA

6= SE 1=Suc
402
7=
cess
0=Fail
           
Operat
or

Trans 1=Suc
403
action
ID:
cess
0=Fail            
Xxxx

Guard
Tour
1=Suc
404
no.
Xxxx +
cess            
0=Fail
cycle
no.

124 Matrix COSEC Devices API User Guide

Table: System Events

Event Details Applicable Devices

Panel/
(Field Wirele
Panel
4) Direct Path ss Vega IO ARC Direct
Event (Field (Field (Field NGT PVR Door Lite/
and Door Contr Door/ Contr Contr Contr ARGO Door
ID 1) 2) 3) Door Door FMX Standalo
(Field V2 oller Door oller oller oller V4
ne Panel
5) V3
lite

8=
User
Card
9=
User
Finger
Propri
ety
format
e
10=
Specia
l
Cards
14=
Palm
16=
palm
templa
te with
guide
refere
mode
405
nce
ID:
17=Us            
er
Xxxx
Finger
-
Supre
ma
ISO
format
18=Us
er
Finger
-
Lumidi
gm
ISO
format
19=
User
Face
20=Mo
bile
Device

1=Nor
mal

2=Fau
lt
(Open
)
406
3=
           
Fault(
Short)

4=
Activa
ted

1=Nor
407
mal
4=Acti            
vated

11 =
Pulse
12 =
Interlo
ck
13 =
1=Nor
I/O Latch
mal
408 Link 15 =
4=Acti            
ID Toggle
vated
(only
with
activat
ed
event)

Matrix COSEC Devices API User Guide 125

Table: System Events

Event Details Applicable Devices

Panel/
(Field Wirele
Panel
4) Direct Path ss Vega IO ARC Direct
Event (Field (Field (Field NGT PVR Door Lite/
and Door Contr Door/ Contr Contr Contr ARGO Door
ID 1) 2) 3) Door Door FMX Standalo
(Field V2 oller Door oller oller oller V4
ne Panel
5) V3
lite

5=
8=
Web
User
Jeeve
Cards
s
9=
6=
409
ID:
Xxxx
User
Finger
ACMS            
7=
s
Speci
14 =
al
Palm
Functi
on

1=Nor
Time mal/
Trigge Deacti
410 red vated            
Functi
on Id 4=Acti
vated

1=Nor
Time mal/
Stamp Deacti
411 ing vated            
Functi
on ID 4=Acti
vated

Door
Guard
Contro
tour 1=Suc
412 no.
+cycle
ller
seque
cess            
0=Fail
nce
no.
no.

event
seque roll 1=Suc
413 nce over cess            
numb count 0=Fail
er

Config
ur-
451 ation
Table
Index
start
Index
end            
ID xxx

Roll
over
numb
452
er            
00 to
99

453            
Config
ur-
454 ation
Index
start
Index
end            
Table
ID xxx

126 Matrix COSEC Devices API User Guide

Table: System Events

Event Details Applicable Devices

Panel/
(Field Wirele
Panel
4) Direct Path ss Vega IO ARC Direct
Event (Field (Field (Field NGT PVR Door Lite/
and Door Contr Door/ Contr Contr Contr ARGO Door
ID 1) 2) 3) Door Door FMX Standalo
(Field V2 oller Door oller oller oller V4
ne Panel
5) V3
lite

1= 2-
person
Rule
Time
2=
Period
Acces
= xxx
s
(config
Policie
ured
s
value)
3=
Alarms
(this
4=
field is
Anti- 1=
used
pass Overri
only
455 with
Overri
back
5=
dden
0=            
First In Resu
dden
User med
events
6=
)
Mantra
p
Resu
7=
me
Occup
events
ancy
will
control
have
8=
blank
Visitor
Escort
Rule

0=
1=Con Fail
figurati 1=
1=Bac
on Succe
456
kup
2=Upd
2=Eve
nt
ss            
2=
ate
3=Fir CRC
mware Check
Fail

6=
from
ACMS
457 8=            
from
Hardw
are

0=
Interna
l 0=
Finger Fail
Reade 1=
r Succe
458 ss            
1= 2=
Extern Not
al Suppo
Finger rted
Reade
r

459
Card
ID
Card
ID
Card
ID            

Refere
460
nce
ID:            
xxxx

0= Syste
Refere Author m
461
nce
ID:
ized
1=
User
Index            
xxxx Reject 1 to
ed 10

Matrix COSEC Devices API User Guide 127

Table: Cafeteria Events

Event Details Applicable Devices

Direct Path Wirel Vega Panel/ ARC Direct

Event (Field (Field (Field (Field (Field NGT PVR Door
Door Contro ess Contr Panel Contr ARGO Door
ID 1) 2) 3) 4) 5) Door Door FMX
V2 ller Door oller Lite oller V4

Item
Code +
Refere Menu Menu
501 nce ID
Xxxx
Numbe
r+
Numb
er
Item
Cost           
Quantit
y

Item
User
Code +
Level
Refere Menu Discou
502 nce ID Numbe
+
Menu
Item
Cost
nt           
Xxxx r+ Value
Numb
Quantit
er
y

Item
Code +
Refere Menu Menu
503 nce ID Numbe Numb
Item
Cost           
Xxxx r+ er
Quantit
y

Item
User
Code +
Level
Refere Menu Discou
504 nce ID Numbe
+
Menu
Item
Cost
nt           
Xxxx r+ Value
Numb
Quantit
er
y

Item
Code + Menu
505 Menu Numb
Item
Cost
          
Numbe er
r

Item
Code + Menu
506 Menu
Numbe
Numb
Item
Cost           
er
r

Trans Availab
Refere
507 nce ID
Xxxx
action
Amou
le
Balanc
          
nt e

0=
Failure
Previo Rechar
Refere 1=Suc
508 nce ID cessful
us
Balan
ge
Amoun
          
Xxxx 2=verifi
ce t
cation
failed

0=
Failure
Previo
Refere 1=Suc
509 nce ID cessful
us
Balan
Reset
Value           
Xxxx 2=verifi
ce
cation
failed

Previo Transa
Refere Menu
510 nce ID Numb
us
Balan
ction
Amoun           
Xxxx er
ce t

Transa
Refere Menu
511 nce ID Numb
ction
Amoun           
Xxxx er
t

128 Matrix COSEC Devices API User Guide

Table: Cafeteria Events

Event Details Applicable Devices

Direct Path Wirel Vega Panel/ ARC Direct

Event (Field (Field (Field (Field (Field NGT PVR Door
Door Contro ess Contr Panel Contr ARGO Door
ID 1) 2) 3) 4) 5) Door Door FMX
V2 ller Door oller Lite oller V4

0=
Conse
cutive
Refere
512 nce ID
transac
tion           
Xxxx
1= pre-
orderin
g

Matrix COSEC Devices API User Guide 129

SECURITY SOLUTIONS

MATRIX COMSEC PVT. LTD.

Head Office:
394-GIDC, Makarpura, Vadodara - 390010, India.
Ph.: 18002587747
E-mail: [email protected]

Website: www.matrixcomsec.com