COSEC DEVICES API GUIDE Manual Device

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 79

SECURITY SOLUTIONS
COSEC Devices API
User Guide
COSEC Devices API
User Guide
SECURITY SOLUTIONS
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 1.0
Release date: May 31, 2014
Table of Contents i
Contents
Contents .......................................................................................................................................................... i
List of Tables .................................................................................................................................................. 3
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 ............................................................................................................................... 4
Prerequisite ......................................................................................................................................................... 5
Authentication ..................................................................................................................................................... 5
HTTP Request-Response ................................................................................................................................... 5
Communication Flow ..................................................................................................................................................................... 6
Request Format ............................................................................................................................................................................. 6
Response Format .......................................................................................................................................................................... 7
URL Syntax .................................................................................................................................................................................... 8
Common Actions ........................................................................................................................................................................... 9
Additional Information ....................................................................................................................................... 10
Supported APIs ............................................................................................................................................ 11
API Quick Reference ......................................................................................................................................... 11
Device Configuration ................................................................................................................................... 13
Basic Device Configuration ............................................................................................................................... 14
Function Key Configuration ............................................................................................................................... 17
Reader Configuration ........................................................................................................................................ 18
Finger Reader Parameter Configuration ........................................................................................................... 20
Palm Sensor Parameter Configuration ............................................................................................................. 21
Enrollment Configuration ................................................................................................................................... 22
Access Settings Configuration .......................................................................................................................... 24
Alarm Configuration .......................................................................................................................................... 25
Date and Time Configuration ............................................................................................................................ 26
Door Features Configuration ............................................................................................................................. 29
System Timers Configuration ............................................................................................................................ 31
Special Function Configuration ......................................................................................................................... 32
User Configuration ...................................................................................................................................... 33
Setting/Retrieving User Configuration ............................................................................................................... 34
Setting a User Photo ......................................................................................................................................... 37
Deleting a User ................................................................................................................................................. 39
Setting User Credentials ................................................................................................................................... 40
Retrieving User Credentials .............................................................................................................................. 41
Deleting User Credentials ................................................................................................................................. 43
Enrollment .................................................................................................................................................... 44
Enrolling a User ................................................................................................................................................. 45
Enrolling Special Cards ..................................................................................................................................... 48
Events ........................................................................................................................................................... 49
Retrieving Events .............................................................................................................................................. 50
ii Table of Contents
Retrieving Events in the TCP Socket ................................................................................................................ 52
Sending Commands to Device ................................................................................................................... 54
Error Responses .......................................................................................................................................... 57
API Response Codes ................................................................................................................................... 59
Appendix ...................................................................................................................................................... 61
List of Tables
Table: API Quick Reference .......................................................................................................................... 11
Table: Device Configuration Parameters ....................................................................................................... 14
Table: Function Key Configuration Parameters ............................................................................................. 17
Table: Reader Configuration Parameters ...................................................................................................... 18
Table: Finger Reader Parameter Configuration - Parameters ....................................................................... 20
Table: Finger Reader Parameter Configuration - Parameters ....................................................................... 21
Table: Enrollment Configuration Parameters ................................................................................................. 22
Table: Access Settings Configuration Parameters ........................................................................................ 24
Table: Alarm Configuration Parameters ........................................................................................................ 25
Table: Date and Time Configuration Parameters .......................................................................................... 26
Table: Door Features Configuration Parameters ........................................................................................... 29
Table: System Timers Configuration Parameters .......................................................................................... 31
Table: Special Function Configuration Parameters ....................................................................................... 32
Table: User Configuration Parameters .......................................................................................................... 34
Table: Setting a User Photo - Parameters ..................................................................................................... 37
Table: Delete User - Parameters ................................................................................................................... 39
Table: Setting User Credentials - Parameters ............................................................................................... 40
Table: Retrieving User Credentials - Parameters .......................................................................................... 41
Table: Deleting User Credentials - Parameters ............................................................................................. 43
Table: Enrolling User - Parameters ............................................................................................................... 45
Table: Enroll Special Cards - Parameters ..................................................................................................... 48
Table: Retrieving Events - Parameters .......................................................................................................... 50
Table: Value Range for Event Sequence Numbers ....................................................................................... 50
Table: Retrieving Events in the TCP Socket - Parameters ............................................................................ 52
Table: List of Commands to Device ............................................................................................................... 54
Table: Get Credential Count Command - Parameters ................................................................................... 54
Table: Deleting Credentials for All Users - Parameters ................................................................................. 56
Table: API Response Codes ......................................................................................................................... 59
Table: Universal Time Zone Reference ......................................................................................................... 61
Table: List of Events ...................................................................................................................................... 62
Table: Size of Event Fields ............................................................................................................................ 64
Table: User Events ........................................................................................................................................ 64
Table: Special Function Codes Reference .................................................................................................... 66
Table: Field 3 Detail (User Events) Reference .............................................................................................. 67
Table: Information of Bit 0 and Bit 1 .............................................................................................................. 67
Table: Information of Bit 4 and Bit 8 .............................................................................................................. 67
Table: Door Events ........................................................................................................................................ 68
Table: Alarm Events ...................................................................................................................................... 69
Table: System Events .................................................................................................................................... 70
Matrix COSEC Devices API User Guide 1
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 2
Document Organization
This document has been organized into the following topics:
1. About the Document
2. API Overview
3. Supported APIs
4. Device Configuration
5. User Configuration
6. Enrollment
7. Events
8. Sending Commands to Devices
9. Error Responses
10. API Response Codes
11. 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 with a quick reference list for the user. Topics 4-8
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 9 provides illustrations of error messages. Topic 10 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.
Matrix COSEC Devices API User Guide 3
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.
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.
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.
Fig. Communication through COSEC Web Server
HTTP Request
HTTP Response
Direct Door
3rd Party Application
Fig. Communication through COSEC API
Matrix COSEC Devices API User Guide 4
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 Path Controller
• COSEC Wireless Door
• COSEC NGT Door
• COSEC PVR Door
• COSEC Vega Controller
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).
• 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
Matrix COSEC Devices API User Guide 5
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: 1234
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)
Start-line = Request-Line | Status-Line
Matrix COSEC Devices API User Guide 6
Communication Flow
The communication takes place in the following manner:
1. The client checks availablility of the device.
2. If available, the client issues a request for the device.
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:
1. Request Line
This line is constituted by the following three elements which must be
separated by a space:
• The method type (GET, HEAD, POST, PUT etc.)
• 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
Cosec
Device
3 rd party
software
SERVER CLIENT
REQUEST: w ith syntax, but no authentication / invalid authentication
RESPONSE: denied
Response status code ( 4xx) along with suggestions of supported
authentication method
REQUEST: with syntax and supported passw ord authentication
RESPONSE: successful
Requested Message body along with response status code i .e 2xx
REQUEST: the server is not
connected
Fig: communication flow
REQUEST: invalid syntax but valid authentication
RESPON SE: denied
Response status code (4xx)
Matrix COSEC Devices API User Guide 7
Example:
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:
It consists of the following components:
2. Header Fields
Add information about the request using these header fields:
• A General Header (<Header-name>:<value>).
• A Request Header (<Header-name>:<value>).
• An Entity Header (<Header-name>:<value>).
3Empty Line This is an empty line separating headers from the message body.
4Message Body This is the chunk or payload.
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)
VERSION-HTTP CODE EXPLANATION<crlf>
HEADER: Value<crlf>
.
.
.
HEADER: Value<crlf>
Empty line<crlf>
BODY OF THE RESPONSE
1. A status line
This line is constituted by the following three elements which must be
separated by a space:
• 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.
2. The response header fields
These optional lines allow additional information to be added to the
response header. This information appears in the form of a name
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.
Matrix COSEC Devices API User Guide 8
Example
When the server gets a request, it will respond with a standard HTTP status code as illustrated in the following
sample response:
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
Take a close look at the URL and its basic elements:
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://<deviceIP:deviceport>/device.cgi/<request-type>?<argument>=<value>[&<argument>=<value>......]
URL element Description
http:// This is the protocol used to communicate with the client.
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.
<deviceIP:deviceport>
This identifies the device with which communication is to be performed. It
consists of two components:
deviceIP: Device IP address
deviceport: Device Port Number
device.cgi This is a mandatory entity required to specify the CGI directory for all the
device-related commands.
<request-type> This specifies the type of API request. For the mandatory request types,
please refer to the individual API descriptions.
Matrix COSEC Devices API User Guide 9
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:
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:
<argument>
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
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.
http://192.168.x.y:80/device.cgi/device-basic-config?action=get&format=xml
Action Use
GET To fetch required data from device.
SET To set required parameters for a given function.
GETDEFAULT
This is used to get default the parameters of all/ specified
argument. If any argument is specified then default value of
that particular argument is returned else default value of
complete group is returned.
SETDEFAULT
This is used to default the parameters. If any argument is
specified then default that particular value else default
complete group
URL element Description
Matrix COSEC Devices API User Guide 10
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.
DELETE To delete data from device.
ENROLL To enroll an entity to a device.
Action Use
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
API Quick Reference
This section enables users to view a quick reference list of all supported Devices APIs discussed in the guide. The
following table lists all functions along with their respective HTTP Request URLs and the applicable action values.
For further details on supported parameters and values, refer to the respective argument-value tables for individual
APIs (See List of Tables).
Table: API Quick Reference
URL Actions Functionality
http://<deviceIP:deviceport>/device.cgi/device-basic-
config?action=<value>[&<argument>=<value>….]
get, set, getdefault,
setdefault
Basic Device Configuration
http://<deviceIP:deviceport>/device.cgi/function-
key?action=<value>[&<argument>=<value>….]
get, set, getdefault,
setdefault
Function Key Configuration
http://<deviceIP:deviceport>/device.cgi/reader-
config?action=<value>[&<argument>=<value>….]
get, set, getdefault,
setdefault
Reader Configuration
http://<deviceIP:deviceport>/device.cgi/enroll-
options?action=<value>[&<argument>=<value>….]
get, set, getdefault,
setdefault
Enrollment Configuration
http://<deviceIP:deviceport>/device.cgi/access-
setting?action=<value>[&<argument>=<value>….]
get, set, getdefault,
setdefault
Access Settings Configuration
http://<deviceIP:deviceport>/device.cgi/
alarm?action=<value>[&<argument>=<value>….]
get, set, getdefault,
setdefault
Alarm Configuration
http://<deviceIP:deviceport>/device.cgi/date-
time?action=<value>[&<argument>=<value>….]
get, set, getdefault,
setdefault
Date and Time Configuration
http://<deviceIP:deviceport>/device.cgi/door-
feature?action=<value>[&<argument>=<value>….]
get, set, getdefault,
setdefault
Door Features Configuration
http://<deviceIP:deviceport>/device.cgi/system-
timer?action=<value>[&<argument>=<value>….]
get, set, getdefault,
setdefault
System Timers Configuration
http://<deviceIP:deviceport>/device.cgi/special-
function?action=<value>[&<argument>=<value>….]
get, set, getdefault,
setdefault
Special Function Configuration
http://<deviceIP:deviceport>/device.cgi/
users?action=<value>[&<argument>=<value>….]
set, get Setting/Retrieving User Configuration
http://<deviceIP:deviceport>/device.cgi/
userphoto?action=<value>[&<argument>=<value>….]
get, set, delete Setting a User Photo
http://<deviceIP:deviceport>/device.cgi/
users?action=delete[&<argument>=<value>….]
delete Deleting a User
http://<deviceIP:deviceport>/device.cgi/
credential?action=set[&<argument>=<value>….]
set Setting User Credentials
http://<deviceIP:deviceport>/device.cgi/
credential?action=get[&<argument>=<value>….]
get Retrieving User Credentials
Matrix COSEC Devices API User Guide 12
http://<deviceIP:deviceport>/device.cgi/
credential?action=delete[&<argument>=<value>….]
delete Deleting User Credentials
http://<deviceIP:deviceport>/device.cgi/
enrolluser?action=enroll[&<argument>=<value>….]
enroll Enrolling a User
http://<deviceIP:deviceport>/device.cgi/
enrollspcard?action=enroll[&<argument>=<value>….]
enroll Enrolling Special Crads
http://<deviceIP:deviceport>/device.cgi/
events?action=getevent[&<argument>=<value>….]
getevent Retrieving Events
http://<deviceIP:deviceport>/device.cgi/tcp-
events?action=getevent[&<argument>=<value>….]
getevent Retrieving Events in TCP Socket
http://<deviceIP:deviceport>/device.cgi/
command?action=clearalarm
clearalarm Sending Commands -
Clear Alarm
http://<deviceIP:deviceport>/device.cgi/
command?action=getcount
getcount Sending Commands -
Get Credential Count for Enrolled
Credentials
http://<deviceIP:deviceport>/device.cgi/
command?action=acknoledgealarm
acknoledgealarm Sending Commands -
Acknowledge Alarm
http://<deviceIP:deviceport>/device.cgi/
command?action=lockdoor
lockdoor Sending Commands -
Lock Door
http://<deviceIP:deviceport>/device.cgi/
command?action=unlockdoor
unlockdoor Sending Commands -
Unlock Door
http://<deviceIP:deviceport>/device.cgi/
command?action=normalizedoor
normalizedoor Sending Commands -
Normalize Door
http://<deviceIP:deviceport>/device.cgi/
command?action=getusercount
getusercount Sending Commands -
Getting User Count on Device
http://<deviceIP:deviceport>/device.cgi/
command?action=geteventcount geteventcount
Sending Commands -
Get Current Event Sequence
Number
http://<deviceIP:deviceport>/device.cgi/
command?action=systemdefault systemdefault Sending Commands - Default the
System Configuration
http://<deviceIP:deviceport>/device.cgi/
command?action=deletecredential deletecredential Sending Commands - Delete
Credentials for All Users
Table: API Quick Reference
URL Actions Functionality
Matrix COSEC Devices API User Guide 13
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
Matrix COSEC Devices API User Guide 14
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
app 1, 2 No
To define the application.
1 = Advanced Access Control
2 = Basic Access Control
name Alphanumeric,
Max. 30 characters No To identify/configure the device name.
asc-code Numeric, 16 bits,
1-65535 range No To configure an Additional Security Code
(ASC). Should be non-zero.
Max-fingers
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
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
No Maximum no. of templates that can be stored
per user on this device.
format text, xml No specifies the format in which the response is
expected.
Matrix COSEC Devices API User Guide 15
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.
Example
Following are some test cases for your reference:
1. To get all parameters.
2. To get device name, when expected value is blank and the response format is in text.
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
Sample Response
HTTP Code: 200 OK
Content-Type: <code>
Content-Length: <type>
Body:
app=1 name= asc-code=0 max-fingers=1
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=
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>
<name></name>
<app>1</app>
</COSEC_API>
Matrix COSEC Devices API User Guide 16
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:
Example
1. To configure function key F1 as official work – IN.
Table: Function Key Configuration Parameters
Argument Valid Values Mandatory Description
F1 0 = None
1 = Official IN
2 = Official OUT
3 = Short Leave IN
4 = Short Leave OUT
5 = Regular IN
6 = Regular OUT
7 = Post Break IN
8 = Pre - Break OUT
9 = Overtime IN
10 = Overtime OUT
No
Assigning special functions to
respective function keys.
F2
F3
F4
format text,xml No Specifies the format in which the
response is expected.
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
Matrix COSEC Devices API User Guide 18
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
Argument Valid Values Mandatory Description
reader1
0 = None
1 = EM Prox Reader
2 = HID Prox Reader
3 = MiFare Reader
4 = HID iCLASS-U Reader
5 = HID iCLASS-W Reader
No To define the internal card
reader.
reader2
0 = None
1 = Finger Reader
2 = Palm Vein Reader
No To define the internal biometric
reader.
reader3
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
7 = UHF Reader
8 = Combo Exit Reader
9 = MiFare-W Reader
No To define the external reader.
door-access-mode
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
10 = Card + PIN + Palm
11 = Palm + Group (Optional)
12 = Finger then Card
13 = Palm then Card
No To define the access mode
applicable for door access.
door-entry-exit-mode 0 = Entry
1 = Exit No
To define the whether the
internal reader is to be set on an
entry or exit mode.
Matrix COSEC Devices API User Guide 19
Example
1. To configure internal card reader as an HID Prox reader and internal reader mode as entry.
reader-access-mode
0 = Card
1 = Finger
4 = Card + Finger
6 = Any
12 = Finger then Card
No
To define the access mode
applicable for the external
reader.
reader-entry-exit-mode 0 = Entry
1 = Exit No
To define the whether the
external reader is to be set on an
entry or exit mode.
tag-re-detect-delay 00 - 3600 seconds No To define the tag re-detection
delay time.
format text,xml No Specifies the format in which the
response is expected.
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
Table: Reader Configuration Parameters
Argument Valid Values Mandatory Description
Matrix COSEC Devices API User Guide 20
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
security
0 = Normal
1 = Secure
2 = More Secure
Default = 0
Yes To define the security type
while enrollment.
lighting-cond
0 = Out door
1 = In door
Default =1
No To define the lighting condition.
sensitivity
0 = Level 1 (Low)
1 = Level 2
2 = Level 3
3 = Level 4
4 = Level 5
5 = Level 6
6 = Level 7
7 = Level 8 (High)
Default = 7
No To define the sensitivity levels
from low to high.
fast-mode
0 = Mode 1 (Normal)
1 = Mode 2
2 = Mode 3
3 = Mode 4
4 = Mode 5
5 = Mode 6 (Fastest)
6 = Auto
Default = 6
No
To define the mode to be used
during enrollment.
image-quality
0 = Weak
1 = Moderate
2 = Strong
3 = Strongest
Default = 1
No
To define the acceptable
image quality for enrollment.
format text,xml No Specifies the format in which
the response is expected
Matrix COSEC Devices API User Guide 21
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
security
0 = Normal
1 = Highest
2 = High
3 = Low
4 = Lowest
Default = 2
Yes To define the security type
while enrollment.
palm-matching-
timeout
0 to 9999 sec
Default = 15 sec
No To define the palm matching
timeout.
palm-temp-quality
0 = Good
1 = Moderate
2 = Poor
Default = 1
No To define the acceptable
image quality for enrollment.
format text,xml No Specifies the format in which
the response is expected
Matrix COSEC Devices API User Guide 22
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
enroll-on-device 0 = Inactive
1 = Active No To enable/disable the feature to enroll
through special function
enroll-using 0 = User ID
1 = Reference No. No
To define the option to enroll the credential
using the user’s Reference No. or User ID,
for enrollment through special function.
Note: This parameter will not be valid for
NGT Direct Door and Vega Controller
where enrollment must be performed by
User ID.
temp-per-finger
0 = Single Template/
Finger
1 = Dual Template/Finger
No To define the number of templates to be
saved per finger.
enroll-finger-count
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
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
No
No. of fingers allowed to be enrolled in one
enrollment cycle.
Note: For the action=set method, this
value should not be greater than the max-
finger value set in Basic Device
Configuration API.
Matrix COSEC Devices API User Guide 23
• 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.
enroll-palm-count
0 = 1 Palm
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
No
No. of palms allowed to be enrolled in one
enrollment cycle.
enroll-card-count
0 = 1 Card
1 = 2 Cards
2 = 3 Cards
3 = 4 Cards
No
No. of special function cards allowed to be
enrolled in one enrollment cycle.
enroll-mode
0 = Read Only Card
1 = Smart Card
2 = Finger Print
3 = FP then Card
4 = Palm Template
5 = Palm then Card
No To define the enrollment mode for
enrollment through device.
format text,xml No Specifies the format in which the response
is expected.
Table: Enrollment Configuration Parameters
Argument Valid Values Mandatory Description
Matrix COSEC Devices API User Guide 24
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:
Example
1. To get data for all parameters in the text format.
Table: Access Settings Configuration Parameters
Argument Valid Values Mandatory Description
week-day<0~6>
sun (0) to sat (6)
0 = Inactive
1 = Active
No
To define the active working days. This
parameter is repeated for each day of
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
format text, xml No Specifies the format in which the
response is expected
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
Matrix COSEC Devices API User Guide 25
Alarm Configuration
Description: To set or retrieve configuration parameters for enabling/disabling alarms and related functions on a
COSEC device such as Auto Alarm Acknowledgement.
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
alarm 0 = Inactive
1 = Active No To enable/disable alarm.
tamper-alarm 0 = Inactive
1 = Active No To enable or disable the feature.
auto-alarm-ack 0 = Inactive
1 = Active No To enable or disable the Auto Alarm
Acknowledgement feature.
format text,xml No Specifies the format in which the
response is expected.
Matrix COSEC Devices API User Guide 26
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
time-format 0 = 24 hours
1 = 12 hours No
Defines the time format to be
displayed on the device display.
Note: This is applicable only for the
time shown on the device display and
not for general date-time which will
always be in 24 hours format.
update-mode 0 = Auto
1 = Manual No Defines whether the update mode is
manual or through NTP Server.
ntp-server-type 0 = Predefined
1 = User Defined No
Defines whether the NTP server is a
predefined server or user-defined
server address.
time-zone
00-74 (Tool supported by
Windows), default: GMT
(+05:30) Chennai, Kolkata,
Mumbai, New Delhi.
Refer to “Table: Universal
Time Zone Reference” on
page 61
No To define the universal time zone.
ntp-server
0 = ntp1.cs.wisc.edu
1 = time.windows.com
2 = time.nist.gov
No To define the NTP Address.
user-defined-ntp Alphanumeric, Max. 40
characters. No To define the user-defined NTP.
dst-enable 0 = Disable
1 = Enable No To enable/disable DST.
Matrix COSEC Devices API User Guide 27
fwd-month
0 = January
1 = February
2 = March
3 = April
4 = May
5 = June
6 = July
7 = August
8 = September
9 = October
10 = November
11 = December No Forward clock day
fwd-week
0 = 1st
1 = 2nd
2 = 3rd
3 = 4th
4 = Last
fwd-day
0 = Sunday
1 = Monday
2 = Tuesday
3 = Wednesday
4 = Thursday
5 = Friday
6 = Saturday
fwd-time-hh 00 - 23 (24 hours format
only) No Forward clock time instance
fwd-time-mm 00 - 59
rev-month
0 = January
1 = February
2 = March
3 = April
4 = May
5 = June
6 = July
7 = August
8 = September
9 = October
10 = November
11 = December
No
Reverse clock day
rev-week
0 = 1st
1 = 2nd
2 = 3rd
3 = 4th
4 = Last
No
Table: Date and Time Configuration Parameters
Argument Valid Values Mandatory Description
Matrix COSEC Devices API User Guide 28
• 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.
rev-day
0 = Sunday
1 = Monday
2 = Tuesday
3 = Wednesday
4 = Thursday
5 = Friday
6 = Saturday
No Reverse clock day
rev-time-hh 00 - 23 (24 hours format
only) No Reverse clock time instance
rev-time-mm 00 - 59
duration-hh 00 - 23 (24 hours format
only) No
Time by which clock should be
forwarded or reversed.
duration-mm 00 - 59
format text,xml No Specifies the format in which the
response is expected.
Table: Date and Time Configuration Parameters
Argument Valid Values Mandatory Description
Matrix COSEC Devices API User Guide 29
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
allow-exit-when-locked 0 = Inactive
1 = Active No To allow exit when door is locked.
auto-relock 0 = Inactive
1 = Active No To enable/disable the Auto-relock
feature.
asc-active 0 = Inactive
1 = Active No To enable/disable the Additional
Security Code (ASC).
buzzer-mute 0 = Unmute
1 = Mute No To mute/un-mute the buzzer.
door-sense-active 0 = Inactive
1 = Active No To enable/disable sensing of door
states.
door-sense 0 = NO
1 = NC No
To define the normal door state as
as normally open (NO) or normally
closed (NC).
supervised 0 = Unsupervised
1 = Supervised No
To enable/disable supervised
sensing of door states (four-state
monitoring of door controllers).
exit-switch 0 = Inactive
1 = Active No To enable/disable the exit switch.
greeting-msg-enable 0 = Inactive
1 = Active No To enable/disable the display
greeting message.
greeting-msg<1~4> Alphanumeric, Max. 21
ASCII characters No
To define upto 4 display greeting
messages, the start time and the
end time for displaying each
message.
greeting-start-time-
hh<1~4> 00-23 No
greeting-start-time-
mm<1~4> 00-59 No
greeting-end-time-
hh<1~4> 00-23 No
greeting-end-time-
mm<1~4> 00-59 No
voice-guidance 0 = Inactive
1 = Active No To enable/disable Voice Guidance
(Only for NGT doors).
Matrix COSEC Devices API User Guide 30
• 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.
format text,xml No Specifies the format in which the
response is expected.
Table: Door Features Configuration Parameters
Argument Valid Values Mandatory Description
Matrix COSEC Devices API User Guide 31
System Timers Configuration
Description: To set or retrieve configurations for the following system timers:
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:
Auto Alarm Acknowledgement 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.
Table: System Timers Configuration Parameters
Argument Valid Values Mandatory Description
alarm-ack-timer 10 to 65535 (sec) No To define the timer for Auto Alarm
Acknowledgement.
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
sp-function-timer 1-99 (mins) No To define the Special Function Timer.
format text,xml No Specifies the format in which the
response is expected.
Matrix COSEC Devices API User Guide 32
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
2 = Official Work - OUT
3 = Short Leave - IN
4 = Short Leave - OUT
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
Yes The index number of a special function.
enable 0 = Disable
1 = Enable
No To enable/disable special functions on
the device.
card1 64 Bits (20 Numeric Digits
approx.)
No To define the special function card 1.
card2 64 Bits (20 Numeric Digits
approx.)
No To define the special function card 2.
card3 64 Bits (20 Numeric Digits
approx.)
No To define the special function card 3.
card4 64 Bits (20 Numeric Digits
approx.)
No To define the special function card 4.
format text,xml No Specifies the format in which the
response is expected.
Matrix COSEC Devices API User Guide 33
User Configuration
The various COSEC devices have capacity to support the following number of users:
• Direct Door V2 :2000
• NGT Direct Door :10,000
• Wireless Door :50,000
• Path Controller :2000
• PVR Door :10,000
• Vega Controller :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 34
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
user-id Maximum 10 characters Yes
To set or retrieve the
alphanumeric user ID for the
selected user.
Note: If a set request is sent
against an existing user ID, then
configuration for this user will be
updated with the new values.
user-index
Direct Door V2= 1 - 2,000
Path Controller = 1 - 2,000
Wireless Door = 1 - 50,000
PVR = 1 - 10,000
NGT = 1 - 10,000
Vega Controller = 1 - 50,000
No
To identify the index number for
the selected user ID (only get
parameter)
ref-user-id Maximum 8 digits
Yes (Not
mandatory
for the get
action)
To select the numeric user ID on
which the specified operation is
to be done.
name Alphanumeric. Max. 15 characters No To define the user name
user-active 0 = Inactive
1 = Active No to activate or deactivate a user.
vip 0 = Inactive
1 = Active No
To define a user as VIP.
Note: A VIP user is a user with
the special privilege to access a
particular door.
validity-enable 0 = Inactive
1 = Active No To enable/disable the user
validity.
validity-date-dd 1-31 No
To define the end date for user
validity.
validity-date-mm 1-12 No
validity-date-yyyy 2000-2037 No
Matrix COSEC Devices API User Guide 35
•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.
user-pin 1 to 6 Digits No
To set the user PIN or get the
event from user PIN.
Note: The user-pin can be set to
a blank value.
by-pass-finger 0 = Inactive
1 = Active No To enable/disable the bypass
finger option.
by-pass-palm 0 = Inactive
1 = Active No To enable/disable the bypass
palm option.
card1 64 Bits (8 bytes) (max value -
18446744073709551615) No To set or delete the card value
against a user.
card2 64 Bits (8 bytes) (max value -
18446744073709551615) No To set or delete the card value
against a user.
dob-enable 0 = Enable
1 = Disable No To enable/disable the display of a
birthday message.
dob-dd 1-31
No To set or delete the date of birth
for a user.
dob-mm 1-12
dob-yyyy 1990-2037
user-group 0-999 No
To set the user group number.
Note: A user can be assigned to
any user group ranging from 1 to
999. User group number can be
set/update via “Set” command. To
remove a user from an assigned
user group, user group should be
set to 0.
format text, xml No Specifies the format in which the
response is expected.
Table: User Configuration Parameters
Argument Valid Values Mandatory Description
Matrix COSEC Devices API User Guide 36
Example
1. To get user names for user-id = 1
Sample Request
http://deviceIP:deviceport/device.cgi/users?action=get&user-id=1&format=xml
Sample Response
HTTP Code: 200 OK
Content-Type: <xml>
Content-Length: <length>
Body:
<COSEC_API>
<user-id>1</user-id>
<user-index>0</user-index>
<ref-user-id></ref-user-id>
<name></name>
<user-active>0</user-active>
<vip>0</vip>
<validity-enable>0</validity-enable>
<validity-date-dd>1</validity-date-dd>
<validity-date-mm>1</validity-date-mm>
<validity-date-yyyy>2009</validity-date-yyyy>
<user-pin></user-pin>
<by-pass-finger>0</by-pass-finger>
<card1>0</card1>
<card2>0</card2>
</COSEC_API>
Matrix COSEC Devices API User Guide 37
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:
Example
Following are some test cases for your reference:
1. To add an image file in .jpeg format for user-id 1.
2. To fetch the user photo for the same user.
Table: Setting a User Photo - Parameters
Argument Valid Values Mandatory Description
user-id Maximum 10 characters Yes To specify the alphanumeric user ID
for the user whose photo is to be set.
user-photo N/A Yes
To get, set or delete the user photo.
This should be done in the data
portion of the request /
response.(applicable only for VEGA
and NGT doors)
photo-format
0 = jpeg
1 = jpg
2 = png
3 = bmp
Yes (only for set
parameter)
To define the format for the
photograph.
format text,xml No Specifies the format in which the
response is expected.
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
Sample Request
http://<deviceIP:deviceport>/device.cgi/userphoto?action=get&user-id=1
Matrix COSEC Devices API User Guide 38
This is an example only. The actual response will vary depending on product model and configuration.
Sample Response
HTTP Code: 200 OK
Content-Type: image/jpeg
Content-Length: 12345
Body:
<JPEG Image Data>
Matrix COSEC Devices API User Guide 39
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 10 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.
Matrix COSEC Devices API User Guide 40
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
type
1 = Finger
2 = Card
3 = Palm
Yes To define the user credentials
type.
user-id Alphanumeric (Max 10 characters) Yes To select the user-id for which the
credential is to be fetched.
card1 64 Bits (8 bytes) (max value -
18446744073709551615) No It defines the value for card-1
card2 64 Bits (8 bytes) (max value -
18446744073709551615) No It defines the value for card-2
format text,xml No Specifies the format in which the
response is expected.
data - No
This is the data of respective
credential type, which is to be
stored at given index number for
the respective user id.
Matrix COSEC Devices API User Guide 41
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
type
1 = Finger
2 = Card
3 = Palm
Yes To define the user credentials
type.
user-id Alphanumeric (Max. 10 characters Yes To select the user-id for which the
credential is to be fetched.
card1 64 Bits (8 bytes) (max value -
18446744073709551615) It defines the value for card-1
card2 64 Bits (8 bytes) (max value -
18446744073709551615) It defines the value for card-2
finger-index
1 = 1 Finger
2 = 2 Fingers
3 = 3 Fingers
4 = 4 Fingers
5 = 5 Fingers
6 = 6 Fingers
7 = 7 Fingers
8 = 8 Fingers
9 = 9 Fingers
10 = 10 Fingers
No
Identifies the number of finger
templates/palm templates to be
set or retrieved, on or from the
device. The template will be set
and retrieved from the data
portion of the request and
response.
palm-index
1 = 1 Palm
2 = 2 Palms
3 = 3 Palms
4 = 4 Palms
5 = 5 Palms
6 = 6 Palms
7 = 7 Palms
8 = 8 Palms
9 = 9 Palms
10 = 10 Palms
No
format text,xml No Specifies the format in which the
response is expected.
data - No
This is the data of respective
credential type, which is to be
stored at given index number for
the respective user id.
Matrix COSEC Devices API User Guide 42
• 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.
• 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.
Matrix COSEC Devices API User Guide 43
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:
Example
1. To delete finger templates of user id 1.
Table: Deleting User Credentials - Parameters
Argument Valid Values Mandatory Description
user-id Alphanumeric (Max. 10 characters) Yes To delete the credential of a
particular user.
type 0 = All
1 = Finger
2 = Card
3 = Palm
Yes Defines the credential type to be
deleted.
Note: For the selected type, all
credentials will be deleted.
format text,xml No Specifies the format in which the
response is expected.
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 44
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
Matrix COSEC Devices API User Guide 45
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
1 = Smart Card
2 = Finger Print
3 = FP Then Card
4 = Palm Template
5 = Palm Then Card
Yes Defines the credential to be
enrolled.
user-id Maximum 10 characters Yes Defines the alphanumeric User ID
of the user whose credential is to
be enrolled.
finger-count 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
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
No To specify the number of fingers to
be enrolled.
card-count 0 = 1 Card
1 = 2 Cards
2 = 3 Cards
3 = 4 Cards
No To specify the number of cards to
be enrolled.
Matrix COSEC Devices API User Guide 46
palm-count 0 = 1 Palm
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
No To specify the number of palms to
be enrolled.
w-asc 0 = Inactive
1 = Active
No To enable/disable the Additional
Security Code (ASC) to be written
on the Smart Card.
w-fc 0 = Inactive
1 = Active
No To enable/disable the Facility Code
(FC) to be written on the Smart
Card.
w-ref-user-id 0 = Inactive
1 = Active
No To enable/disable the User ID to be
written on the Smart Card.
w-name 0 = Inactive
1 = Active
No To enable/disable the User Name to
be written on the Smart Card.
w-designation 0 = Inactive
1 = Active
No To enable/disable the designation
to be written on the Smart Card.
w-branch 0 = Inactive
1 = Active
No To enable/disable the branch name
to be written on the Smart Card.
w-department 0 = Inactive
1 = Active
No To enable/disable the department
name to be written on the Smart
Card.
w-bg 0 = Inactive
1 = Active
No To enable/disable the blood group
to be written on the Smart Card.
w-contact 0 = Inactive
1 = Active
No To enable/disable Emergency
Contact information to be written on
the Smart Card.
w-medical-history 0 = Inactive
1 = Active
No To enable/disable the medical
history to be written on the Smart
Card.
w-fp-template 0 = No Templates
1 = 1 Finger Template
2 = 2 Finger Templates
No To enable/disable the finger
templates to be written on the
Smart Card.
name Alphanumeric, 15 Chars, ASCII
Code
No Defines the values for the
respective fields to be written on the
Smart Card.
designation
branch
department
Table: Enrolling User - Parameters
Argument Valid Values Mandatory Description
Matrix COSEC Devices API User Guide 47
• 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.
bg Maximum 4 characters. Valid
Values:
A+
A-
B+
B-
AB+
AB-
O+
O-
A1-
A1+
A1B-
A1B+
A2-
A2+
A2B-
A2B+
B1+
No Defines the values for the
respective fields to be written on the
Smart Card.
Note: ‘bg’ stands for blood group of
the user.
contact Alphanumeric, 15 Chars, ASCII
Code
No
medical-history Alphanumeric, 15 Chars, ASCII
Code
No
format text,xml No Specifies the format in which the
response is expected.
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
Table: Enrolling User - Parameters
Argument Valid Values Mandatory Description
Matrix COSEC Devices API User Guide 48
Enrolling Special Cards
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
(special function ID)
Yes Defines the special function
identification number.
card-count 0 = 1 Card
1 = 2 Cards
2 = 3 Cards
3 = 4 Cards
No To specify the number of cards to be
enrolled.
format text,xml No Specifies the format in which the
response is expected.
Matrix COSEC Devices API User Guide 49
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 50
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:
•For different kind of events, different fields are required, to understand the functionality of an event,
which are denoted as detail fields.
• The details field in the response depends on the type of device.
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.
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
events sent in this response. If the
“no-of-events” field value is 1, then
this will be the only event sent to the
server.
seq-number Refer to “Table: Value Range for
Event Sequence Numbers” for the
valid values on different devices.
Yes
no-of-events 1 to 5 (for Direct Door V2 and Path
Controller)
1 to 100 ( for all other Direct Doors)
No Specifies the number of events to be
fetched.
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
Sample Request
http://deviceIP:deviceport/device.cgi/events?action=getevent&roll-over-count=0&seq-number=1&no-of-events=3
Matrix COSEC Devices API User Guide 51
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
• 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.
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>
Matrix COSEC Devices API User Guide 52
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:
Due to memory constraints, this API is not supported on Direct Door V2.
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.
Table: Retrieving Events in the TCP Socket - Parameters
Argument Valid Values Mandatory Description
ipaddress IP address and port number
validations are same as for network
configuration settings.
Yes Defines the IP Address and the
listening port on which the events
are to be sent.
port
roll-over-count 0 to 65535 Yes It is used to specify the exact
sequence number of an event stored
at any port.
seq-number Refer to “Table: Value Range for
Event Sequence Numbers” for the
valid values on different devices.
Yes It is used to specify the sequence
number of any event. The maximum
value for this can be from 1 to the
event log capacity of that device.
response-time 3 - 15 seconds No To specify the response time to wait
for a confirmation of established
network.
interface 0 = Ethernet
1 = Wi-Fi
2 = Mobile Broadband
No Specifies the interface.
Note: If no interface is defined,
Ethernet will be tried by default.
format text,xml No Specifies the format in which the
response is expected.
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
Matrix COSEC Devices API User Guide 53
• The default TCP protocol acknowledgement 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 (upto 5,00,000 events).
Sample Response
HTTP Code: 200 OK
Content-Type: <type>
Content-Length: <length>
Body: Response-Code=0
Matrix COSEC Devices API User Guide 54
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>
For action=getcount
For valid values of this method, refer to the following argument-value table.
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.
2Get Credential Count for
Enrolled Credentials getcount
To get the count of already enrolled
templates and credentials for a user on
the selected device.
3 Acknowledge Alarm acknoledgealarm To command the device to acknowledge
an alarm without clearing it.
4 Lock Door lockdoor To command the door to return to a
locked state.
5 Unlock Door unlockdoor To command the door to return to an
unlocked state.
6 Normalize Door normalizedoor To command the door to return to a
normal state.
7 Get User Count on Device getusercount To obtain the total number of users
added on a device.
8Get Current Event Sequence
Number geteventcount To get the current event sequence
number and roll over count in a device.
9Default the System
Configuration systemdefault To set all the configurations on the
device to default status.
10 Delete Credentials for All Users deletecredential To delete all biometric credentials of
users from device.
Table: Get Credential Count Command - Parameters
Argument Valid Values Mandatory Description
user-id 1 to max. User ID in the door
(2 bytes)
Yes Defines the numeric ID of the user
whose data is to be fetched.
card-count 0 = 1 Card
1 = 2 Cards
2 = 3 Cards
3 = 4 Cards
No To get the number of cards enrolled.
Matrix COSEC Devices API User Guide 55
• 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.
finger-count Single Template/Finger: 0-9
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
No To get the number of fingers
enrolled.
palm-count 0 = 1 Palm
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
No To get the number of palms enrolled.
format text,xml No Specifies the format in which the
response is expected.
Table: Get Credential Count Command - Parameters
Argument Valid Values Mandatory Description
Matrix COSEC Devices API User Guide 56
For action=deletecredential
For valid values of this method, refer to the following argument-value table.
Example
Following are some test cases for your reference:
1. To get the current rollover count and sequence number of events in the device.
Table: Deleting Credentials for All Users - Parameters
Argument Valid Values Mandatory Description
type 0 = All
1 = Finger
2 = Palm
Yes To specify the type of credential to
be deleted.
Sample Request
http://<deviceIP:deviceport>/device.cgi/command?action=geteventcount&format=xml
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 >
Matrix COSEC Devices API User Guide 57
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.
• Invalid value is assigned to argument in request.
•Syntax of request is incorrect or any unexpected arguments are received.
•Mandatory fields are not mentioned in request.
Sample Response
HTTP code: <code>
Content-type: <type>
Body:
Request failed: Incomplete command “<argument>=”
Sample Response
HTTP code: <code>
Content-type: <type>
Body:
Request failed: Invalid command “<argument>=<invalid value>”
Sample Response
HTTP code: <code>
Content-type: <type>
Body:
Request failed: Invalid syntax “<entire request>”
Sample Response
HTTP code: <code>
Content-type: <type>
Body:
Request failed: Incomplete command “<entire request>”
Matrix COSEC Devices API User Guide 58
• 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 59
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 -
1Failed - Invalid Login
Credentials On every Authentication/Verification while logging In
2Date and time – manual set
failed If unable to set the RTC for date and time API
3 Invalid Date/Time In User API, if validity-date or date of birth is set wrong.
If the starting time and end time of a shift is configured as same.
4Maximum users are already
configured. On every set command for user API
5 Image – size is too big On every set command for user API
6Image – format not
supported On every set command for user API
7Card 1 and card 2 are
identical On every set command for user API and set credential API
8 Card ID exists On every set command for user API and set credential API, Set
Special Function API
9Finger print template/ Palm
template already exists Set credential API
10 No Record Found Event sequence number and roll over count not found, user id not
found in Set User API
11 Template size/ format
mismatch
If the expected template size is not as per the required size, format or
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.
13 User id not found
In enroll user command if user id is not available in the device and in
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.
15 Reader mismatch/ Reader
not configured
The enroll request is for smart card and the device has proximity
reader or if enroll request has palm template but door has finger reader
and similar cases.
16 Device Busy All cases of enrollment when the device is unable to process a request
as it is in a different menu state
17 Internal process error Internal error like configuration, firmware or event or calibration failure
occur
18 PIN already exists Set User API: PIN is already assigned to another user
19 Biometric credential not
found
In enroll user smart card, write FP is enabled, but FP is not enrolled,
Get FP/Palm template command is sent but template is not present.
20 Memory Card Not Found In case memory card is not connected, and a command related to
getting an image (user photo) is sent.
Matrix COSEC Devices API User Guide 60
21 Reference User ID exists When an already existing User ID is entered against a user having
unique User ID.
22 Wrong Selection
For enrolling user, if writing FP template on smart card is enabled, but
no fingerprint is enrolled.
When palm/finger/card count exceeds the maximum number of
available places.
Table: API Response Codes
Response Code Description Test Condition
Matrix COSEC Devices API User Guide 61
Appendix
Table: Universal Time Zone Reference
Index=0
Index=1
Index=2
Index=3
Index=4
Index=5
Index=6
Index=7
Index=8
Index=9
Index=10
Index=11
Index=12
Index=13
Index=14
Index=15
Index=16
Index=17
Index=18
Index=19
Index=20
Index=21
Index=22
Index=23
Index=24
Index=25
Index=26
Index=27
Index=28
Index=29
Index=30
Index=31
Index=32
Index=33
Index=34
Index=35
Index=36
Index=37
Index=38
Index=39
Index=40
Index=41
Index=42
Index=43
Index=44
Index=45
Index=46
Index=47
Index=48
Index=49
Index=50
Index=51
Index=52
Index=53
Index=54
Index=55
Index=56
Index=57
Index=58
Index=59
Index=60
Text="(GMT-12:00) International Date Line West"
Text="(GMT-11:00) Midway Island, Samoa"
Text="(GMT-10:00) Hawaii"
Text="(GMT-09:00) Alaska"
Text="(GMT-08:00) Pacific Time (Us & Canada); Tijuana"
Text="(GMT-07:00) Arizona"
Text="(GMT-07:00) Chihuahua, La Paz, Mazatlan"
Text="(GMT-07:00) Mountain Time (Us & Canada)"
Text="(GMT-06:00) Ce ntral America"
Text="(GMT-06:00) Central Time (Us & Canada)"
Text="(GMT-06:00) Guadalajara, Mexico City, Monterrey"
Text="(GMT-06:00) Saskatchewan"
Text="(GMT-05:00) Bogota, Lima, Quito"
Text="(GMT-05:00) Eastern Time (Us & Canada)"
Text="(GMT-05:00) Indiana (East)"
Text="(GMT-04:00) Atlantic Time (Canada)"
Text="(GMT-04:00) Caracas, La Paz"
Text="(GMT-04:00) Santiago"
Text="(GMT-03:30) Newfoundland"
Text="(GMT-03:00) Brasilia"
Text="(GMT-03:00) Buenos-Aires, Georgetown"
Text="(GMT-03:00) Greenland"
Text="(GMT-02:00) Mid-Atlantic"
Text="(GMT-01:00) Azores"
Text="(GMT-01:00) Cape Verde Is"
Text="(GMT) CASABLANCA, MONROVIA"
Text="(GMT) Dublin, Edinburgh, Lisbon, London"
Text="(GMT+01:00) Amsterdam, Berlin, Bern, Rome, Stockholm, Vienna"
Text="(GMT+01:00) Belgrade, Bratislava, Budapest, Ljubljana, Prague"
Text="(GMT+01:00) Brussels, Copenhagen, Madrid, Paris"
Text="(GMT+01:00) Sarajevo, Skopje, Warsaw, Zagreb"
Text="(GMT+01:00) West Central Africa"
Text="(GMT+02:00) Athens, Beirut, Istanbul, Minsk"
Text="(GMT+02:00) Bucharest"
Text="(GMT+02:00) Cairo"
Text="(GMT+02:00) Harare, Pretoria"
Text="(GMT+02:00) Helsinki, Kyiv, Riga, Sofia, Tallinn, Vilnius"
Text="(GMT+02:00) Jerusalem"
Text="(GMT+03:00) Baghdad"
Text="(GMT+03:00) Kuwait, Riyadh"
Text="(GMT+03:00) Moscow, St Petersburg, Volgograd"
Text="(GMT+03:00) Nairobi"
Text="(GMT+03:30) Tehran"
Text="(GMT+04:00) Abu Dhabi, Muscat"
Text="(GMT+04:00) Baku, Tbilisi, Yerevan"
Text="(GMT+04:30) Kabul"
Text="(GMT+05:00) Ekaterinburg"
Text="(GMT+05:00) Islamabad, Karachi, Tashkent"
Text="(GMT+05:30) Chennai, Kolkata, New Delhi, Mumbai"
Text="(GMT+05:45) Kathmandu"
Text="(GMT+06:00) Almay, Novosibirsk"
Text="(GMT+06:00) Astana, Dhaka"
Text="(GMT+06:00) Sri Jayewardenepura"
Text="(GMT+06:30) Rangoon"
Text="(GMT+07:00) Bangkok, Hanoi, Jakarta"
Text="(GMT+07:00) Krasnoyarsk"
Text="(GMT+08:00) Beijing, Chongqing, Hong Kong, Urumqi"
Text="(GMT+08:00) Irkutsk, Ulaanbataar"
Text="(GMT+08:00) Kuala Lumpur, Singapore"
Text="(GMT+08:00) Perth"
Text="(GMT+08:00) Taipei"
Matrix COSEC Devices API User Guide 62
Table: Universal Time Zone Reference
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
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
162 User Denied – Door Lock
Index=61
Index=62
Index=63
Index=64
Index=65
Index=66
Index=67
Index=68
Index=69
Index=70
Index=71
Index=72
Index=73
Index=74
Text="(GMT+09:00) Osaka, Sapporo, Tokyo"
Text="(GMT+11:00) Magadan, Solomon Is, New Caledonia"
Text="(GMT+12:00) Auckland, Wellington"
Text="(GMT+12:00) Fiji, Kamchatka, Marshall Is"
Text="(GMT+13:00) Nuku'alofa"
Text="(GMT+09:00) Seoul"
Text="(GMT+09:00) Yakutsk"
Text="(GMT+09:30) Adelaide"
Text="(GMT+09:30) Darwin"
Text="(GMT+10:00) Brisbane"
Text="(GMT+10:00) Canberra, Sydney, Melbourne,"
Text="(GMT+10:00) Guam, Port Moresby"
Text="(GMT+10:00) Hobart"
Text="(GMT+10:00) Vladivostok"
Matrix COSEC Devices API User Guide 63
163 User Denied – Invalid Access Group
164 User Denied – Validity date expired
165 User Denied – Invalid Route Access
166 User Denied – Invalid Shift Access
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
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
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
Table: List of Events
Event ID Event Description
Matrix COSEC Devices API User Guide 64
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.
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
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
Table: User Events
Event Details Applicable Devices
Event ID
(Field 1)
User ID
(Field 2)
Special
Code
(Field 3)
Entry/Exit
(Field 4) (Field 5)
Direct
Door V2
Path
Controller
Wireless
Door
NGT
Door
PVR
Door
Vega
Controller
User Allowed Events
Table: List of Events
Event ID Event Description
Matrix COSEC Devices API User Guide 65
101
Xxxx
(user ID=0 for
REX input)
Special
Function
code
Detail 0 0  
102 Xxxx
Special
Function
code
Detail 0 0 
103 Xxxx
Special
Function
code
Detail 0 0  
104 Xxxx
Special
Function
code
Detail 0 0  
105 Xxxx
Special
Function
code
Detail 0 0  
106 Xxxx
Special
Function
code
Detail 0 0  
107 Xxxx
Special
Function
code
Detail 0 0  
108 Xxxx
Special
Function
code
Detail 0 0  
109 Xxxx
Special
Function
code
Detail 0 0  
110 Xxxx
Special
Function
code
Detail 0 0  
User Denied Events
151 (User ID = 0 if
not identified)
Special
Function
code Detail 0 0  
152 Xxxx 0 Detail 0 0  
153 Xxxx 0 Detail 0 0  
154 Xxxx 0 Detail 0 0  
155 Xxxx 0 Detail 0 0  
156 Xxxx 0 Detail 0 0  
157 Xxxx 0 Detail 0 0  
158 Xxxx 0 Detail 0 0  
159 Xxxx 0 Detail 0 0  
160 Xxxx 0 Detail 0 0  
161 Xxxx 0 Detail 0 0  
162 Xxxx 0 Detail 0 0  
163 Xxxx 0 Detail 0 0  
164 Xxxx 0 Detail  
Table: User Events
Event Details Applicable Devices
Event ID
(Field 1)
User ID
(Field 2)
Special
Code
(Field 3)
Entry/Exit
(Field 4) (Field 5)
Direct
Door V2
Path
Controller
Wireless
Door
NGT
Door
PVR
Door
Vega
Controller
Matrix COSEC Devices API User Guide 66
165 Xxxx
0=Door Not
in Sequence
1=Door Not
in Route
Detail 0 0
 
2=Door Not
in Sequence
for Smart
card based
Route
3=Door Not
in Smart
card based
Route
4=Credentia
l Invalid for
Smart card
based
Route
Access
 
166 Xxxx
0=Outside
working
hours
1=Holiday
Detail 0 0
 
2=Week off
3=Field
Break
4=Rest Day
 
Table: Special Function Codes Reference
S.No. Special Function Name Special Function Code Applicable for Allowed
Events
Applicable for Denied
Events
1Official Work-IN Marking in
T&A 1
2Official Work-OUT Marking
in T&A 2
3Short Leave-IN Marking in
T&A 3
4Short Leave-OUT Marking
in T&A 4
5 Clock - IN Marking in T&A 5
6Clock - OUT Marking in
T&A 6
7Post Lunch-IN Marking in
T&A 7
Table: User Events
Event Details Applicable Devices
Event ID
(Field 1)
User ID
(Field 2)
Special
Code
(Field 3)
Entry/Exit
(Field 4) (Field 5)
Direct
Door V2
Path
Controller
Wireless
Door
NGT
Door
PVR
Door
Vega
Controller
Matrix COSEC Devices API User Guide 67
8Pre Lunch -OUT Marking
in T&A 8
9Over time – IN Marking in
T&A 9
10 Over time – OUT Marking
in T&A 10
11 Late –IN Allowed Marking
in T&A 11
12 Early - OUT Allowed
Marking in T&A 12
13 Access in Degrade Mode
Marking 99 
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
RFU Group Palm Finger Card PIN RFU RFU Entry/
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 8
Credential Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Value
PIN 000011
Card 000102
Card + PIN 000113
Finger 001004
Table: Special Function Codes Reference
S.No. Special Function Name Special Function Code Applicable for Allowed
Events
Applicable for Denied
Events
Matrix COSEC Devices API User Guide 68
Finger + PIN 001015
Finger + Card 001106
Finger + Card + PIN 001117
Finger + Card 001106
Finger + Card + PIN 001117
Finger + Card 001106
Finger + Card + PIN 001117
Palm 010008
PIN + Palm 010019
Card + Palm 0101010
PIN + Card + Palm0101111
Group + Palm 1100024
Table: Door Events
Event Details Applicable Devices
Event ID
(Field 1)
Status
(Field 2) (Field 3) (Field 4) (Field 5)
Direct
Door V2
Path
Controller
Wireless
Door
NGT
Door
PVR
Door
Vega
Controller
201
1= Normal
2= Locked
3= Unlocked
0000
 
202 4= Activated
5= Deactivated 0000
 
203 4= Activated
5= Deactivated 0000
 
204
4= Activated
1= Normal
6= Fault (open)
7= Fault (short)
11= Disabled
0000
 
205
4= Activated
1= Normal
11= Disabled
0000
 
206
1= Normal
6= Fault (open)
7= Fault (short)
11= Disabled
0000
 
207 0 0 1= ON Line
0= OFF Line 00  
Table: Information of Bit 4 and Bit 8
Credential Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Value
Matrix COSEC Devices API User Guide 69
Table: Alarm Events
Event Details Applicable Devices
Event ID (Field 1) (Field 2) (Field 3) (Field
4)
(Field
5)
Direct
Door V2
Path
Controller
Wireless
Door
NGT
Door
PVR
Door
Vega
Controller
301 User ID Xxxx 1 = Critical
Alarm
Seque-
nce
Number
00  
302 User ID Xxxx 1 = Critical Same as
above 00  
303 User ID Xxxx 1 = Critical Same as
above 00  
304 1= Internal
2= External 3 = Minor Same as
above 00  
305 0 3 = Minor Same as
above 00  
306 0 2 = Major Same as
above 00  
307 0 1 = Critical Same as
above 00  
308 0 2 = Major Same as
above 00  
309 0 2 = Major Same as
above 00  
310 0 1 = Critical Same as
above 00  
311 0 2 = Major Same as
above 00  
312 0 1 = Critical Same as
above 00  
313 0 1 = Critical Same as
above 00  
314
1= Power ON/
OFF Detected
(time not in
sync)
2= low battery
detected
3= RTC Not
Detected
2 = Major
1 = Critical Same as
above 00  
315 0 2 = Major
1 = Critical
Same as
above 00  
351 0
4 = SysInterlock
5 = User_Jeeves
6 = User_ACMS
9 = Auto
Same as
above 00  
352 0
4 = SysInterlock
5 = User_Jeeves
6 = User_ACMS
7= Special
Function
Same as
above 00  
353 0 0 Same as
above 00  
Matrix COSEC Devices API User Guide 70
Table: System Events
Event Details Applicable Devices
Event
ID (Field 1) (Field 2) (Field 3) (Field
4)
(Field
5)
Direct
Door V2
Path
Controller
Wireless
Door
NGT
Door
PVR
Door
Vega
Controller
401 User ID:
xxxx
0= Unused
(Restore User)
1=Absentee Rule
2=Unauthorized
access
3=Usage count
4=Invalid PIN
1= Blocked
0= Restored
00  
402 0
5= SA
6= SE
7= Operator
1=Success
0=Fail 00  
403 Transaction
ID: Xxxx 0
1=Success
0=Fail 0 0  
404
Guard Tour
no. Xxxx +
cycle no.
01=Success
0=Fail 00  
405 ID: Xxxx
8 = User Card
9 = User Finger
10 = Special
Cards
14 = Palm
1= Card/FP/
Palm-1
2= Card/FP/
Palm-2
3 = Card-3
4 = Card-4
00  
406 0 0
1=Normal
2=Fault (Open)
3= Fault(Short)
4= Activated
00  
407 0 0 1=Normal
4=Activated 00  
408 I/O Link ID
11 = Pulse
12 = Interlock
13 = Latch
15 = Toggle
(only with
activated event)
1=Normal
4=Activated 00  
409 ID: Xxxx
8 = User Cards
9 = User Fingers
14 = Palm
5= Web Jeeves
6= ACMS
7= Special
Function
00  
410
Time
Triggered
Function Id
0
1=Normal/
Deactivated
4=Activated
00  
411
Time
Stamping
Function ID
0
1=Normal/
Deactivated
4=Activated
00  
412
Guard tour
no. +cycle
no.
Door Controller
sequence no.
1=Success
0=Fail 00  
413
event
sequence
number
roll over count 1=Success
0=Fail 00  
451
Configur-
ation Table
ID xxx
Index start Index end 0 0  
Matrix COSEC Devices API User Guide 71
452
Roll over
number
00 to 99
0000
 
453 0 0 0 0 0  
454
Configur-
ation Table
ID xxx
Index start Index end 0 0  
455
Time Period
= xxx
(configured
value)
(this field is
used only
with
Overridden
events)
Resume
events will
have blank
1= 2-person Rule
2= Access
Policies
3= Alarms
4= Anti-pass
back
5= First In User
6= Mantrap
7= Occupancy
control
8= Visitor Escort
Rule
1= Overridden
0= Resumed 00  
456 1=Backup
2=Update
1=Configuration
2=Event
3=Firmware
0 = Fai l
1 = S u c c e s s
2 = CRC Check
Fail
00  
457 0 0
6 = from ACMS
8 = from
Hardware
00  
458 0
0 = Internal
Finger Reader
1 = External
Finger Reader
0 = Fail
1 = Success
2 = Not
Supported
00  
Table: System Events
Event Details Applicable Devices
Event
ID (Field 1) (Field 2) (Field 3) (Field
4)
(Field
5)
Direct
Door V2
Path
Controller
Wireless
Door
NGT
Door
PVR
Door
Vega
Controller
MATRIX COMSEC PVT. LTD.
Corporate Office:
394-GIDC, Makarpura, Vadodara - 390010, India.
Ph.:+91 265 2630555, Fax: +91 265 2636598
E-mail: Info@MatrixComSec.com
Manufacturing Unit:
15 & 19 GIDC, Waghodia - 391760, Dist. Vadodara, India.
Ph.: +91 2668 263172/73
Customer Care:
Ph.: +91 265 2630555
E-mail: Customer.Care@MatrixComSec.com, Support@MatrixComSec.com
www.MatrixComSec.com
SECURITY SOLUTIONS

Navigation menu