COSEC Web API

User Guide

SECURITY SOLUTI ONS

 SECURITY SOLUTIONS

COSEC Web API 1.0

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

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

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

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

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

Version 1.0
Release date: June 2, 2014
 Contents

List of Tables ................................................................................................................................................. iii

About the Document ...................................................................................................................................... 1

Document Conventions ....................................................................................................................................... 1
Document Organization ...................................................................................................................................... 2
Who Can Use this Document .............................................................................................................................. 2

API Overview................................................................................................................................................... 3
How It Works ....................................................................................................................................................... 3
General Features ................................................................................................................................................ 3
What the User Should Know ............................................................................................................................... 4
Prerequisite ......................................................................................................................................................... 4
Enabling API Access ........................................................................................................................................... 4
HTTP Request-Response .................................................................................................................................. 5
Communication Flow ...................................................................................................................................................................... 5
Request Format .............................................................................................................................................................................. 6
Response Format ........................................................................................................................................................................... 7
URL Syntax ..................................................................................................................................................................................... 8
Specifying the Format ..................................................................................................................................................................... 9
Getting a List of Supported Fields ................................................................................................................................................. 10
Additional Information ................................................................................................................................................................... 11
Supported APIs ................................................................................................................................................. 12

Devices .......................................................................................................................................................... 14
Getting a Device List ......................................................................................................................................... 15
Assigning Users to Device ................................................................................................................................ 17
Revoking Users from Device ............................................................................................................................. 19
Adding a New Device ........................................................................................................................................ 21
Deleting a Device .............................................................................................................................................. 24
Obtaining Device Status .................................................................................................................................... 25
Updating Device Configuration ......................................................................................................................... 26

Sites ............................................................................................................................................................... 27
Obtaining Data on Existing Sites ....................................................................................................................... 28

Users ............................................................................................................................................................. 29
Accessing User Data ......................................................................................................................................... 30
Adding/Editing a User ....................................................................................................................................... 34
Adding User Photograph ................................................................................................................................... 42
Deleting a User ................................................................................................................................................. 44
Enrolling a User ................................................................................................................................................. 45
Setting Credentials on Device ........................................................................................................................... 47
Deleting Credentials from Device ...................................................................................................................... 48

Enterprise Structure ..................................................................................................................................... 49

Obtaining Enterprise Group Details .................................................................................................................. 51
Obtaining List of Renamed Groups ................................................................................................................... 52

Time and Attendance ................................................................................................................................... 53

Getting Daily Attendance Data .......................................................................................................................... 54
Getting Monthly Attendance Data ..................................................................................................................... 62
Access Control ............................................................................................................................................. 67
Obtaining List of Access Routes ....................................................................................................................... 68
Obtaining Access Route Details ........................................................................................................................ 70

Data Import and Export ............................................................................................................................... 72

Getting Export Template List ............................................................................................................................. 73
Getting Export Template Details ....................................................................................................................... 75
Getting Import Template List ............................................................................................................................. 76
Getting Import Template Details ....................................................................................................................... 77
Getting Template Data ...................................................................................................................................... 78

Data Transfer ................................................................................................................................................. 81

Retrieving User Data ......................................................................................................................................... 82
Sending User Data ............................................................................................................................................ 83

Events ............................................................................................................................................................ 84
Adding an Event ................................................................................................................................................ 85
Obtaining Time and Attendance Events ............................................................................................................ 87
Obtaining Time and Attendance Events by Date .............................................................................................. 90
Obtaining Access Control Events ...................................................................................................................... 93
Obtaining Access Control Events by Date ........................................................................................................ 96
Obtaining Door/Alarm/System Events ............................................................................................................... 99

Sending Commands to Device .................................................................................................................. 103

User Count on Device ................................................................................................................................ 106

Error Responses......................................................................................................................................... 108

 List of Tables
Table: URL Structure .......................................................................................................................................8
Table: Getting a Device List - Parameters .....................................................................................................15
Table: Getting a Device List - Response fields ..............................................................................................15
Table: Assigning Users to Device - Parameters ............................................................................................17
Table: Adding a New Device - Parameters ....................................................................................................21
Table: Deleting a Device - Parameters ..........................................................................................................24
Table: Obtaining Device Status - Parameters ...............................................................................................25
Table: Obtaining Data on Existing Sites - Response Fields ..........................................................................28
Table: Accessing User Data - Parameters ....................................................................................................30
Table: Accessing User Data - Response Fields ............................................................................................30
Table: Adding/Editing a User - Parameters ...................................................................................................34
Table: Adding User Photograph - Parameters ...............................................................................................42
Table: Deleting a User - Parameters .............................................................................................................44
Table: Enrolling a User - Parameters ............................................................................................................45
Table: Setting Credentials on Device - Parameters .......................................................................................47
Table: Deleting Credentials from Device - Parameters .................................................................................48
Table: Obtaining Enterprise Group Details - Parameters ..............................................................................51
Table: Obtaining Enterprise Group Details - Response Fields ......................................................................51
Table: Obtaining List of Renamed Groups - Response Fields ......................................................................52
Table: Getting Daily Attendance Data - Parameters ......................................................................................54
Table: Getting Daily Attendance Data - Response Fields .............................................................................54
Table: Getting Monthly Attendance Data - Parameters .................................................................................62
Table: Getting Monthly Attendance Data - Response Fields .........................................................................63
Table: Obtaining List of Access Routes - Parameters ...................................................................................68
Table: Obtaining List of Access Routes (Smart card) - Response Fields ......................................................68
Table: Obtaining List of Access Routes (Panel) - Response Fields ..............................................................68
Table: Obtaining Access Route Details - Parameters ...................................................................................70
Table: Obtaining Access Route Details (Smart card) - Response Fields ......................................................70
Table: Obtaining Access Route Details (Panel) - Response Fields ...............................................................70
Table: Getting Export Template List - Parameters ........................................................................................73
Table: Getting Export Template List - Response Fields ................................................................................73
Table: Getting Export Template Details - Parameters ...................................................................................75
Table: Getting Export Template Details - Response Table ...........................................................................75
Table: Getting Import Template List - Response Fields ................................................................................ 76
Table: Getting Import Template Details - Parameters ...................................................................................77
Table: Getting Import Template Details - Response Fields ...........................................................................77
Table: Getting Template Data - Parameters ..................................................................................................78
Table: Getting Template Data - Response Fields ..........................................................................................79
Table: Retrieving User Data - Parameters .....................................................................................................82
Table: Sending User Data - Parameters ........................................................................................................83
Table: Adding an Event - Parameters ............................................................................................................85
Table: Obtaining Time and Attendance Events - Parameters .......................................................................87
Table: Obtaining Time and Attendance Events - Response Fields ...............................................................87
Table: Obtaining Time and Attendance Events by Date - Parameters ..........................................................90
Table: Obtaining Time and Attendance Events by Date - Response Fields ..................................................90
Table: Obtaining Access Control Events - Parameters .................................................................................93
Table: Obtaining Access Control Events - Response Fields .........................................................................93
Table: Obtaining Access Control Events by Date - Parameters ....................................................................96
Table: Obtaining Access Control Events by Date - Response Fields ............................................................96
Table: Obtaining Door/Alarm/System Events - Parameters ..........................................................................99
Table: Obtaining Door/Alarm/System Events - Response Fields ..................................................................99
Table: List of Events ....................................................................................................................................100
Table: Sending Commands to Device - Parameters ...................................................................................103
Table: User Count on Device - Parameters .................................................................................................106
CHAPTER 1 About the Document

Welcome to the COSEC Web API User Guide. This document will provide you a comprehensive overview and
complete user-guidance for COSEC Web APIs. You can learn more about COSEC Web 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. Cross-references and other links will appear as follows: Document Conventions

For e.g. To learn more about APIs, please refer to section API Overview (or, See “API Overview” on
page 3.).

2. The term device used in this document, will refer to all COSEC Panels and COSEC Door Controllers.

3. Some abbreviations/acronyms/condensed forms commonly used in the document are expanded as

follows:

• ESS: Employee Self Service

• HTTP: Hypertext Transfer Protocol
• URL: Uniform Resource Locator
• XML: Extensible Markup Language
• JSON: JavaScript Object Notation
• IMEI: International Mobile Equipment Identity
• FTP: File Transfer Protocol
• T&A: Time and Attendance
• C-OFF: Compensatory Off

4. 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>”).

5. Arguments in a request URL, along with their corresponding values, will be separated by a ‘semi-colon’ (‘;’)
from other arguments. “?” will be allowed as a separator between the request-type and an argument.
Special characters (&, ‘, “, <, > and ;) will not be allowed for any arguments and its value.

6. 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.

Matrix COSEC Web API User Guide 1

 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.

Document Organization
Chapters 1 and 2 will provide a general understanding of COSEC APIs and the basic interface communication.
Chapters 3 to 13 provide a chapter-wise discussion of API groups with detailed explanation of individual APIs. The
following information has been provided on each request type:

• Description of the functionality.

• Actions used.
• Generic query syntax.
• Mandatory and optional parameters (argument-value table).
• Fields returned in response (“Response Fields”. Wherever applicable).
• Additional reference (if any).
• Examples (Sample Request and Sample Response).

Chapter 14 provides a description of API error responses.

For license requirement information, refer “Supported APIs” on page 12.

Who Can Use this Document

The COSEC Web API User Guide is meant for third-party software developers who wish to integrate the COSEC
Web application with another remote application. This guide will provide information to users on how to request and
receive services from the COSEC Web server via HTTP API.

Matrix COSEC Web API User Guide 2

CHAPTER 2 API Overview

COSEC enables third party developers to access some of its important functionality via APIs. Integrate your
application with COSEC and remotely execute functions such as retrieval of device, user and attendance data,
sending and updating configurations on the COSEC database, applying and approving applications, leave
management, cafeteria management and so on.

How It Works
A COSEC Web API is an interface that interacts with client applications, enabling them to invoke or push data from
and to the COSEC database, using the COSEC Web server. This can be processed by sending a simple HTTP
request to the COSEC server. The server then returns an appropriate response which the remote application can
subsequently process on its own, without the need to launch the COSEC Web application.

Consider an example where an organization (say, ABC) is using COSEC for time and attendance monitoring and
management. However, ABC has its independant Payroll application which requires the input of monthly
attendance data of all employees to process their salaries every month. In such a scenario, the application can be
integrated with COSEC via HTTP to raise a request for the relevant employee records in a specific format.

Thus, COSEC APIs are communicative interfaces that provide effective backend support, making integration
possible from any corner of the world. This also cuts down on an organization’s needs to invest both time and
resources in manual data-handling and data errors, promoting speed, precision and efficiency in resource
management.

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 format, as specified.

• 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).

Matrix COSEC Web API User Guide 3

 • Use a mandatory parameter action universally, which takes simple HTTP actions (such as GET, SET,
DELETE etc.) as values, and specifies the action to be requested.

What the User Should Know

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

• Basic functioning of the COSEC system

• Basic HTTP request-response communication

• XML

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

• The COSEC software application (pre-installed).

• The location for COSEC Web server (pre-installed).

• A network enabled for accessing the COSEC Web server.

• API access enabled on the COSEC Web server.

To learn about system requirements, please refer to the COSEC Manual in your software installation kit.

Enabling API Access

COSEC APIs are applicable to any COSEC System Account user enabled for API access. The COSEC server will
require Basic Authentication using the System Account user’s login credentials (Username and Password).

To know how to enable API access for a user, please refer to the COSEC Manual in your software
installation kit.

Matrix COSEC Web API User Guide 4

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

Communication Flow
The communication takes place in the following manner:

1. The client checks availablility of the Web Application server.

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

3. The server parses the request for the action to be taken. For e.g. for the action=get method, the server
fetches specified data from the COSEC database.

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 as a response.

5 Matrix COSEC Web API User Guide

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

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

separated by a space:

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

1. Request Line • The requested URL

• The HTTP version to use

For e.g.:

GET [Link] HTTP/1.0

Add information about the request using these header fields:

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

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

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

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

4 Message Body This is the chunk or payload.

Example:

GET [Link] HTTP/1.0

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

Matrix COSEC Web API User Guide 6

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

VERSION-HTTP CODE EXPLANATION<crlf>

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

It consists of the following components:

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

separated by a space:

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

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

These optional lines allow additional information to be added to the

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

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

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

HTTP/1.0 200 OK
Date: Sat, 15 Jan 2000 [Link] GMT
Server: Microsoft-IIS/2.0
Content-Type: text/HTML
Content-Length: 1245
Last-Modified: Fri, 14 Jan 2000 [Link]
GMT

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

7 Matrix COSEC Web API User Guide

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

[Link]

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

Table: URL Structure

URL element Description

This is the protocol used to communicate with the client.

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

This describes the server location where the COSEC Web is installed. It could be an IP
address or a domain name.

For eg. let’s say the IP address for COSEC Web is [Link]/cosec. Then a generic
HTTP query would look like:
<servername>
[Link]

Note: This document commonly uses the domain name “matrixserver” for all its
examples.

[Link] This is a mandatory entity required to invoke the API service.

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

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

request can support multiple arguments.
<argument>
A mandatory argument for all COSEC API functions is action. This argument always takes
an HTTP action as its value (For eg. action=get).

These are argument values that determine the response. Requests may allow single or
<value>
multiple (‘comma’ separated) values for an argument, depending on the API called.

Example

Let us assume that the COSEC Web has been installed on a location named “matrixserver”. The user wants to
retrieve a list of all panel devices defined on the COSEC database. In this case, a sample request would resemble
the following:

Sample Request:

[Link]

Sample Response:

id|name|siteid
p_1|Panel-1|
<EOT>

Matrix COSEC Web API User Guide 8

In this case, the query uses an action=get argument which is commonly used to retrieve information from a server.
This action takes an argument type which in this case, defines the device type (“panel”) and takes the value panel.

Specifying the Format

The response for COSEC API can be returned in one of the following formats:

• Text
• XML

The expected response format can be specified using a common argument: format. When no format is specified,
the response is returned in text format, by default.

Example

Following are some sample cases for the format argument.

Sample Request:

To get response in text,

[Link]

Sample Response:

id|name|siteid
d_1|direct door|1
d_3|NGT Door|1
d_6|5453|1
d_2|NGTDoor1|1
<EOT>

Sample Request:

To get response in XML,

[Link]

9 Matrix COSEC Web API User Guide

Sample Response:

For the text format, response data would be displayed as follows:

• Each field in the event or data output shall be separated by a “pipe”(|).

• Each event or data line should be completed with a “carriage return - line feed”(CRLF).
• The message body should end with <EOT> indicating ‘end of transmission’.

Getting a List of Supported Fields

The COSEC system supports “schema” to get a list of all fields supported by an API for a specific action in a
specified format.

Syntax

[Link]

The valid arguments for this request are action and format.

Example

Sample Request:

[Link]

Matrix COSEC Web API User Guide 10

Sample Response:

Additional Information
1. If an argument-value pair is mentioned multiple times in a request, the last value will be considered.

Example:

[Link]

In this case, id = 5678 will be considered.

2. For all the API’s the response for date parameters will be in the following format: mm/dd/yyyy HH:MM

3. Special characters (&, ‘, “, <, > and ;) for any arguments and its value are not allowed.

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 server. Enter the
authentication credentials when prompted. The response will be displayed on your browser in the specified
format.

11 Matrix COSEC Web API User Guide

Supported APIs
The remaining chapters in this User Guide shall list and describe all APIs supported by COSEC. These interfaces
have been organized into chapters based on license requirements as well as functionality, for the convenience of
understanding. The following table provides a quick reference list for all supported functions and their license
requirement:

Table 1: Supported APIs

Function <request-type>? Request URL License Requirement

[Link]
Getting a Device List device? Basic
device?action=get;<argument>=<value>...

[Link]
Assigning Users to Devices device? Basic
device?action=assign;<argument>=<value>...

[Link]
Revoking Users from Device device? Basic
device?action=revoke;<argument>=<value>...

[Link]
Adding a New Device device? Basic
device?action=set;<argument>=<value>...

[Link]
Deleting a Device device? Basic
device?action=delete;<argument>=<value>...

[Link]
Obtaining Device Status device? Basic
device?action=list;<argument>=<value>......

[Link]
Updating Device
device? device?action=update;<argument>=<value>... Basic
Configuration
..

Obtaining Data on Existing [Link]

site? Basic
Sites site?action=get;<argument>=<value>...

[Link]
Accessing User Data user? Basic
user?action=get;<argument>=<value>...

[Link]
Adding/Editing a User user? Basic
user?action=set;<argument>=<value>...

[Link]
Adding User Photograph user? Basic
user?action=setphoto;<argument>=<value>...

[Link]
Deleting a User user? Basic
user?action=delete;<argument>=<value>...

[Link]
Enrolling a User user? Basic
user?action=enroll;<argument>=<value>...

Setting Credentials on [Link]

user? Basic
Device credential;<argument>=<value>...

Deleting Credentials from [Link]

user? Basic
Device credential;<argument>=<value>...

organization?,
branch?,
Obtaining Enterprise Group department?, [Link]
T&A or Roster
Details designation?, group>?action=get;<argument>=<value>...
category?, grade?,
section?

Obtaining List of Renamed [Link]

group-rename-list? T&A or Roster
Groups list?action=get

Getting Daily Attendance [Link] T&A

attendance-daily?
Details daily?action=get;<argument>=<value>...

Matrix COSEC Web API User Guide 12

Table 1: Supported APIs

Function <request-type>? Request URL License Requirement

Getting Monthly Attendance [Link]

attendance-monthly? T&A
Details monthly?action=get;<argument>=<value>...

[Link]
Obtaining List of Access
accessroutemaster? accessroutemaster?action=get;<argument>=< Access Control
Routes
value>...

[Link]
Obtaining Access Route Access Control
accessroutedetails? accessroutedetails?action=get;<argument>=<
Details
value>...

[Link]
Getting Export Template List template-list? Basic
list?action=get;<argument>=<value>...

Getting Export Template [Link]

template-details? Basic
Details details?action=get;<argument>=<value>...

[Link]
Getting Import Template List import-template-list? Basic
list?action=get;<argument>=<value>...

Getting Import template import-template- [Link]

Basic
Details details? details?action=get;<argument>=<value>...

[Link]
Getting Template Data template-data? Basic
data?action=get;<argument>=<value>...

[Link]
Retrieving User Data datatransfer? datatransfer?action=get;<argument>=<value>. Basic
.

[Link]
Sending User Data datatransfer? datatransfer?action=set;<argument>=<value>. Basic
.

[Link]
Adding an Event events? Basic
events?action=set;<argument>=<value>...

Obtaining Time and [Link]

event-ta? T&A
Attendance Event Details ta?action=get;<argument>=<value>...

Obtaining Time and

[Link]
Attendance Event Details (By event-ta-date? T&A
date?action=get;<argument>=<value>...
Date)

Obtaining Access Control [Link]

event-acs? Basic
Event Details acs?action=get;<argument>=<value>...

Obtaining Access Control [Link]

event-acs-date? Basic
Event Details (By Date) date?action=get;<argument>=<value>...

Obtaining Door/Alarm/ [Link]

event-others? Basic
System Event Details others?action=get;<argument>=<value>...

[Link]
Sending Commands to commands?action=command;<argument>=<v
device-commands? Basic
Device alue>......

[Link]
Getting User Count on
device-users? users?action=get;<argument>=<value>...... Basic
Devices

13 Matrix COSEC Web API User Guide

CHAPTER 3 Devices

The Devices interface lets you access and modify device data on the COSEC server. The HTTP query syntax to
access device data from the COSEC server is as follows:

Syntax

[Link]

The Devices API allows you to perform the following functions:

• Getting a Device List

• Assigning Users to Device

• Revoking Users from Device

• Adding a New Device

• Deleting a Device

• Obtaining Device Status

• Updating Device Configuration

Matrix COSEC Web API User Guide 14

Getting a Device List

This COSEC API allows the user to obtain a list of available devices on the COSEC database. For instance, an
organization may have 100 panels and 200 direct door devices enlisted via COSEC. The user can obtain a list of all
the 300 devices or a list for an individual device type using this command.

Action

action=get

Syntax

[Link]

Parameters

Table: Getting a Device List - Parameters

Argument Valid Values Mandatory Default Value Description

To specify type of device/devices

all, door, panel, group,
type No all whose list is to be fetched (only one
paneldoor
value at a time).

Response Fields

Table: Getting a Device List - Response fields

Field Name Tag Name Valid Values Remarks

Here, p means panel, d

means direct doors and g
all, means group,
p_1 to p_999,
Id id
d_1 to d_9999, while, p_1 will stand for a
g_1 to g_99999 panel device with
ID = 1

This is the name of the

Name name Max. 30 alphanumeric characters
device.

This is the site

identification number.
Site Id site-id 1 to 999
Only for type= door and
type=paneldoor

Example

This example presents a sample request and response case when accessing “matrixserver”, for obtaining a list of
all available devices:

Sample Request:

[Link]

15 Matrix COSEC Web API User Guide

Sample Response:

id|name|siteid
g_1|Device-1|
g_2|dnext|
g_3|d3|
g_4|Research|
p_1|Panel-1|
d_1|direct door|1
d_3|NGT Door|1
d_6|5453|1
d_2|NGTDoor1|1
<EOT>

The sample response simply illustrates a particular instance of the expected output. The actual data for
each field will differ from case to case.

Sample Request:

For type=door,

[Link]

Sample Response:

id|name|siteid
d_1|direct door|1
d_3|NGT Door|1
d_6|5453|1
d_2|NGTDoor1|1
<EOT>

Matrix COSEC Web API User Guide 16

Assigning Users to Device

This function helps assign a user to all or specific Panels, Direct Doors or Device Groups pre-defined on the
COSEC system.

Action

action=assign

Syntax

[Link]

Parameters

Table: Assigning Users to Device - Parameters

Argument Valid Values Mandatory Default Value Description

Yes - To specify the device with the device

all, type and device ID.
p_1 to p_999,
device
d_1 to d_9999, Here, p means panel, d means direct
g_1 to g_99999 doors and g means group, while, p_1
will stand for a panel device with ID = 1

Max 10 Alphanumeric Yes - To specify the User ID.

id
Characters

Multiple devices (either panels or doors) of the same type can be specified, each value separated by a ‘comma’
(For eg. device=p_1,p_2,p_3,p_4,d_1,d_2,d_3,d_4,…). User can also define a range of devices (eg.
device=p_1-p_50). However, only a single group can be assigned to a user. The same should also be applicable
for id values.

Example

Following are some sample cases for this function.

Sample Request:

Assigning multiple group values to the device argument. Invalid request.

[Link]

Sample Response:

failed: Invalid command : device=g_1,g_2 only single group against a user

17 Matrix COSEC Web API User Guide

Sample Request:

To assign user to all devices.

[Link]

Sample Response:

success: successful

Sample Request:

For ”device=p_1”, “id=1”,

[Link]

Sample Response:

success: successful

Sample Request:

For user to be assigned to “p_1”,”d_1” and “g_1”,

[Link]

Sample Response:

success: successful

Matrix COSEC Web API User Guide 18

Revoking Users from Device

The purpose of this function is to revoke a user from all or specific devices defined on the COSEC system. This can
be performed for a single device type, multiple device types or for a specific device group.

Only a single group will be allowed to be revoked from a user at a time.

Action

action=revoke

Syntax

[Link]

Parameters

Same as Table: Assigning Users to Device - Parameters.

Example

This example presents a sample request and response when accessing “matrixserver”.

Sample Request:

For revoking all devices.

[Link]

Sample Response:

success: successful

Sample Request:

For ”device=p_1”, ”id=1”.

[Link]

Sample Response:

success: successful

Sample Request:

For “device=p_1,d_1,g_1”.

[Link]

19 Matrix COSEC Web API User Guide

Sample Response:

success: successful

Matrix COSEC Web API User Guide 20

Adding a New Device

This function enables you to define a new biometric device on the COSEC database and set certain configurations
depending on the device type. The device can be assigned to a specified device group and site and configured
based on site requirements.

Action

action=set

Syntax

[Link]

Parameters

Table: Adding a New Device - Parameters

Argument Valid Values Mandatory Default Value Description

This is the type of device, which

user wants to add.

Here,

0 = Panel,
1 = Direct Door V1,
device-type 0,1,2,3,4,5,6,7,8,9 Yes - 2 = Panel Lite
3 = Direct Door V2,
4 = NGT Direct Door,
5 = Wireless Direct Door
6 = Path Controller
7 = PVR Direct Door
8 = Vega Panel-Lite
9 = Vega Controller

This is the device identification

device-id 1 to 65000 Yes -
number of the device type (MID).

name Maximum 30 characters Yes - This is the name of the device.

This is the MAC Address of the

Maximum 17 characters (each device.
mac Yes -
byte separated by “:”)
E.g. - “[Link]”

This is the name of the device

device-group Maximum 30 characters No - group to which the device is to be
added.

0 = active The enabled/disabled status of the

active No 1 (active)
1 = inactive device.

If not specified then

the default site will
be internally This will define the site ID of the
site 1 to 999 No
configured against direct doors and panel door.
the device being
added.

21 Matrix COSEC Web API User Guide

Table: Adding a New Device - Parameters

Argument Valid Values Mandatory Default Value Description

This field is only applicable to

direct doors. This field will define
0 = Basic Access Control 0 (Basic Access the application/use of the device.
application No
1 = Advanced Access Control Control) (this feature enables the
advanced access control features
on device).

0= card This field is applicable to direct

1= finger doors only
2= card & PIN
3= finger & PIN Note:
4= card & finger Options 0,1,2,3,4,5,6 and 12 are
5= card & finger & PIN applicable only to device with
6= Any finger print reader.
access-mode No 6 (Any)
7= palm
8= palm & PIN Options 0,2,6,7,8,9,10 and 11 are
9= card & palm applicable for devices with Palm
10= card & PIN & palm Vein Reader.
11= palm & group
12= finger then card For Path Controllers, modes 2, 3,
13= palm then card and 5 are not applicable.

This parameter will toggle the

feature of considering the event
consider-for- 0 - disabled
No 1 (enabled) originating from the respective
attendance 1 - enabled
device for attendance calculation/
process.

0=entry This will set the Internal Reader IO

ir-mode No 0 (entry)
1=exit type (entry or exit).

0= none
1= emprox reader
2= hidprox reader This is the internal card reader
card-reader-type No 1 (emprox reader)
3= mifare reader type.
4= hid iclass u-reader
5= hid iclass w-reader

This will identify the finger/palm

0=none 1 (If device type is reader type as an internal reader.
finger-reader-type 1= finger reader No PVR, the default
2=palm reader value will be 2) Note: Palm Reader is applicable
for PVR Doors only.

0= entry
er-mode No 1 (exit) This is the external reader mode.
1= exit

0= none This will determine the external

1= em prox reader reader IO type.
2== hid prox reader
3= mifare reader For device type=1 (direct door
4=hid iclass u reader V1), er-types (8,9,10) are not
er-type No 0 (none)
5= finger reader applicable.
6= hid icalss w-reader
8= uhf reader er-type=5 is not applicable to
9= combo exit reader PVR door type.
10= mifare w reader

This parameter will be used to

0= enable
exit-switch No 1 (disable) enable/disable the exit switch for
1= disable
the door.

To update device configurations for the above parameters, See “Updating Device Configuration” on
page 26.

Matrix COSEC Web API User Guide 22

Example

The following is an example of a successful request sent to “matrixserver” with the following values:
• device-type=0
• device-id=1
• name=panel
• mac=[Link]
• device-group=Research

Sample Request:

[Link]
id=1;name=panel;mac=[Link];device-group=Research

Sample Response:

success: successful

23 Matrix COSEC Web API User Guide

Deleting a Device

This Devices function allows you to delete a biometric device from the COSEC database. Specify the device type
and device ID to send a ‘delete’ command.

Action

action=delete

Syntax

[Link]

This process is irreversible. Please proceed with caution.

Parameters

Table: Deleting a Device - Parameters

Argument Valid Values Mandatory Default Value Description

This is the type of device, which user

wants to delete.

Here,

0 = Panel,
1 = Direct Door V1,
device-type 0,1,2,3,4,5,6,7,8,9 Yes - 2 = Panel Lite
3 = Direct Door V2,
4 = NGT Direct Door,
5 = Wireless Direct Door
6 = Path Controller
7 = PVR Direct Door
8 = Vega Panel-Lite
9 = Vega Controller

To specify the device identification

device-id 1-9999 Yes -
number.

Example

The following example illustrates how to delete a direct door device with a device identification number 1:

Sample Request:

[Link]

Sample Response:

success: successful

Matrix COSEC Web API User Guide 24

Obtaining Device Status

This function enables the user to obtain the connection status of devices. The user can obtain a list of devices from
the COSEC server based on the device status. The device status can be either ‘connected’ or ‘disconnected’.

Action

action=list

Syntax

[Link]

Parameters

Table: Obtaining Device Status - Parameters

Argument Valid Values Mandatory Default Value Description

all, connected, To specify the devices to be listed on

status No all
disconnected the basis of their status.

Example

The following are some sample cases of requests sent to “matrixserver”:

Sample Request:

To obtain a list of all connected devices (“status=connected”).

[Link]

Sample Response:

success: No records found

Sample Request:

When “status=all”,

[Link]

Sample Response:

device-type|device-id|name|active|ip|mac|status|connect-time|disconnect-time
0|1|Panel-1|1||[Link]|disconnected||10/3/2013 [Link] AM
1|1|door|1|[Link]|[Link]|disconnected|10/3/2011 [Link] AM|10/3/2013 [Link] AM
4|2|NGTDoor1|1||[Link]|disconnected||10/3/2013 [Link] AM
3|3|NGT Door|1||[Link]|disconnected||10/3/2013 [Link] AM
3|6|5453|1||[Link]|disconnected||10/3/2013 [Link] AM
<EOT>

25 Matrix COSEC Web API User Guide

Updating Device Configuration

Specify a device ID and device type and edit the configuration for this device as saved on the COSEC database.
Parameters that can be updated are specified in the argument-value table below.

Action

action=update

This method is not applicable for Panel Doors.

Syntax

[Link]

Parameters

Same as Table: Adding a New Device - Parameters.

The Login User must have rights on the device which is to be updated.

Example

The following are some sample cases of requests sent to “matrixserver”:

Sample Request:

To update a Direct Door V2 named “RndBasementV2”.

[Link]

Sample Response:

success: successful

Sample Request:

When the specified MAC address is already associated with another device. Failed Request.

[Link]
type=9;mac=[Link];device-group=RnD

Sample Response:

failed: Mac is already associated with another device.

Matrix COSEC Web API User Guide 26

CHAPTER 4 Sites

A Site is a work area or unit defined on the COSEC system to which one or more COSEC devices are assigned. A
site can be defined by an administrator based on requirements. For e.g.: The organization ABC could have multiple
sites defined, such as ABCheadoffice, ABCfactory, ABCwarehouse and so on. This COSEC API allows users to
access data of specific sites using COSEC. The http query to access site data from the COSEC server should
resemble the following syntax:

Syntax

[Link]

The Sites APIs allow you to perform the following functions:

• Obtaining Data on Existing Sites

Matrix COSEC Web API User Guide 27

Obtaining Data on Existing Sites

This function allows the user to access data about existing sites. This includes the Site ID, Site Name and a Default
site.

Action

action=get

Syntax

[Link]

Response Fields

Table: Obtaining Data on Existing Sites - Response Fields

Field Name Tag Name Valid Values Remarks

Site ID Id 1 - 999 The Site ID

Site Name Name Max 30 alphanumeric character The Site Name

This indicate whether the

1 : default site
Default Default specified site is a default
0 : not a default site
site or not.

Example

Sample Request:

With default values,

[Link]

Sample Response:

Id|Name|Default
1|Site-1|1
2|h|0
<EOT>

Sample Request:

Syntax with valid action but no record available,

[Link]

Sample Response:

success: No records found

Matrix COSEC Web API User Guide 28

CHAPTER 5 Users

This API allows the access and modification of user data from the COSEC database. The Users APIs allows you to
perform the following functions:

• Accessing User Data

• Adding/Editing a User

• Adding User Photograph

• Deleting a User

• Enrolling a User

• Setting Credentials on Device

• Deleting Credentials from Device

Matrix COSEC Web API User Guide 29

Accessing User Data

This function allows you to retrieve specific data for a single user or multiple users. For instance, this method can
be used to retrieve an employee’s name, date-of-birth, joining date, blood-group, Passport Number etc.

Action

action=get

Syntax

[Link]

Parameters

Table: Accessing User Data - Parameters

Argument Valid Values Mandatory Default Value Description

This is the user id.

Note: Multiple IDs can be selected,

Max 10 alphanumeric each separated by a ‘comma’.
id No all
characters e.g.:”1, 3, 7, 9…”

Note: If id is not mentioned, data for all

the users will be returned.

Response Fields

Table: Accessing User Data - Response Fields

Field Name Tag Name Valid Values Remarks

Allowed Characters
A-Z
Id id max 10 characters a-z
0-9
/_\\.@:

Reference Code reference-code 1 to 99999999 (max 8 digits) -

Allowed Characters
A-Z
User Name name max 45 alphanumeric characters a-z
0-9
-_. ()[]

Short Name short-name max 15 alphanumeric characters -

1 : Active
Active active -
0 : Inactive

U- T&A User
Module module -
R- Roster User

Date of Birth date-of-birth ddmmyyyy -

Joining Date joining-date ddmmyyyy -

Confirmation Date confirmation-date ddmmyyyy -

Leaving Date leaving-date ddmmyyyy -

Matrix COSEC Web API User Guide 30

Table: Accessing User Data - Response Fields

Field Name Tag Name Valid Values Remarks

Reason For Leaving reason-for-leaving max 15 alphanumeric characters -

PF No. pf-no max 30 alphanumeric characters -

Driving License driving-license max 30 alphanumeric characters -

PAN No. pan max 30 alphanumeric characters -

ESI No. esi-no max 30 alphanumeric characters -

Passport No. passport-no max 30 alphanumeric characters -

Visa No. visa-no max 12 alphanumeric characters -

Visa Expiry Date visa-expiry ddmmyyyy -

Integration Reference integration-reference max 20 alphanumeric characters -

Height height 0 - 999 -

Weight weight 0 - 999 -

na
Gender gender male -
female

na,a+,a-,b+,b-,ab+,ab-,o+,o-
Blood Group blood-group ,A1–,A1+,A1B-,A1B+,A2- -
,A2+,A2B–,A2B+,B1+

married
Marital Status marital-status unmarried -
na

Nationality nationality max 20 alphanumeric characters -

Father/Spouse Name father-spouse-name max 30 alphanumeric characters -

Qualification qualification max 50 alphanumeric characters -

Experience experience max 50 alphanumeric characters -

Medical History medical-history max 50 alphanumeric characters -

Local Address1 local-address1 max 30 alphanumeric characters -

Local Address2 local-address2 max 30 alphanumeric characters -

Local Street local-street max 30 alphanumeric characters -

Local City local-city max 30 alphanumeric characters -

Local Pin code local-pincode max 10 alphanumeric characters -

Local State local-state max 40 alphanumeric characters -

Local Country local-country max 20 alphanumeric characters -

Permanent Address1 permanent-address1 max 30 alphanumeric characters -

Permanent Address2 permanent-address2 max 30 alphanumeric characters -

Permanent Street permanent-street max 20 alphanumeric characters -

Permanent City permanent-city max 30 alphanumeric characters -

Permanent Pin Code permanent-pincode max 20 alphanumeric characters -

Permanent State permanent-state max 40 alphanumeric characters -

Permanent Country permanent-country max 20 alphanumeric characters -

31 Matrix COSEC Web API User Guide

Table: Accessing User Data - Response Fields

Field Name Tag Name Valid Values Remarks

Personal Phone personal-phone max 30 numeric characters or - -

Personal Cell personal-cell max 20 numeric characters or - -

Personal E-mail personal-email max 100 alphanumeric characters -

Official Phone official-phone max 30 numeric characters or - -

Official Extension official-extension max 4 numeric characters -

Official Cell official-cell max 20 numeric characters or - -

Official E-mail official-email max 100 alphanumeric characters -

Organization ID organization 1 - 999999 -

Branch ID branch 1 - 999999 -

Department ID department 1 - 999999 -

Section ID section 1 - 999999 -

Category ID category 1 - 999999 -

Grade ID grade 1 - 999999 -

Designation ID designation 1 - 999999 -

Reporting In-Charge reporting-incharge 1 - 999 -

1 : enabled
ESS Login ess-login -
0 : disabled

1 : editing allowed
ESS Detail Edit ess-detail-edit -
0 : editing not allowed

1 : enabled
Attendance via ESS attendance-via-ess -
0 : disabled

1 : enabled
Active Directory Login active-directory-login -
0 : disabled

Active Directory Username active-directory-username max 128 alphanumeric characters -

Active Directory Domain active-directory-domain max 128 alphanumeric characters -

1 : enabled
Attendance Calculation attendance-calc -
0 : disabled

Max Personal hours max-personal-hrs 0 - 99 -

Bus Route bus-route 0 - 999 -

1 – enable bypass
Bypass Fingerprint/Palm bypass-finpalm -
0 – disable bypass

Employment Profile employment-contract max 4 alphanumeric characters -

Employment Type employment-type max 4 alphanumeric characters -

Award and Penalty award-penalty max 4 alphanumeric characters -

Work Profile work-profile max 4 alphanumeric characters -

Roster Policy roster-policy max 4 alphanumeric characters -

Attendance Policy (Roster) roster-attendance-policy max 4 alphanumeric characters -

Hour Exception hour-exception max 4 alphanumeric characters -

Attendance Policy (T&A) attendance-policy 1-99 -

Matrix COSEC Web API User Guide 32

Table: Accessing User Data - Response Fields

Field Name Tag Name Valid Values Remarks

Late-In Policy lateIn-policy 1-99 -

Early Out policy earlyOut-policy 1-99 -

Overtime Policy overtime-policy 1-99 -

Absentee Policy absentee-policy 1-99 -

C-Off Policy coff-policy 1-99 -

PIN pin 1-999999 -

Card-1 card-1 max 20 numeric characters -

Card-2 card-2 max 20 numeric characters -

Access Validity Date access-validity-date ddmmyyyy format -

Access Level access-level 1 - 15 -

1 – enable bypass
Bypass Finger bypass-finger -
0 – disable bypass

1 – enable bypass
Bypass Palm bypass-palm -
0 – disable bypass

1 – access allowed
Shift based access shiftbased-access -
0 – access denied

Shift Schedule shift-schedule 1- 99 -

Start Shift start-shift max 2 numeric characters -

Holiday Schedule holiday-schedule 1 - 99 -

Device Group device-group max 30 numeric characters -

Smart access route smart-access-route 1 - 99 -

Max route level max-route-level 1 - 75 -

1 - allowed
Allow e-Canteen allow-ecanteen -
0 – not allowed

Discount Level discount-level 0 to 4 -

1 - postpaid
Account Type account-type -
0 - prepaid

Max Allowed Limit max-allowed-limit 0.0 to 9999999.9 -

Max Usage Limit max-usage-limit 0.0 to 9999999.9 -

Organization Code organization_code max 6 alphanumeric characters -

Branch Code branch_code max 6 alphanumeric characters -

Department Code department_code max 6 alphanumeric characters -

Category Code category_code max 6 alphanumeric characters -

Grade Code grade_code max 6 alphanumeric characters -

Designation Code designation_code max 6 alphanumeric characters -

Section Code section_code max 6 alphanumeric characters -

Leave Group ID leave_group 1-99 -

33 Matrix COSEC Web API User Guide

Adding/Editing a User

This API will allow you to define a new user, as well as add/edit specific data for an existing user on the COSEC
database (only single user at a time). For instance, this process can be used to add information such as an
employee’s name, date-of-birth, joining date, blood-group, Passport Number etc.

Action

action=set

If the action=set request is sent for an existing user, the new values sent will overwrite the existing values,
if any.

Syntax

[Link]

Parameters

Table: Adding/Editing a User - Parameters

Argument Valid Values Mandatory Default Value Description

This is the User Id.

Max 10 Alphanumeric
id Yes - For ESS User, the User ID should be
Characters
same as Login User’s ID

Max stored ref

This is the unique Reference code for
reference-code 1 to 99999999 No code+1
every User.

This is the User Name.

Allowed Characters
Max 45 Alphanumeric A-Z
name Yes -
Characters a-z
0-9
-_. ()[]

This is the short name of User.

Allowed Characters
First 15 characters
Max 15 Alphanumeric A-Z
short-name No of name
Characters a-z
0-9
-_. ()

This is a field that shows whether user

is active or not.
active 0 or 1 No 1
It has two values 0 and 1 for inactive
and active respectively.

This value specifies the user type.

Depending upon
module U or R Yes U- T&A User
License
R- Roster User

Matrix COSEC Web API User Guide 34

Table: Adding/Editing a User - Parameters

Argument Valid Values Mandatory Default Value Description

This is the date of birth of the user.

date-of-birth ddmmyyyy format No -
Note: - date-of-birth shall be lower than
joining-date.

Y (if
This is the joining date of the user.
confirmation-
joining-date ddmmyyyy format
date or leaving- -
Note: - joining-date should be higher
date to be
than date-of-birth.
configured)

This is the confirmation date of the user.

ddmmyyyy format
confirmation-date No -
Note: - confirmation-date shall not be
lower than joining-date.

This is the date of leaving of the user.

Yes (if reason
ddmmyyyy format
leaving-date for leaving to -
Note: - leaving-date shall not be lower
be configured)
than joining-date.

Max 15 Alphanumeric This is the reason of leaving an

reason-for-leaving No -
Characters organization.

Max 30 Alphanumeric
pf-no No - This is the PF Number of the user.
Characters

Max 30 Alphanumeric
driving-license No - This is the driving license of the user.
Characters

Max 30 Alphanumeric
pan No - This is the PAN of the user.
Characters

Max 30 Alphanumeric
esi-no No - This is the ESI Number of the
Characters

Max 30 Alphanumeric This is the Passport Number of the

passport-no No -
Characters user.

Yes (If visa-

Max 12 Alphanumeric
visa-no expiry date to - This is the IQAMA number of the user.
Characters
be configured)

This is the date of expiry of the IQAMA

visa-expiry ddmmyyyy format No -
or visa.

Max 20 Alphanumeric This is the integration reference for the

integration-reference No -
Characters user.

This is the height of the user in the

height 0 to 999 No -
centimeter.

weight 0 to 999 No - This is the weight of the user in Kg.

na,
gender No NA This is the gender of the user.
male,female

NA,A+,A-,B+,B-
,AB+,AB-,o+,o-
blood-group ,A1–,A1+, A1B-, No NA This is the blood group of the user.
A1B+,A2-
,A2+,A2B–,A2B+,B1+

marital-status married,unmarried No Married This is the marital status of the user.

Max 20 alphanumeric
nationality No - This is the nationality of the user.
characters

35 Matrix COSEC Web API User Guide

Table: Adding/Editing a User - Parameters

Argument Valid Values Mandatory Default Value Description

Max 30 Alphanumeric This is the father or spouse name of the

father-spouse-name No -
Characters user.

Max 50 Alphanumeric
qualification No - This is the qualification of the user.
Characters

max 50 alphanumeric
experience No - This is the work experience of the user.
characters

max 50 alphanumeric
medical-history No - This is the medical history of the user.
characters

max 30 alphanumeric
local-address1 No - This is the local address 1 of the user.
characters

max 30 alphanumeric
local-address2 No - This is the local address 2 of the user.
characters

max 30 alphanumeric
local-street No - This is the street for local address 1.
characters

max 40 alphanumeric
local-city No - This is the city for local address 1.
characters

max 10 numeric This is the local pin code for local

local-pincode No -
characters address 1.

max 40 alphanumeric
local-state No - This is the state for local address 1.
characters

max 20 alphanumeric
local-country No - This is the country for local address 1.
characters

max 30 alphanumeric This is the permanent address 1 of the

permanent-address1 No -
characters user.

max 30 alphanumeric This is the permanent address 2 of the

permanent-address2 No -
characters user.

max 20 alphanumeric This is the street for permanent address

permanent-street No -
characters 1.

max 30 alphanumeric
permanent-city No - This is the city for permanent address 1.
characters

max 10 numeric This is the local pin code for permanent

permanent-pincode No -
characters address 1.

max 40 alphanumeric This is the state for permanent address

permanent-state No -
characters 1.

max 20 alphanumeric This is the country for permanent

permanent-country No -
characters address 1.

max 32 numeric This is the personal phone number of

personal-phone No -
characters or - the user.

max 30 numeric This is the personal mobile number of

personal-cell No -
characters or - the user.

max 100
This is the personal email address of
personal-email alphanumeric No -
the user.
characters

max 30 numeric This is the official phone number of the

official-phone No -
characters or - user.

max 10 numeric
official-extension No - This is the extension of the user.
characters

Matrix COSEC Web API User Guide 36

Table: Adding/Editing a User - Parameters

Argument Valid Values Mandatory Default Value Description

max 30 numeric This is the official mobile number of the

official-cell No -
characters or - user.

max 100
This is the official email address of the
official-email alphanumeric No -
user.
characters

Default
organization
organization 1 to 999999 No defined in This is the ‘Organization’ of the user.
Enterprise
structure

Default branch
defined in
branch 1 to 999999 No This is the ‘Branch’ of the user.
Enterprise
structure

Default department
defined in
department 1 to 999999 No This is the ‘Department’ of the user.
Enterprise
structure

Default section
defined in
section 1 to 999999 No This is the ‘Section’ of the user.
Enterprise
structure

Default category
defined in
category 1 to 999999 No This is the ‘Category’ of the user.
Enterprise
structure

Default grade
defined in
grade 1 to 999999 No This is the ‘Grade’ of the user.
Enterprise
structure

Default designation
defined in
designation 1 to 999 No This is the ‘Designation’ of the user.
Enterprise
structure

This is the “Reporting-in-charge” of the

reporting-incharge 1 to 999 No -
user

This field enables/disables the users

ess-login 1 or 0 No 0
ESS login.

This field toggles the option for user to

ess-detail-edit 1 or 0 No 0 change/edit the user’s basic details in
ESS.

This enables or disables the users

attendance-via-ess 1 or 0 No 0
attendance to be marked via ESS.

This enables/disables the users ESS

active-directory-login 1 or 0 No 0
login via Active directory credentials.

37 Matrix COSEC Web API User Guide

Table: Adding/Editing a User - Parameters

Argument Valid Values Mandatory Default Value Description

This is the user’s Active directory

username.

Yes (if active- Note: The active directory username

max 128
active-directory- directory-login provided should not be repeated for any
alphanumeric -
username to be other user. Also the active directory
characters
configured) username can be same as that user ID
of the same user for which the active
directory username is assigned and
none other.

Yes (if active-

max 128
directory-login This is the domain name for the active
active-directory-domain alphanumeric -
to be directory login purpose
characters
configured)

This enables/disables the attendance

attendance-calc 1 or 0 No 1
calculation for the user.

This configures the max number of

max-personal-hrs 0 to 99 No -
hours the user can use as short leave.

This is the bus route for the user. This is

bus-route 0 to 999 No -
an optional field.

This parameter enables/disables the

bypass-finpalm 1 or 0 No 0 option to bypass biometric credentials
for attendance marking.

Default
max 4 alphanumeric Employment This is the roster user’s Employment
employment-profile No
characters contract defined in contract.
Roster

Default
max 4 alphanumeric This is the roster user’s Employment
employment-type No Employment type
characters type.
defined in Roster

Default Award and

max 4 alphanumeric This is the award and penalty assigned
award-penalty No Penalty defined in
characters to the roster user.
Roster

Default Work
max 4 alphanumeric This is the work profile assigned to the
work-profile No Profile defined in
characters roster user.
Roster

Default General
max 4 alphanumeric Rules defined in This is the general rules assigned to the
general-rules No
characters Roster roster user.

Default Policy
max 4 alphanumeric This is the policy assigned to the roster
policy No defined in Roster
characters user.

max 4 alphanumeric This is the hour exception assigned to

hour-exception No -
characters the roster user.

Default Attendance
Policy defined in
This is the ‘Attendance policy’ of the
attendance-policy 1 to 99 No Time &
user.
Attendance/
Policies

Matrix COSEC Web API User Guide 38

Table: Adding/Editing a User - Parameters

Argument Valid Values Mandatory Default Value Description

Default Late In
Policy defined in
lateIn-policy 1 to 99 No Time & This is the ‘Late-In policy’ of the user.
Attendance/
Policies

Default Early Out

Policy defined in
This is the ‘Early-out policy’ of the user.
earlyOut-policy 1 to 99 No Time &
Attendance/
Policies

Default Overtime
Policy defined in
overtime-policy 1 to 99 No Time & This is the ‘Overtime policy’ of the user.
Attendance/
Policies

Default Absentee
Policy defined in
absentee-policy 1 to 99 No Time & This is the ‘Absentee policy’ of the user.
Attendance/
Policies

Default COFF
Policy defined in
coff-policy 1 to 99 No Time & This is the ‘COFF policy’ of the user.
Attendance/
Policies

This is the access control system pin

number of the user.
pin 1 to 999999 No -
Note: - Same pin will not be allowed
against any two user IDs.

This is the card number 1 of the user,

required for access control system.
max 20 numeric
card-1 No -
characters
Note: - Same value of card-1 will not be
allowed for any two user IDs.

This is the card number 2 of the user,

required for access control system.
max 20 numeric
card-2 No -
characters
Note: - Same value of card-2 will not be
allowed for any two user IDs.

This is the Access Validity date of the

user. Setting this will automatically
access-validity-date ddmmyyyy format No -
enable the ‘Access Validity’ feature for
the user.

This is the access level assigned to

access-level 1 to 15 No -
user, used for access control features.

This determines whether the user can

bypass-finger 1 or 0 No 0 bypass the finger credential for any
access control feature/rule.

This determines whether the user can

bypass-palm 1 or 0 No 0 bypass the palm credential for any
access control feature/rule.

39 Matrix COSEC Web API User Guide

Table: Adding/Editing a User - Parameters

Argument Valid Values Mandatory Default Value Description

This parameter determines the

application of access restriction based
shiftbased-access 1 or 0 No 0
on the shift assigned to the user from
the shift schedule.

This field assigns the shift schedule to

shift-schedule 1 to 99 No First Shift Schedule
the user.

max 2 alphanumeric The selected The user should define the start shift for
start-shift No
characters schedule’s first shift the selected shift schedule.

first holiday This field defines the users allowed

holiday-schedule 1 to 99 No
schedule holidays.

max 30 numeric
device-group No - This is the name of the device group.
characters

This field assigns the access route to

smart-access-route 1 to 99 No -
the user. (For Smartcard Users only)

This field assigns maximum level to

max-route-level 1 to 75 No 75 which user can access the Smart
Access Route.

This determines whether the ecanteen

features are allowed for the selected
user or not.
allow-ecanteen 1 or 0 No 0
Note: Whether the Allowed for e-
canteen option is true or false, user can
change Account Type (his account
should be settled) and Discount Level.

This value defines the user applicable

discount-level 0 to 4 No 0 discount level for any canteen
transactions.

This parameter determines the user’s

canteen account type.
account-type 1 or 0 No 0
0 – prepaid
1 - postpaid

As specified in
This defines the max allowed limit for
max-allowed-limit 0.0 to 9999999.9 No eCanteen/Account
the canteen user for a month.
configuration

As specified in This defines the max usage limit for the

max-usage-limit 0.0 to 9999999.9 No eCanteen/Account canteen user beyond which the user’s
configuration canteen account will be blocked.

max 6 alphanumeric Organization ID and Organization Code

organization_code No -
characters cannot be specified together.

max 6 alphanumeric Branch ID and Branch Code cannot be

branch_code No -
characters specified together.

max 6 alphanumeric Department ID and Department Code

department_code No -
characters cannot be specified together.

max 6 alphanumeric Category ID and Category Code cannot

category_code No -
characters be specified together.

max 6 alphanumeric Grade ID and Grade Code cannot be

grade_code No -
characters specified together.

max 6 alphanumeric Designation ID and Designation Code

designation_code No -
characters cannot be specified together.

Matrix COSEC Web API User Guide 40

Table: Adding/Editing a User - Parameters

Argument Valid Values Mandatory Default Value Description

max 6 alphanumeric Section ID and Section Code cannot be

section_code No -
characters specified together.

To specify a leave group ID, for a leave

leave_group 2 Digits
group to be assigned to the user.

Example

The following examples illustrate sample requests for adding or editing users.

Sample Request:

To add a user named “Sam”, whose user ID is “202” (activated for the Time and Attendance module license) -

[Link]

Sample Response:

success: successful

Sample Request:

To add details such as date of birth, gender, nationality and blood group for the user Sam.

[Link]
birth=22061978;gender=male;nationality=indian;blood-group=b+

Sample Response:

success: successful

Sample Request:

To change the username for Sam to “Samuel Jackson”.

[Link] Jackson

Sample Response:

success: successful

41 Matrix COSEC Web API User Guide

Adding User Photograph

Update the user photograph in a user’s configured profile on COSEC using this request.

Action

action=setphoto

Syntax

[Link]

Parameters

Table: Adding User Photograph - Parameters

Argument Valid Values Mandatory Default Value Description

Max 10 alphanumeric
userid Yes - This is the unique User Id.
characters

The path should

include the image file This will be the network path of the
also with file extension. image file which is to be set as user
photo.
Path Supported file types Yes
are: If FTP credential parameters are
.jpg,.jpeg,.bmp,.png specified, then the path mentioned
Also the file size should be an FTP path.
should be <= 50 kb

If the image is on an FTP location then

login credentials must be supplied. This
is the FTP username.
ftpusername - Yes -
This parameter must be used with the
‘ftppassword’ parameter for a
successful request.

If the image is on an FTP location then

login credentials must be supplied. This
is the FTP password.
ftppassword - Yes -
This parameter must be used with the
‘ftpusername’ parameter for a
successful request.

The supported file formats are *.jpg,*.bmp and *.png.

Example

This sample request illustrates how to set a photograph for the user ID 202, when the source image file [Link]
is located in the following FTP location: [Link]

Sample Request:

[Link]
[Link];ftpusername=sam;ftppassword=1234

Matrix COSEC Web API User Guide 42

Sample Response:

success: successful

43 Matrix COSEC Web API User Guide

Deleting a User

This function can be used to delete an existing user from the COSEC database permanently. Only a single user can
be deleted at a time using this method.

This process is irreversible. Please proceed with caution.

Action

action=delete

Syntax

[Link]

Parameters

Table: Deleting a User - Parameters

Argument Valid Values Mandatory Default Value Description

Max 10 alphanumeric This is the unique User Id.

id Yes -
characters

Example

This example illustrates how to delete the user Samuel (id=202) from the COSEC database:

Sample Request:

[Link]

Sample Response:

success: successful

Matrix COSEC Web API User Guide 44

Enrolling a User

This API can be used to generate an enrollment request for a user on a specific device. Only a single user can be
enrolled at a time using this action.

Action

action=enroll

Syntax

[Link]

Parameters

Table: Enrolling a User - Parameters

Argument Valid Values Mandatory Default Value Description

Max 10 alphanumeric
id Yes - This is the unique User ID.
characters

This is the type of device, in which

enrollment of respective user to be
done.
0 = Panel,
1 = Direct Door V1,
2 = Panel Lite
device-type 0-9 Yes - 3 = Direct Door V2,
4 = NGT Direct Door,
5 = Wireless Direct Door
6 = Path Controller
7 = PVR Direct Door
8= Vega Panel-Lite
9= Vega Controller

This is the device identification number

of the device type, on which enrollment
device-id 1 to 65000 Yes - of respective user is to be done. This
device must be assigned to the user-id
for which enrollment is to be performed.

Yes. Only if
device type =
This is the Panel Door identification
Panel (0),
panel-door-id 1 to 99 - number, in case a panel is selected for
Panel-Lite
device-type.
(2), or Vega
Panel-Lite (8)

This is the type of enrollment.

fp,
enroll-type card, Yes - Note: - Only Read-Only cards
palm supported.

1 to 10 (for enroll-
type=fp)
This is the count for the enroll type
1,2 (for enroll-
enroll-count Yes - (finger print, card or palm) to be
type=card)
enrolled for the respective user id.
1 to 10 (for enroll-
type=palm)

45 Matrix COSEC Web API User Guide

Example

This example demonstrates a typical request URL for enrolling 2 fingers for a user on a Direct Door V1:

Sample Request:

[Link]

Sample Response:

success: successful

Matrix COSEC Web API User Guide 46

Setting Credentials on Device

Send a user’s credentials to all the available panel or direct door devices on COSEC. There are two types of
credentials that can be set for a user - fingerprint (fp) and card.

Action

action=set-credential

Syntax

[Link]

Parameters

Table: Setting Credentials on Device - Parameters

Argument Valid Values Mandatory Default Value Description

Max 10 alphanumeric
id Yes - This is the unique User Id.
characters

credential-type fp, card Yes - This is the type of credential.

Max 768 Alphanumeric

Characters (for fp)
Max 20 numeric
This is the data of respective credential
Characters (for card)
type, which is to be stored at given
data Note: - For credential Yes -
index number for the respective user
type = finger print, user
ID.
should send finger
print templates into
hexadecimal.

This API supports setting credentials only for Read-Only cards.

Example

The following example illustrates how to add user credentials with the given set of values:
• id=1
• credential-type=card
• data=12345678901234567890 (card number)

Sample request:

[Link]
type=card;data=12345678901234567890

Sample Response:

success: successful

47 Matrix COSEC Web API User Guide

Deleting Credentials from Device

Delete a user’s credentials from all the available panel or direct door devices on COSEC.

Action

action=del-credential

Syntax

[Link]

Parameters

Table: Deleting Credentials from Device - Parameters

Argument Valid Values Mandatory Default Value Description

Max 10 alphanumeric
Id Yes - This is the unique User Id.
characters

credential-type fp, card, palm Yes - This is the type of credential.

This process is irreversible. Please proceed with caution.

This API supports Read-Only cards only.

Example

This example demonstrates a sample request to delete fingerprint credentials for a user with user ID “1” from all
devices on the COSEC database.

Sample Request:

[Link]

Sample Response:

success: successful

Matrix COSEC Web API User Guide 48

CHAPTER 6 Enterprise Structure

The Enterprise Structure APIs allow the user to retrieve data related to various groups within an enterprise. COSEC
identifies the following enterprise groups:
• Organization
• Branch
• Department
• Designation
• Section
• Category
• Grade

The generic syntax for all Enterprise Structure API requests is stated below.

Syntax

[Link]

Here, the request-type (<enterprise-group>) will depend on the enterprise group for which the API is being called.

For Organization: <enterprise-group>=organization

For Branch: <enterprise-group>=branch
For Department: <enterprise-group>=department
For Designation: <enterprise-group>=designation
For Section: <enterprise-group>=section
For Category: <enterprise-group>=category
For Grade: <enterprise-group>=grade

For e.g.:

For Organization, the API URL will resemble:

[Link]

Similarly, for Branch, send:

[Link]

Matrix COSEC Web API User Guide 49

 If an enterprise group is renamed on the COSEC system, the new label should be used in the URL to
invoke an API. For e.g. if the group ‘Organization’ is renamed as ‘Company’, then the URL syntax for
Organization APIs should be:

[Link]

For each of the Enterprise Groups, COSEC supports the following APIs:

• Obtaining Enterprise Group Details

• Obtaining List of Renamed Groups

Matrix COSEC Web API User Guide 50

Obtaining Enterprise Group Details

User can fetch the details of an enterprise group by specifying the group name in the <enterprise-group> part of the
URL and specifying the group ID. For example, for an organization, the group ID will be the Organization ID.

Action

action=get

Syntax

[Link]

Parameters

Table: Obtaining Enterprise Group Details - Parameters

Argument Valid Values Mandatory Default Value Description

1-999999
This is the ID of the specific enterprise
Note: This is the
group.
minimum to maximum
id No All Multiple IDs can be selected, each
range. In case of a
separated by “, (comma)” e.g.:”1, 3, 7,
system with a defined
9…”
ID range 1-50, valid
range shall be 1-50.

Response Fields

Table: Obtaining Enterprise Group Details - Response Fields

Field Name Tag Name Valid Values Remarks

ID id 1-999999 -

Allowed Characters
upto 40 characters (for
A-Z
“Organization” and “Branch”)
Name name a-z
0-9
upto 30 characters (for others)
-_. ()[]

Example

Fetching an organization by ID ‘7’.

Sample Request:

[Link]

Sample Response:

id|name
7|Apex Industries Pvt. Ltd.
<EOT>

51 Matrix COSEC Web API User Guide

Obtaining List of Renamed Groups

On COSEC, it is possible for an administrator to rename enterprise groups (For eg. “Organization” can be renamed
as “Organization1”). This particular API allows the user to retrieve the data of all enterprise groups which have been
renamed and their relevant details such as the group code, the display name and the alias name.

Action

action=get

Syntax

[Link]

Response Fields

Table: Obtaining List of Renamed Groups - Response Fields

Field Name Tag Name Valid Values Remarks

Duplicate Code not

Code code upto 6 alphanumeric characters
allowed

Allowed characters:
A-Z
Name displayName maximum 30 characters a-z
0-9
-_.()[]

Allowed characters:
A-Z
Alias Name aliasName maximum 30 characters a-z
0-9
-_.()[]

This API will return only values that are in the English Language. In case the groups are renamed and
stored in a different language, the original English group name will be used.

Example

Sample Request:

[Link]

Sample Response:

code|displayName|aliasName
Org|Organization|Organization
Brc|Branch|Branch
Dpt|Department|Department
Sec|Section|Section
Ctg|Category|Category
Grd|Grade|Grade
Dsg|Designation|Designation
Usr|User|User
<EOT>

Matrix COSEC Web API User Guide 52

CHAPTER 7 Time and Attendance

This section covers all APIs pertaining to Time and Attendance data of COSEC users. These are as follows:

• Getting Daily Attendance Data

• Getting Monthly Attendance Data

Matrix COSEC Web API User Guide 53

Getting Daily Attendance Data

This API allows the user to obtain daily attendance data for employees over a specified time duration and for
specific user groups.

Action

action=get

Syntax

[Link]

Parameters

Table: Getting Daily Attendance Data - Parameters

Argument Valid Values Mandatory Default Value Description

If “field-name” is not mentioned, then

configured “field-name” for the
The list of fields is respective template in ‘API Data
Field-name mentioned in the No - Template’ will be fetched.
Response Fields table. User can select multiple “field-name”,
each separated by “, (comma)”
e.g.:”userid, username, orgid…”

This is the date range for which data is

date-range ddmmyyyy-ddmmyyyy No Current Day
to be fetched.

all
organization
branch
department
Range of users for whom data is to be
range designation No All
fetched.
section
category
grade
user

1 to 999 (for all the

ranges except all & Each range (except all) shall have
user) specific id.
Yes, if
10 Char. (for user) System should allow user to select
mentioned
Note: This is the min multiple id, each separated by “,
Id range is other -
to max range. In case (comma)” e.g.:”1, 3, 7, 9…”
than ‘All’.
of a system with only Or
1-50 id defined then Select a range of id
valid range shall be 1- E.g.”1-50”.
50.

Response Fields

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

User ID USERID upto 10 characters. -

User Name USERNAME upto 45 characters -

Short Name short_name max 15 alphanumeric characters -

Matrix COSEC Web API User Guide 54

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

Integration Reference integration_reference max 20 alphanumeric characters -

Organization ID ORGID 1-999999 -

Branch ID BRCID 1-999999 -

Department ID DPTID 1-999999 -

Section ID SECID 1-999999 -

Category ID CTGID 1-999999 -

Grade ID GRDID 1-999999 -

Designation ID DSGID 1-999999 -

Reference No. ADLUSERID numeric (8 digits) -

M : Male
Gender GENDER F: Female -
NA : Not available

M : Married
Marital Status MRTLSTAT U : Unmarried -
NA : Not available

Birth Date BIRTHDT dd/mm/yyyy -

Joining Date JOINDT dd/mm/yyyy -

Leaving Date LEAVEDT dd/mm/yyyy -

Process Date PROCESSDATE dd/mm/yyyy -

Process Date PROCESSDATE_D mm/dd/yy HH:MM:SS -

1st Punch PUNCH1 dd/mm/yyyy HH:MM -

1st Punch PUNCH1_DATE dd/mm/yyyy -

1st Punch PUNCH1_TIME HH:MM -

2nd Punch PUNCH2 dd/mm/yyyy HH:MM -

2nd Punch PUNCH2_DATE dd/mm/yyyy -

2nd Punch PUNCH2_TIME HH:MM -

3rd Punch PUNCH3 dd/mm/yyyy HH:MM -

3rd Punch PUNCH3_DATE dd/mm/yyyy -

3rd Punch PUNCH3_TIME HH:MM -

4th Punch PUNCH4 dd/mm/yyyy HH:MM -

2nd Punch PUNCH2_TIME HH:MM -

4th Punch PUNCH4_DATE dd/mm/yyyy -

4th Punch PUNCH4_TIME HH:MM -

5th Punch PUNCH5 dd/mm/yyyy HH:MM -

5th Punch PUNCH5_DATE dd/mm/yyyy -

5th Punch PUNCH5_TIME HH:MM -

6th Punch PUNCH6 dd/mm/yyyy HH:MM -

6th Punch PUNCH6_DATE dd/mm/yyyy -

55 Matrix COSEC Web API User Guide

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

6th Punch PUNCH6_TIME HH:MM -

7th Punch PUNCH7 dd/mm/yyyy HH:MM -

7th Punch PUNCH7_DATE dd/mm/yyyy -

7th Punch PUNCH7_TIME HH:MM -

8th Punch PUNCH8 dd/mm/yyyy HH:MM -

8th Punch PUNCH8_DATE dd/mm/yyyy -

8th Punch PUNCH8_TIME HH:MM -

9th Punch PUNCH9 dd/mm/yyyy HH:MM -

9th Punch PUNCH9_DATE dd/mm/yyyy -

9th Punch PUNCH9_TIME HH:MM -

10th Punch PUNCH10 dd/mm/yyyy HH:MM -

10th Punch PUNCH10_DATE dd/mm/yyyy -

10th Punch PUNCH10_TIME HH:MM -

11th Punch PUNCH11 dd/mm/yyyy HH:MM -

11th Punch PUNCH11_DATE dd/mm/yyyy -

11th Punch PUNCH11_TIME HH:MM -

12th Punch PUNCH12 dd/mm/yyyy HH:MM -

12th Punch PUNCH12_DATE dd/mm/yyyy -

12th Punch PUNCH12_TIME HH:MM -

1=Official In,
2=Official Out,
3=ShortLeave In,
4=ShortLeave Out,
5=Regular In,
Special Function 1 SPFID1 1-10
6=Regular Out,
7=Lunch In,
8=Lunch Out,
9=Overtime In,
10=Overtime Out

Special Function 2 SPFID2 1-10 Same as above

Special Function 3 SPFID3 1-10 Same as above

Special Function 4 SPFID4 1-10 Same as above

Special Function 5 SPFID5 1-10 Same as above

Special Function 6 SPFID6 1-10 Same as above

Special Function 7 SPFID7 1-10 Same as above

Special Function 8 SPFID8 1-10 Same as above

Special Function 9 SPFID9 1-10 Same as above

Special Function 10 SPFID10 1-10 Same as above

Special Function 11 SPFID11 1-10 Same as above

Special Function 12 SPFID12 1-10 Same as above

Matrix COSEC Web API User Guide 56

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

Scheduled Shift SCHEDULESHIFT Two Character Code -

Work Shift WORKINGSHIFT Two Character Code -

Early In EARLYIN minutes -

Early In EARLYIN_HHMM HH:MM -

Late In LATEIN minutes -

Late In LATEIN_HHMM HH:MM -

Early Out EARLYOUT minutes -

Early Out EARLYOUT_HHMM HH:MM -

Overstay OVERSTAY minutes -

Overstay OVERSTAY_HHMM HH:MM -

Overtime OVERTIME minutes -

Overtime OVERTIME_HHMM HH:MM -

Work time WORKTIME minutes -

Work time WORKTIME_HHMM HH:MM -

PR : Present
AB : Absent
WO : Week Off
PH : Public Holiday <Leave Codes> as
First Half FIRSTHALF
FB : Field Break configured in COSEC
RD : Rest Day
IN : Official In
<Leave Codes>

PR : Present
AB : Absent
WO : Week Off
PH : Public Holiday <Leave Codes> as
Second Half SECONDHALF
FB : Field Break configured in COSEC
RD : Rest Day
IN : Official In
<Leave Codes>

Manual OT Credit MANUALOVERTIME_CREDIT minutes -

MANUALOVERTIME_CREDIT
Manual OT Credit HH:MM -
_HHMM

Manual OT Debit MANUALOVERTIME_DEBIT minutes -

MANUALOVERTIME_DEBIT_
Manual OT Debit HH:MM -
HHMM

Authorized OT AUTHORIZEDOVERTIME minutes -

AUTHORIZEDOVERTIME_H
Authorized OT HH:MM -
HMM

OVERTIMEAUTHORIZATION
OT Authorization Date dd/mm/yyyy -
DATE

Manual C-Off Credit MANUALCOFF_CREDIT minutes -

MANUALCOFF_CREDIT_HH
Manual C-Off Credit HH:MM -
MM

Manual C-Off Debit MANUALCOFF_DEBIT minutes -

57 Matrix COSEC Web API User Guide

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

MANUALCOFF_DEBIT_HHM
Manual C-Off Debit HH:MM -
M

Authorized C-Off AUTHORIZEDCOFF minutes -

Authorized C-Off AUTHORIZEDCOFF_HHMM HH:MM -

Authorized C-Off Date AUTHORIZEDCOFFDATE dd/mm/yyyy -

Availed C-Off AVAILEDCOFF minutes -

Availed C-Off AVAILEDCOFF_HHMM HH:MM -

Encashed C-Off ENCASHEDCOFF minutes -

Encashed C-Off ENCASHEDCOFF_HHMM HH:MM -

Lunch Duration LUNCHDURATION minutes -

Lunch Duration LUNCHDURATION_HHMM HH:MM -

Late In Lunch LATEINLUNCH minutes -

Late In Lunch LATEINLUNCH_HHMM HH:MM -

Early Out Lunch EARLYOUTLUNCH minutes -

Early Out Lunch EARLYOUTLUNCH_HHMM HH:MM -

0 : status is not WO/PH

WO and PH WEEKOFFANDHOLIDAY -
1 : status is WO/PH

Official Duration OFFICIALDURATION minutes -

Personal Duration PERSONALDURATION minutes -

Shift Start SHIFTSTART HH:MM -

Shift End SHIFTEND HH:MM -

Lunch Start LUNCHSTART HH:MM -

Lunch End LUNCHEND HH:MM -

Out Punch OUTPUNCH mm/dd/yyyy HH:MM -

Out Punch OUTPUNCH_DATE mm/dd/yyyy -

Out Punch OUTPUNCH_TIME HH:MM -

Format same as SPFID1-

Out Special Function OUTSPFID 1-10
SPFID12

Site ID SITEID 1-999 -

Minimum Work hours for Full

MINWRKHRSFDAY minutes -
day

Minimum Work hours for Full

MINWRKHRSFDAY_HHMM HH:MM -
day

Minimum Work hours for Half

MINWRKHRSHDAY minutes -
Day

Minimum Work hours for Half

MINWRKHRSHDAY_HHMM HH:MM -
day

0 : Normal
Shift Type SHIFTTYPE 0,1,2 1 : Field Break
2 : Rest Day

Matrix COSEC Web API User Guide 58

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

The summary statement

50 alpha-numeric
Summary SUMMARY for the attendance date.
characters(max)
Eg. : Absent due to late-in

0 : WO
1 : PH
Day Status DAYSTATUS -
2 : WO/PH
3 : Normal

Calculated as per Net-

Net Work Hours NETWORKHRS HH:MM work hours policy defined
for the user.

The overtime adjustment

Adjusted work hours ADJUSTEDHRS HH:MM done in month process for
less work hours correction.

Return If [Link]
In/Out Reason for Punch 1 punch_reason1 30 alphanumeric characters
blank.

In/Out Reason for Punch 2 punch_reason2 30 alphanumeric characters -

In/Out Reason for Punch 3 punch_reason3 30 alphanumeric characters -

In/Out Reason for Punch 4 punch_reason4 30 alphanumeric characters -

In/Out Reason for Punch 5 punch_reason5 30 alphanumeric characters -

In/Out Reason for Punch 6 punch_reason6 30 alphanumeric characters -

In/Out Reason for Punch 7 punch_reason7 30 alphanumeric characters -

In/Out Reason for Punch 8 punch_reason8 30 alphanumeric characters -

In/Out Reason for Punch 9 punch_reason9 30 alphanumeric characters -

In/Out Reason for Punch 10 punch_reason10 30 alphanumeric characters -

In/Out Reason for Punch 11 punch_reason11 30 alphanumeric characters -

In/Out Reason for Punch 12 punch_reason12 30 alphanumeric characters -

Example

Following are some sample cases for this API:

Sample Request:

To fetch attendance data for the current date (default):

[Link]

59 Matrix COSEC Web API User Guide

Sample Response:

UserID|UserName|ProcessDate|Punch1|Punch2|WorkingShift|LateIn|EarlyOut|Overtime|WorkTime
1|SALIM ANSARI|01/01/2013|||23|0|0|0|0
10|RAJENDRA GOSWAMI|01/01/2013|||23|0|0|0|0
1001|ANKITKUMAR SOHLIYA|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|582
1002|MEGHA H SHUKLA|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|582
1003|UMESH M TALANPURI|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|539
1004|DARSHAK B PATEL|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|541
1007|DHAVAL I PATEL|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|605
1008|MAYANK K KORAT|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|564
1009|DIPTI K RATHWA|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|544
1010|RAHUL S SHAH|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|576
1011|PARIKA S PANDEY|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|528
1012|PARIKSHIT DAS|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|602
1015|SUMEDHA A GAWARIKAR|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|533
1016|BALAJI A|01/01/2013|||GN|0|0|0|0
102|AKSHAY SHETH|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|531
1020|VAISHALI M THAKER|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|474
1022|PANDURANG D CHAUHAN|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|555
1028|SUNIL K GURNANI|01/01/2013|||GN|0|0|0|0
1030|KEYUR BHALODIYA|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|697
1038|TANMAY SHAH|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|532
<EOT>

Sample Request:

To fetch daily-attendance records for a specified date-range.

[Link]

Sample Response:

UserID|UserName|ProcessDate|Punch1|Punch2|WorkingShift|LateIn|EarlyOut|Overtime|WorkTime
1|SALIM ANSARI|01/01/2013|||23|0|0|0|0
10|RAJENDRA GOSWAMI|01/01/2013|||23|0|0|0|0
1001|ANKITKUMAR SOHLIYA|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|582
1002|MEGHA H SHUKLA|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|582
1003|UMESH M TALANPURI|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|539
1004|DARSHAK B PATEL|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|541
1007|DHAVAL I PATEL|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|605
1008|MAYANK K KORAT|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|564
1009|DIPTI K RATHWA|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|544
1010|RAHUL S SHAH|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|576
1011|PARIKA S PANDEY|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|528
1012|PARIKSHIT DAS|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|602
1015|SUMEDHA A GAWARIKAR|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|533
1016|BALAJI A|01/01/2013|||GN|0|0|0|0
102|AKSHAY SHETH|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|531
1020|VAISHALI M THAKER|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|474
1022|PANDURANG D CHAUHAN|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|555
1028|SUNIL K GURNANI|01/01/2013|||GN|0|0|0|0
1030|KEYUR BHALODIYA|01/01/2013|01/01/2013 [Link]|01/01/2013 [Link]|GS|0|0|0|697
<EOT>

Sample Request:

To fetch specific fields in response using the field-name optional argument.

[Link]
range=01012013-02012013

Matrix COSEC Web API User Guide 60

Sample Response:

UserID|firsthalf|secondhalf
1|WO|WO
10|WO|WO
1001|AB|AB
1002|AB|AB
1003|AB|PR
1004|AB|AB
1007|AB|AB
1008|AB|AB
1009|AB|AB
1010|AB|AB
1011|AB|AB
1012|AB|AB
1015|AB|AB
1016|PR|PR
102|AB|AB
1020|AB|AB
1022|AB|AB
1028|PR|PR
1030|AB|AB
<EOT>

61 Matrix COSEC Web API User Guide

Getting Monthly Attendance Data

This API allows the user to obtain attendance data for employees for a specific month and for specific user groups
in a specific format.

Action

action=get

Syntax

[Link]

Parameters

Table: Getting Monthly Attendance Data - Parameters

Argument Valid Values Mandatory Default Value Description

If “field-name” is not mentioned, then

configured “field-name” for the
respective template in ‘API Data
The list of fields is
Template’ will be fetched.
field-name mentioned in response No -
table.
User can select multiple “field-name”,
each separated by “, (comma)”
e.g.:”userid, username, orgid…”

the format shall be Current Month and The Month and Year for which the data
month-year No
mmyyyy Current Year is to be fetched.

all
organization
branch
Range of users for whom data is to be
department
fetched.
range designation No All
section
category
grade
user

Each range (except all) shall have

1 to 999 (for all the
specific id.
ranges except all &
System should allow user to select
user)
multiple id, each separated by “,
10 Char. (for user) Yes, if
(coma)” e.g.:”1, 3, 7, 9…”
Note: This is the min mentioned
id - Or
to max range. In case range is other
Select a range of id
of a system with only than ‘All’.
E.g.”1-50”.
1-50 id defined then
Note: - ID is mandatory, if mentioned
valid range shall be 1-
range is other than all.
50.

Matrix COSEC Web API User Guide 62

Response Fields

Table: Getting Monthly Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

User ID USERID 10 characters. -

User Name USERNAME 45 characters -

Short Name short_name max 15 alphanumeric characters -

Integration Reference integration_reference max 20 alphanumeric characters -

Organization ID ORGID 1-999999 -

Branch ID BRCID 1-999999 -

Department ID DPTID 1-999999 -

Section ID SECID 1-999999 -

Category ID CTGID 1-999999 -

Grade ID GRDID 1-999999 -

Designation ID DSGID 1-999999 -

Reference No. ADLUSERID numeric (8 digits) -

M : Male
Gender GENDER F: Female -
NA : Not available

M : Married
Marital Status MRTLSTAT U : Unmarried -
NA : Not available

Birth Date BIRTHDT dd/mm/yyyy -

Joining Date JOINDT dd/mm/yyyy -

Leaving Date LEAVEDT dd/mm/yyyy -

Process Year PYEAR yyyy -

Process Month PMONTH mm

Present Days PRDAYS Numeric Multiples of 0.5

Absent Days ABDAYS Numeric Multiples of 0.5

Week-Off Days WODAYS Numeric Multiples of 0.5

Public Holiday Days PHDAYS Numeric Multiples of 0.5

Paid Leave Days PLDAYS Numeric Multiples of 0.5

Tour Days TRDAYS Numeric Multiples of 0.5

Unpaid Leave Days ULDAYS Numeric Multiples of 0.5

Lay Off Days LODAYS Numeric Multiples of 0.5

Early In EARLYIN minutes -

Early In EARLYIN_HHMM HH:MM -

Late In LATEIN minutes -

Late In LATEIN_HHMM HH:MM -

Early Out EARLYOUT minutes -

Early Out EARLYOUT_HHMM HH:MM -

63 Matrix COSEC Web API User Guide

Table: Getting Monthly Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

Overstay OVERSTAY minutes -

Overstay OVERSTAY_HHMM HH:MM -

Total Overtime OVERTIME minutes -

Total Overtime hrs. OVERTIME_HHMM HH:MM -

Worktime WORKTIME minutes -

Worktime hrs. WORKTIME_HHMM HH:MM -

Manual OT Credit MANOTCR minutes -

Manual OT Credit MANOTCR_HHMM HH:MM -

Manual OT Debit MANOTDB minutes -

Manual OT Debit MANOTDB_HHMM HH:MM -

Authorized OT AUTHOT minutes -

Authorized OT AUTHOT_HHMM HH:MM -

Manual COFF Credit MANCOFFCR minutes -

Manual COFF Credit MANCOFFCR_HHMM HH:MM -

Manual COFF Debit MANCOFFDB minutes -

Manual COFF Debit MANCOFFDB_HHMM HH:MM -

Authorized COFF AUTHCOFF minutes -

Authorized COFF AUTHCOFF_HHMM HH:MM -

Availed COFF AVLCOFF minutes -

Availed COFF AVLCOFF_HHMM HH:MM -

Encashed COFF ENCCOFF minutes -

Encashed COFF ENCCOFF_HHMM HH:MM -

Shift Allowance SFTALW - -

Lunch Break. LUNCHBREAK minutes -

Lunch Break hrs. LUNCHBREAK_HHMM HH:MM -

Lunch Late LUNCHLATE minutes -

Lunch Late LUNCHLATE_HHMM HH:MM -

Lunch Early LUNCHEARLY minutes -

Lunch Early LUNCHEARLY_HHMM HH:MM -

OT for first week of

Weekly Overtime component OTW1 minutes
the month

OT for first week of

Weekly Overtime component OTW1_HHMM HH:MM
the month

OT for second week

Weekly Overtime component OTW2 minutes
of the month

OT for second week

Weekly Overtime component OTW2_HHMM HH:MM
of the month

Matrix COSEC Web API User Guide 64

Table: Getting Monthly Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

OT for third week of

Weekly Overtime component OTW3 minutes
the month

OT for third week of

Weekly Overtime component OTW3_HHMM HH:MM
the month

OT for fourth week

Weekly Overtime component OTW4 minutes
of the month

OT for fourth week

Weekly Overtime component OTW4_HHMM HH:MM
of the month

OT for fifth week of

Weekly Overtime component OTW5 minutes
the month

OT for fifth week of

Weekly Overtime component OTW5_HHMM HH:MM
the month

Week 1 Work Time WRKTIMEW1 minutes -

Week 1 Work Time WRKTIMEW1_HHMM HH:MM -

Week 2 Work Time WRKTIMEW2 minutes -

Week 2 Work Time WRKTIMEW2_HHMM HH:MM -

Week 3 Work Time WRKTIMEW3 minutes -

Week 3 Work Time WRKTIMEW3_HHMM HH:MM -

Week 4 Work Time WRKTIMEW4 minutes -

Week 4 Work Time WRKTIMEW4_HHMM HH:MM -

Week 5 Work Time WRKTIMEW5 minutes -

Week 5 Work Time WRKTIMEW5_HHMM HH:MM -

Previous Adjustment days PREVDAYS Numeric Multiples of 0.5

Previous Overtime. PREVOT minutes -

Previous Overtime hrs. PREVOT_HHMM HH:MM -

Previous Work. PREVWRKTIME minutes -

Previous Work hrs. PREVWRKTIME_HHMM HH:MM -

Previous Shift Allowance PREVSFTALW -

Net Work Time NETWORKTIME minutes -

Net Work Time NETWORKTIME_HHMM HH:MM -

Total OT1 (Actual) TOTAL_OT1 minutes -

Total OT1 (Actual) TOTAL_OT1_HHMM HH:MM -

Total OT2 (Actual) TOTAL_OT2 minutes -

Total OT2 (Actual) TOTAL_OT2_HHMM HH:MM -

Total OT3 (Actual) TOTAL_OT3 minutes -

Total OT3 (Actual) TOTAL_OT3_HHMM HH:MM -

Total OT4 (Actual) TOTAL_OT4 minutes -

65 Matrix COSEC Web API User Guide

Table: Getting Monthly Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

Total OT4 (Actual) TOTAL_OT4_HHMM HH:MM -

Total OT5 (Actual) TOTAL_OT5 minutes -

Total OT5 (Actual) TOTAL_OT5_HHMM HH:MM -

Total Authorized OT1 TOTAL_AUTH_OT1 minutes -

Total Authorized OT1 TOTAL_AUTH_OT1_HHMM HH:MM -

Total Authorized OT2 TOTAL_AUTH_OT2 minutes -

Total Authorized OT2 TOTAL_AUTH_OT2_HHMM HH:MM -

Total Authorized OT3 TOTAL_AUTH_OT3 minutes -

Total Authorized OT3 TOTAL_AUTH_OT3_HHMM HH:MM -

Total Authorized OT4 TOTAL_AUTH_OT4 minutes -

Total Authorized OT4 TOTAL_AUTH_OT4_HHMM HH:MM -

Total Authorized OT5 TOTAL_AUTH_OT5 minutes -

Total Authorized OT5 TOTAL_AUTH_OT5_HHMM HH:MM -

Example

This example presents a case where monthly-attendance records are to be fetched for Organization ID ‘1’.

Sample Request:

http:/matrixserver/[Link]/attendance-monthly?action=get;range=organization;id=1

Sample Response:

UserID|UserName|PYear|PMonth|PRDays|ABDays|WorkTime_HHMM|PLDays|TRDays
1053|JINU SAM|2013|1|21.0|0.5|15:20|2.5|0.0
1054|PARSHV SHAH|2013|1|24.0|0.0|21:13|0.0|0.0
1055|SANDIP PATEL|2013|1|15.0|6.5|56:56|2.5|0.0
1056|RITESH RAJPUT|2013|1|19.5|4.5|77:07|0.0|0.0
1057|JANPRIYA MALVIYA|2013|1|23.0|1.0|35:36|0.0|0.0
1059|PRATIK PATEL|2013|1|17.5|6.5|70:02|0.0|0.0
1060|PRIYESH SHAH|2013|1|23.5|0.0|17:13|0.5|0.0
1061|DARSHAN PATEL|2013|1|24.0|0.0|17:46|0.0|0.0
1062|MANTHAN PATEL|2013|1|23.0|0.0|13:27|1.0|0.0
895|Atul Kumar Gond|2013|1|5.0|19.0|02:41|0.0|0.0
900|Shaun Trivedi|2013|1|0.0|25.0|00:00|0.0|0.0
<EOT>

Matrix COSEC Web API User Guide 66

CHAPTER 8 Access Control

The Access Control APIs primarily support the retrieval of access route data, as configured on the COSEC server.
An Access Route on COSEC is a configured sequence in which a user is allowed access on Doors assigned to a
particular Panel device, or based on the access policy defined on a Smart Card. Access Routes can be of two types
- Panel-based access routes and Smart Card-based access routes.

The Access Control APIs enable the user to perform the following functions:

• Obtaining List of Access Routes

• Obtaining Access Route Details

Matrix COSEC Web API User Guide 67

Obtaining List of Access Routes

This API allows the user to fetch a list of all existing access routes configured on COSEC and the respective
number of group members assigned to each route.

Action

action=get

Syntax

[Link]

Parameters

Table: Obtaining List of Access Routes - Parameters

Argument Valid Values Mandatory Default Value Description

type smartcard, panel No smartcard This is the type of the access route.

1 to 99 (for smartcard) This is the route number for an access

route No all
1 to 99 (for panel) route.

Yes (only for This is the panel number of the panel

panelno 1 to 99 -
type=panel) for which the access route is defined.

Response Fields

1. For type=smartcard

Table: Obtaining List of Access Routes (Smart card) - Response Fields

Field Name Tag Name Valid Values Remarks

Access Route Number AccessRouteNumber 1 - 99 -

Access Route Name AccessRouteName 15 alphanumeric characters -

Hard/Soft HardSoft Hard, Soft -

1 : active
Active Active -
0 : inactive

1 : reset enabled
Reset On Lowest Level ResetOnLowestLevel -
0 : reset disabled

Count of configured
Group Members GroupMembers 0 - 75
members

2. For type=panel

Table: Obtaining List of Access Routes (Panel) - Response Fields

Field Name Tag Name Valid Values Remarks

Access Route Number AccessRouteNumber 1 - 99 -

Matrix COSEC Web API User Guide 68

Table: Obtaining List of Access Routes (Panel) - Response Fields

Field Name Tag Name Valid Values Remarks

Access Route Name AccessRouteName 15 alphanumeric characters -

1 : active
Active Active -
0 : inactive

1
Sequence Sequence -
0

Panel Name PanelName 30 alphanumeric characters based on panel number

1 : reset enabled
Reset On Lowest Level ResetOnLowestLevel -
0 : reset disabled

Count of configured
Group Members GroupMembers 0 - 32
members

Example

Below is a sample case where a request is raised with default values:

Sample Request:

[Link]

Sample Response:

AccessRouteNumber|AccessRouteName|HardSoft|Active|ResetOnLowestLevel|GroupMembers
1|factory|Soft|1|0|1
2|Factory|Soft|1|0|2
3|Randd|Soft|1|0|2
<EOT>

69 Matrix COSEC Web API User Guide

Obtaining Access Route Details

This API allows the user to request details of all or specific access routes configured on COSEC.

Action

action=get

Syntax

[Link]

Parameters

Table: Obtaining Access Route Details - Parameters

Argument Valid Values Mandatory Default Value Description

type smartcard, panel No smartcard This is the type of the access route.

1 to 99 (for smartcard) This is the route number for an access

route No all
1 to 99 (for panel) route.

Yes (only for This is the panel number of the panel

panelno 1 to 99 -
type=panel) for which the access route is defined.

Response Fields

1. For type=smartcard

Table: Obtaining Access Route Details (Smart card) - Response Fields

Field Name Tag Name Valid Values Remarks

Access Route ID ARID 1-99 -

MID MID 1 - 99999 -

DID DID 1 - 75 -

Panel Door, Direct Door, Direct

Door v2, NGT Direct Door,
Door Type Door Type -
Wireless Door, Compact Door,
PVR Door

Door Name Door Name 30 alphanumeric characters -

Level Level 1 - 75 -

2. For type=panel

Table: Obtaining Access Route Details (Panel) - Response Fields

Field Name Tag Name Valid Values Remarks

Access Route ID ARID 1-99 -

Member Number Member Number 1 - 32 -

Door Number Door Number 1 - 75 -

Door Name Door Name 30 alphanumeric characters -

Matrix COSEC Web API User Guide 70

Table: Obtaining Access Route Details (Panel) - Response Fields

Field Name Tag Name Valid Values Remarks

Level Level 1 - 32 -

Example

Sample Request:

[Link]

Sample Response:

ARID|MID|DID|DoorType|DoorName|Level
1|17|1|Direct Door v2||0
1|48|1|Direct Door v2||0
<EOT>

71 Matrix COSEC Web API User Guide

CHAPTER 9 Data Import and Export

The Data Templates API allows users to define a sequence in which certain specified data fields can be imported/
exported from or to external modules, such as Payroll. This chapter lists COSEC APIs that allow users to retrieve
specific import/export template-related data. These are as follows.

• Getting Export Template List

• Getting Export Template Details

• Getting Import Template List

• Getting Import Template Details

• Getting Template Data

Matrix COSEC Web API User Guide 72

Getting Export Template List

COSEC helps users to create data templates that can carry certain data specified by the user. Using this API, a
user can obtain a list of all existing export templates configured on COSEC along with their IDs, names and types.

Action

action=get

Syntax

[Link]

Parameters

Table: Getting Export Template List - Parameters

Argument Valid Values Mandatory Default Value Description

If template-type=0 , the API will return

the view name to which the template
0 : view name
belongs
template-type 1: actual template No 0 (view name)
If template-type=1, the API will return
name
the actual name of that template as
configured in COSEC Web.

Response Fields

Table: Getting Export Template List - Response Fields

Field Name Tag Name Valid Values Remarks

Template ID id 1-999 -

Name name 40 alphanumeric characters -

1: daily
2: monthly
Template-Type template-type -
3: event-ta
4: event-acs

View-ID view-id 101 - 999 -

Example

The following examples illustrate how template list is fetched with different template-type values:

Sample Request:

[Link]

73 Matrix COSEC Web API User Guide

Sample Response:

id|name
1|Daily Attendance Detail
2|Monthly Attendance Summary
3|Attendance Events
4|Access Control Events
101|Monthly Attendance Summary
102|Daily Attendance Detail
<EOT>

Sample Request:

[Link]

Sample Response:

id|name|template-type|view-id
1|API_Template_Daily|1|9
2|API_Template_Monthly|2|8
3|API_Template_ATDEvents|3|7
4|API_Template_ACSEvents|4|6
101|MONTH ATTENDANCE|2|1
102|daily|1|2
<EOT>

Matrix COSEC Web API User Guide 74

Getting Export Template Details

This API allows the user to obtain the details such as fields, their type, length, name etc. for all or specified export
templates on the COSEC database.

Action

action=get

Syntax

[Link]

Parameters

Table: Getting Export Template Details - Parameters

Argument Valid Values Mandatory Default Value Description

Export data template ID as per the

id 1 to 999 No All configured templates in COSEC Web
Application.

Specifies the list of fields to be

returned.
0 : view’s fields 0 (all fields as per the
field-list No
1 : all fields view structure) If field-list=1, return the combined list
of all the fields (fields form view +
custom fields + static fields)

Response Fields

The response will contain a list of fields defined for the specified templates. For each field the following will be
provided:

Table: Getting Export Template Details - Response Table

Field Name Tag Name Valid Values Remarks

1-100 : API Templates

Template Id id numeric 100 onwards : Export data
Templates.

Field Name field alpha-numeric as per COSEC Database.

Data Type type as per COSEC Database.

Maximum length length numeric as per COSEC Database.

Decimal decimal numeric as per COSEC Database.

0 : database field
Field type field-type 0, 1, 2 1: static field
2: custom field

0: not mandatory
Mandatory mandatory 0, 1
1: mandatory field

75 Matrix COSEC Web API User Guide

Getting Import Template List

This API can be used to fetch a list of all templates configured on the COSEC Web Application for user data import
and event import (both Access Control and Attendance events table).

• 0- User master table

• 1- Event table

Action

action=get

Syntax

[Link]

Response Fields

Table: Getting Import Template List - Response Fields

Field Name Tag Name Valid Values Remarks

As configured in COSEC
Template Id TemplateId numeric
Web Application.

As configured in COSEC
Code code alpha-numeric
Web Application.

Example

The following is a sample request-response.

Sample Request:

[Link]

Sample Response:

TemplateID|Code
1|USER
2|EVENT
<EOT>

Matrix COSEC Web API User Guide 76

Getting Import Template Details

This API enables the user to fetch the internal table structure for the user master table and events table (both
Access Control and Time and Attendance events table), indicating the fields, its data type and field length.

• 0- User master table

• 1- Event table

Action

action=get

Syntax

[Link]

Parameters

Table: Getting Import Template Details - Parameters

Argument Valid Values Mandatory Default Value Description

1 to 2

1=user template
id No all This is the template id.
schema
2=event template
schema

Response Fields

Table: Getting Import Template Details - Response Fields

Field Name Tag Name Valid Values Remarks

Field Id id numeric auto-generated

Field Name field alpha-numeric as per COSEC Database

Data Type type - as per COSEC Database

Maximum length length numeric as per COSEC Database

Decimal decimal numeric as per COSEC Database

77 Matrix COSEC Web API User Guide

Getting Template Data

This is a common API that can be used to retrieve the data for a specified template.

Action

action=get

Syntax

[Link]

Parameters

Table: Getting Template Data - Parameters

Argument Valid Values Mandatory Default Value Description

Export data template ID as per the

configured templates in COSEC Web
Application.

1- 99 : API Templates
id 1-999 Yes -
101-999 : Custom Templates

Note: For User-Defined templates use

the “Template-List” API to get the
template-id.

If it is a daily template The date range for which the data

or event export is required.
template, date range
should be :
date-range ddmmyyyy – Yes - Note: For User-Defined templates use
ddmmmyyyy the “Template-List” API to get the
For a monthly template template-type.
it should be :
mmyyyy-mmyyyy

User id for which data is required.

Multiple IDs can be selected, each
All (If neither user ID
separated by a ‘comma’.
nor any enterprise
Max 10 alphanumeric e.g.:”1, 3, 7, 9…”
userid No group ID is mentioned,
characters (for user)
all active users will be
Note : If userid is mentioned, then the
considered.)
enterprise group fields as listed below,
should not be mentioned.

organization Data for the users belonging to the

specified enterprise group and sub-
branch groups (if mentioned) will be returned.
department
Multiple IDs can be selected for the
designation specified enterprise group, each
1 to 999999
No separated by a ‘comma’.
section e.g.:”1, 3, 7, 9…”

category
Note: These parameters should not be
grade mentioned if userid is mentioned.

Matrix COSEC Web API User Guide 78

Table: Getting Template Data - Parameters

Argument Valid Values Mandatory Default Value Description

Comma separated field-names, for

which the values should be returned.
If no name is specified,
Note: For User-Defined templates use
field-name text No all the configured fields
the “Template List” and “Template
will be considered
Details” APIs to get the list of
configured templates, and their
corresponding arguments.

Response Fields

Table: Getting Template Data - Response Fields

Field Name Tag Name Valid Values Remarks

Export data template ID as

per the configured
templates in COSEC Web
Application.
Template Id template-id 1-999
1- 99 : API Templates
101-999 : Custom
Templates

Allowed characters
A-Z
User ID user-id upto 10 characters a-z
0-9
/_\\.@:

Allowed Characters
A-Z
User Name user-name upto 45 characters a-z
0-9
-_. ()[]

Fields fields - field-name : value pairs

Example

Sample Request:

[Link]

79 Matrix COSEC Web API User Guide

Sample Response:

TEMPLATE-ID|USERID|USERNAME|UserID1|UserName1|ProcessDate|Punch1|Punch2|WorkingShift|LateIn|EarlyOut|Overtime|WorkTime
1|1|SALIM ANSARI|1|SALIM ANSARI|11/02/2013|11/02/2013 [Link]|11/02/2013 [Link]|23|0|0|0|534
1|10|RAJENDRA GOSWAMI|10|RAJENDRA GOSWAMI|11/02/2013|11/02/2013 [Link]|11/02/2013 [Link]|23|0|0|0|492
1|1001|ANKITKUMAR SOHLIYA|1001|ANKITKUMAR SOHLIYA|11/02/2013|11/02/2013 [Link]|11/02/2013 [Link]|GS|0|0|0|529
1|1002|MEGHA H SHUKLA|1002|MEGHA H SHUKLA|11/02/2013|11/02/2013 [Link]|11/02/2013 [Link]|GS|0|0|0|327
1|1003|UMESH M TALANPURI|1003|UMESH M TALANPURI|11/02/2013|11/02/2013 [Link]|11/02/2013 [Link]|GS|0|0|0|524
1|1004|DARSHAK B PATEL|1004|DARSHAK B PATEL|11/02/2013|11/02/2013 [Link]|11/02/2013 [Link]|GS|0|0|0|549
1|1007|DHAVAL I PATEL|1007|DHAVAL I PATEL|11/02/2013|11/02/2013 [Link]|11/02/2013 [Link]|GS|0|0|0|612
1|1008|MAYANK K KORAT|1008|MAYANK K KORAT|11/02/2013|11/02/2013 [Link]|11/02/2013 [Link]|GS|0|0|0|635
1|1009|DIPTI K RATHWA|1009|DIPTI K RATHWA|11/02/2013|||GS|0|0|0|0
1|1010|RAHUL S SHAH|1010|RAHUL S SHAH|11/02/2013|11/02/2013 [Link]|11/02/2013 [Link]|GS|0|0|0|556
1|1011|PARIKA S PANDEY|1011|PARIKA S PANDEY|11/02/2013|11/02/2013 [Link]|11/02/2013 [Link]|GS|0|0|0|530
1|1012|PARIKSHIT DAS|1012|PARIKSHIT DAS|11/02/2013|11/02/2013 [Link]|11/02/2013 [Link]|GS|0|0|0|609
1|1015|SUMEDHA A GAWARIKAR|1015|SUMEDHA A GAWARIKAR|11/02/2013|11/02/2013 [Link]|11/02/2013 [Link]|GS|0|0|0|561
1|1016|BALAJI A|1016|BALAJI A|11/02/2013|||GN|0|0|0|0
1|1|SALIM ANSARI|1|SALIM ANSARI|12/02/2013|12/02/2013 [Link]|12/02/2013 [Link]|23|0|0|0|476
1|10|RAJENDRA GOSWAMI|10|RAJENDRA GOSWAMI|12/02/2013|12/02/2013 [Link]|12/02/2013 [Link]|23|0|0|0|495
1|1001|ANKITKUMAR SOHLIYA|1001|ANKITKUMAR SOHLIYA|12/02/2013|12/02/2013 [Link]|12/02/2013 [Link]|GS|0|0|0|548
1|1002|MEGHA H SHUKLA|1002|MEGHA H SHUKLA|12/02/2013|12/02/2013 [Link]|12/02/2013 [Link]|GS|0|0|0|563
1|1003|UMESH M TALANPURI|1003|UMESH M TALANPURI|12/02/2013|12/02/2013 [Link]|12/02/2013 [Link]|GS|0|0|0|530
1|1004|DARSHAK B PATEL|1004|DARSHAK B PATEL|12/02/2013|12/02/2013 [Link]|12/02/2013 [Link]|GS|0|0|0|553
1|1007|DHAVAL I PATEL|1007|DHAVAL I PATEL|12/02/2013|12/02/2013 [Link]|12/02/2013 [Link]|GS|0|0|0|601
1|1008|MAYANK K KORAT|1008|MAYANK K KORAT|12/02/2013|||GS|0|0|0|0
1|1009|DIPTI K RATHWA|1009|DIPTI K RATHWA|12/02/2013|||GS|0|0|0|0
1|1010|RAHUL S SHAH|1010|RAHUL S SHAH|12/02/2013|12/02/2013 [Link]|12/02/2013 [Link]|GS|0|0|0|561
1|1011|PARIKA S PANDEY|1011|PARIKA S PANDEY|12/02/2013|12/02/2013 [Link]|12/02/2013 [Link]|GS|0|0|0|538
1|1012|PARIKSHIT DAS|1012|PARIKSHIT DAS|12/02/2013|12/02/2013 [Link]|12/02/2013 [Link]|GS|0|0|0|531
1|1015|SUMEDHA A GAWARIKAR|1015|SUMEDHA A GAWARIKAR|12/02/2013|12/02/2013 [Link]|12/02/2013 [Link]|GS|0|0|0|544
1|1016|BALAJI A|1016|BALAJI A|12/02/2013|||GN|0|0|0|0
<EOT>

Matrix COSEC Web API User Guide 80

CHAPTER 10 Data Transfer

The Data Transfer API enables the COSEC system to send a user’s image/finger print template/palm template to a
third party application. It also enables the system to receive the image/finger print template/palm template for a user
and save/update it in the COSEC database.

Only a single user’s data can be sent in one request. Also, only one image/template can be transferred at a time.
The supported size limit for data transfer are as follows –

• Image – 250 kb
• FP template – 768 bytes
• Palm template – 3 kb

The generic URL for a Data transfer API is mentioned below.

Syntax

[Link]

COSEC supports the following data transfer APIs:

• Retrieving User Data

• Sending User Data

Matrix COSEC Web API User Guide 81

Retrieving User Data

This functionality enables the third party to fetch user image/finger print template/palm templates from the COSEC
database.

Action

action=get

Syntax

[Link]

Parameters

Table: Retrieving User Data - Parameters

Argument Valid Values Mandatory Default Value Description

The user identification number of the

userid Varchar(10) Yes -
user whose data is to be requested.

0: image The type of data being requested must

type 1: finger print template Yes - be specified.
2: palm template

0-9 : if it is a palm The position of the template that should

By default the template
template. be returned.
location No stored at location=0
0-9 : if it is a finger print
will be sent.
template. Valid only for FP and Palm templates.

The image/template shall be sent in API data and not in API arguments.

This API cannot be tested on a browser.

Matrix COSEC Web API User Guide 82

Sending User Data

This API can be used by a third party application to send a user’s data to the COSEC database. This user data is
subsequently saved or updated in the database.

Action

action=set

Syntax

[Link]

Parameters

Table: Sending User Data - Parameters

Argument Valid Values Mandatory Default Value Description

The user identification number of the

userid Varchar(10) Yes -
user whose data is to be sent.

0: image The type of data being sent must be

type 1: finger print template Yes - specified.
2: palm template

0-9 : if it is a palm By default, the The position where the template should
template. template will be stored be stored.
location No
0-9 : if it is a finger print at the first available
template. (empty) location for the Valid only for FP and Palm templates.
user.

Option to overwrite the template, if a

0 : no
overwrite No 0 (no) template already exists at the
1 : yes
mentioned position for the user.

An “Invalid Command” error message is returned in the following scenarios:

• If type=1 and location is other than 0-9.

• If type=2 and location is other than 0-9.

• If location specified is out of range.

• If a template already exists at the mentioned location.

• If no free locations are available.

83 Matrix COSEC Web API User Guide

CHAPTER 11 Events

The Events APIs enable users to perform the following functions:

• Adding an Event

• Obtaining Time and Attendance Events

• Obtaining Time and Attendance Events by Date

• Obtaining Access Control Events

• Obtaining Access Control Events by Date

• Obtaining Door/Alarm/System Events

Matrix COSEC Web API User Guide 84

Adding an Event

This API allows the user to add an event into COSEC for processing. This can include both time and attendance, as
well as access control events.

Action

action=set

Syntax

[Link]

Parameters

Table: Adding an Event - Parameters

Argument Valid Values Mandatory Default Value Description

ddmmyyyyhhmmss This is the date and time when the

event-datetime Yes -
format event actually happened.

This is the user id for the event. This

userid Varchar(10) Yes - will link the event with the user in
COSEC.

Valid values 0,1

This specifies whether the event is “in”
in-out 0=IN (default) Yes -
or “out” type.
1=OUT

2 digits This value specifies any special

spfid No 0
Valid range = 0-10 functions associated with the event.

This field is for information purpose

only. Here the event source details can
be specified for later identification for
event-src-details Max. 20 characters No N/A
the event. For e.g. it can mention a
source IP address from where the
event originated.

Valid values 0,1 This field will determine where the

event-type 0=attendance event No 0 event should be saved and how it is to
1=access control event be processed.

Valid values 0,1

This value will determine the access
access 0=denied (event 151) No 1 (allowed)
value for the event.
1=allowed (event 101)

1 to 65000 (panel,
panel-lite) This specifies the device MID as set in
mid No 0
1 to 65000 (direct cosec.
doors)

This specifies the device ID (DID) as

set in COSEC.
did Numeric (2,0) No 1
Note: For Direct Doors, DID will always
be 1.

85 Matrix COSEC Web API User Guide

Table: Adding an Event - Parameters

Argument Valid Values Mandatory Default Value Description

This specifies the device type, as set in

COSEC.

0 = Panel
1 = Direct Door V1
2 = Panel Lite
dtype Numeric (1,0) No 0 3 = Direct Door V2
4 = NGT Direct Door
5 = Wireless Direct Door
6 = Path Controller
7 = PVR Direct Door
8= Vega Panel-Lite
9= Vega Controller

Valid values 0,1

This field specifies that the event has
wphoto 0=no photo No 0
image associated with it or not.
1=with photo

None = 0,
PIN = 1,
Card = 2,
Card_PIN = 3,
FingerPrint = 4,
Finger_PIN = 5,
This will specify the credentials used
credentials Finger_Card = 6, No 0
for the event.
Finger_Card_PIN = 7,
Palm = 8,
Palm_PIN = 9,
Palm_Card = 10,
Palm_Card_PIN = 11,
Palm_Group = 24

0=Device
This will indicate the event source to
1=USB
the COSEC software.
2=ESS
event_src 3=SMS No 5 (Others)
Note : Specify event_src=6 when
4=PIM
Events are submitted using a Mobile
5=Others
Application.
6=APP

When event_src= 0 (Device), 1(USB) and 3(SMS) it is mandatory to specify the correct dtype, did and mid.

Matrix COSEC Web API User Guide 86

Obtaining Time and Attendance Events

This can be used to fetch a specific number of Time and Attendance events in the required format.

Action

action=get

Syntax

[Link]

Parameters

Table: Obtaining Time and Attendance Events - Parameters

Argument Valid Values Mandatory Default Value Description

If “field-name” is not
mentioned, then
The list of valid fields is Multiple field-names can be selected,
system should
mentioned in the each separated by “, (comma)”
field-name No consider configured
“Response Fields” e.g.:”indexno, userid, username,
“field-name” for the
section. orgid…”
respective template in
‘API Data Template’.

Index indicates the start point of an

event. It shall be of 15 numeric digits.
000000000000000- Response shall be provided with an
index No 0
999999999999999 error message, in case of invalid index.
The default value of index shall be 0 (in
case where the index not mentioned).

If count is not
It’s the count up to which the data is
mentioned then
required. It shall be of 3 numeric digits.
system should send
e.g. index=50, and count=100, then
count numeric No 999 (maximum value
system should provide total 100 events,
of count) events from
starting from index =50 up to index
given start point i.e.
=149
index.

Provide this to get events within a

date-range ddmmyyyy-ddmmyyyy No -
particular date range.

Response Fields

Table: Obtaining Time and Attendance Events - Response Fields

Field Name Tag Name Valid Values Remarks

Index number INDEXNO numeric 15 digits -

User ID USERID 10 characters. -

User Name USERNAME 45 characters -

Short Name short_name max 15 characters -

Organization ID ORGID 1-999999 -

Branch ID BRCID 1-999999 -

87 Matrix COSEC Web API User Guide

Table: Obtaining Time and Attendance Events - Response Fields

Field Name Tag Name Valid Values Remarks

Department ID DPTID 1-999999 -

Section ID SECID 1-999999 -

Category ID CTGID 1-999999 -

Grade ID GRDID 1-999999 -

Designation ID DSGID 1-999999 -

Reference No. ADLUSERID numeric System generated

M : Male
Gender GENDER F: Female -
NA : Not available

M : Married
Marital Status MRTLSTAT U : Unmarried -
NA : Not available

Birth Date BIRTHDT dd/mm/yyyy -

Joining Date JOINDT dd/mm/yyyy -

Leaving Date LEAVEDT dd/mm/yyyy -

Event Date and Time EVENTDATETIME dd/mm/yyyy HH:MM:SS -

Event Date and Time EVENTDATETIME_D mm/dd/yyyy HH:MM:SS -

0 : Entry
Entry/Exit Type ENTRYEXITTYPE -
1 : Exit

Master Controller ID MASTERCONTROLLERID 1-65535 Device ID

Door Controller ID DOORCONTROLLERID 1-75 -

Special Function ID SPECIALFUNCTIONID numeric -

Event ID EVENTID numeric -

0 = Panel,
1 = Direct Door,
2 = Panel Lite
3 = Direct Door V2,
4 = NGT Direct Door,
Panel/Door Type PANEL_DOOR_TYPE -
5 = Wireless Direct Door
6 = Compact Direct Door
7 = PVR Direct Door
8= Vega Panel-Lite
9= Vega Controller

Event Date EDATE dd/mm/yyyy -

Event Time ETIME HH:MM -

Insertion Date Time IDATETIME datetime as per server configuration

Site ID SITEID 1-999 -

Device Name device_name 30 alphanumeric characters -

0=controller
1=USB
2=ESS This will indicate the event
Source event_src 3=SMS source to the COSEC
4=PIM software.
5=Others
6=APP

Matrix COSEC Web API User Guide 88

Table: Obtaining Time and Attendance Events - Response Fields

Field Name Tag Name Valid Values Remarks

0 : denied
Access Allowed or Denied access_allowed -
1: allowed

When location is
calculated via GPS. This
GPS Latitude gps_ latitude 9 characters parameter will contain :
latitude
Example: -77.0081

When location is
calculated via GPS. This
GPS Longitude gps_ longitude 9 characters parameter will contain :
longitude
Example: 38.8897

When location is
calculated via GSM. This
GSM Latitude gsm_ latitude 9 characters
parameter will contain :
latitude

When location is
calculated via GSM. This
GSM Longitude gsm_ longitude 9 characters
parameter will contain :
longitude

When location is
calculated via Wi-Fi. This
MAC Address mac_address 17 characters
parameter will contain :
MAC Address of source

Not mandatory. If not

mentioned, default-value
will be online=1 (Online)
0 : Offline
Event Online/Offline Status online_status To be sent by Mobile
1 : Online
Applications to differentiate
in online and offline
events.

Example

Calling T&A events with default values.

Sample Request:

[Link]

Sample Response:

IndexNo|UserID|UserName|EventDateTime|EntryExitType|MasterControllerID|DoorControllerID|SpecialFunctionID|LeaveDT|IDateTime
33|1|sam|01/10/2011 [Link]|0|1|1|0||10/01/2011 [Link]
34|1|sam|03/10/2011 [Link]|0|1|1|0||10/03/2011 [Link]
35|2|hardik|03/10/2011 [Link]|0|1|1|0||10/03/2011 [Link]
36|3|shwetang|03/10/2011 [Link]|0|1|1|0||10/03/2011 [Link]
37|9|home|26/07/2012 [Link]|0|0|0|0||07/26/2012 [Link]
38|9|home|26/07/2012 [Link]|0|0|0|0||07/26/2012 [Link]
39|9|home|26/07/2012 [Link]|0|0|0|0||07/26/2012 [Link]
40|9|home|26/07/2012 [Link]|0|0|0|0||07/26/2012 [Link]
<EOT>

89 Matrix COSEC Web API User Guide

Obtaining Time and Attendance Events by Date

This API is similar to “Obtaining Time and Attendance Events”. However, in this case, the Time and Attendance
events can be obtained for a specified date range.

Action

action=get

Syntax

[Link]

Parameters

Table: Obtaining Time and Attendance Events by Date - Parameters

Argument Valid Values Mandatory Default Value Description

If “field-name” is not
mentioned, then
The list of valid fields is Multiple field-names can be selected,
system should
mentioned in the each separated by “, (comma)”
field-name No consider configured
“Response Fields” e.g.:”indexno, userid, username,
“field-name” for the
section. orgid…”
respective template in
‘API Data Template’.

ddmmyyyyhhmmss- This is date-range. T&A events stored

date-range ddmmyyyyhhmmss Yes - in the specified date-range will be
fetched.

Response Fields

Table: Obtaining Time and Attendance Events by Date - Response Fields

Field Name Tag Name Valid Values Remarks

Index number INDEXNO numeric 15 digits -

User ID USERID 10 characters. -

User Name USERNAME 45 characters -

Short Name short_name max 15 alphanumeric characters -

Organization ID ORGID 1-999999 -

Branch ID BRCID 1-999999 -

Department ID DPTID 1-999999 -

Section ID SECID 1-999999 -

Category ID CTGID 1-999999 -

Grade ID GRDID 1-999999 -

-
Designation ID DSGID 1-999999

Reference No. ADLUSERID numeric System generated

M : Male
Gender GENDER F: Female -
NA : Not available

Matrix COSEC Web API User Guide 90

Table: Obtaining Time and Attendance Events by Date - Response Fields

Field Name Tag Name Valid Values Remarks

M : Married
Marital Status MRTLSTAT U : Unmarried -
NA : Not available

Birth Date BIRTHDT dd/mm/yyyy -

Joining Date JOINDT dd/mm/yyyy -

Leaving Date LEAVEDT dd/mm/yyyy -

Event Date and Time EVENTDATETIME dd/mm/yyyy HH:MM:SS -

Event Date and Time EVENTDATETIME_D datetime as per server configuration

0 : Entry
Entry/Exit Type ENTRYEXITTYPE -
1 : Exit

Master Controller ID MASTERCONTROLLERID 1-65535 Device ID

Door Controller ID DOORCONTROLLERID 1-75 -

Special Function ID SPECIALFUNCTIONID numeric -

Event ID EVENTID numeric -

0 = Panel,
1 = Direct Door,
2 = Panel Lite
3 = Direct Door V2,
4 = NGT Direct Door,
Panel/Door Type PANEL_DOOR_TYPE -
5 = Wireless Direct Door
6 = Compact Direct Door
7 = PVR Direct Door
8= Vega panel-lite
9= Vega Controller

Event Date EDATE dd/mm/yyyy -

Event Time ETIME HH:MM -

Insertion Date Time IDATETIME datetime as per server configuration

Site ID SITEID 1-999 -

Device Name device_name Max 30 alphanumeric character -

0=controller
1=USB
2=ESS This will indicate the event
Source event_src 3=SMS source to the cosec
4=PIM software.
5=Others
6=APP

0 : denied
Access Allowed or Denied access_allowed -
1: allowed

When location is
calculated via GPS. This
GPS Latitude gps_ latitude 9 characters parameter will contain :
latitude
Example: -77.0081

When location is
calculated via GPS. This
GPS Longitude gps_longitude 9 characters parameter will contain :
longitude
Example: 38.8897

91 Matrix COSEC Web API User Guide

Table: Obtaining Time and Attendance Events by Date - Response Fields

Field Name Tag Name Valid Values Remarks

When location is
calculated via GSM. This
GSM Latitude gsm_latitude 9 characters
parameter will contain :
latitude

When location is
calculated via GSM. This
GSM Longitude gsm_longitude 9 characters
parameter will contain :
longitude

When location is
calculated via Wi-Fi. This
MAC Address mac_address 17 characters
parameter will contain :
MAC Address of source

Not mandatory. If not

mentioned, default-value
0 : Offline will be online=1 (Online)
Event Online/Offline Status online_status
1 : Online To be sent by ESS APPs
to differentiate in online
and offline events.

Example

This example presents a case where no time-attendance records are available for the specified date range.

Sample Request:

[Link]

Sample Response:

success : No records found

Matrix COSEC Web API User Guide 92

Obtaining Access Control Events

This can be used to get a specific number of Access Control events (All events other than Time and Attendance
events) in the required format.

Action

action=get

Syntax

[Link]

Parameters

Table: Obtaining Access Control Events - Parameters

Argument Valid Values Mandatory Default Value Description

If “field-name” is not
mentioned, then
The list of valid fields is Multiple field-names can be selected,
system should
mentioned in the each separated by “, (comma)”
field-name No consider configured
“Response Fields” e.g.:”indexno, userid, username,
“field-name” for the
section. orgid…”
respective template in
‘API Data Template’.

Index indicates the start point of an

event. It shall be of 15 numeric digits.
000000000000000-
index No 0
999999999999999
The default value of index shall be 0 (in
case where the index not mentioned)

If count is not
It’s the count up to which the data is
mentioned then
required. It shall be numeric digits.
system will send 999
e.g. index=50, and count=100, then
count numeric No (maximum value of
system should provide total 100 events,
count) events from
starts from index =50 up to index =149
given start point i.e.
index.

Provide this to get events within a

date-range ddmmyyyy-ddmmyyyy No -
particular date range.

Response Fields

Table: Obtaining Access Control Events - Response Fields

Field Name Tag Name Valid Values Remarks

Index number INDEXNO numeric 15 digits -

Allowed characters
A-Z
User ID USERID 10 characters. a-z
0-9
/_\\.@:

93 Matrix COSEC Web API User Guide

Table: Obtaining Access Control Events - Response Fields

Field Name Tag Name Valid Values Remarks

Allowed Characters
A-Z
User Name USERNAME 45 characters a-z
0-9
-_. ()[]

Short Name short_name max 15 alphanumeric characters -

Event Date and Time EVENTDATETIME dd/mm/yyyy HH:MM:SS -

Event Date and Time EVENTDATETIME_D datetime as per server configuration

0 : Entry
Entry/Exit Type ENTRYEXITTYPE -
1 : Exit

Master Controller ID MASTERCONTROLLERID 1-65535 Device ID

Door Controller ID DOORCONTROLLERID 1-75 -

Special Function ID SPECIALFUNCTIONID numeric -

Event ID EVENTID numeric -

0 = Panel,
1 = Direct Door,
2 = Panel Lite
3 = Direct Door V2,
4 = NGT Direct Door,
Panel/Door Type PANEL_DOOR_TYPE -
5 = Wireless Direct Door
6 = Compact Direct Door
7 = PVR Direct Door
8= Vega panel-lite
9= Vega Controller

Event Date EDATE dd/mm/yyyy -

Insertion Date Time IDATETIME datetime as per server configuration

Site ID SITEID 1-999 -

Organization ID ORGID 1-999999 -

Branch ID BRCID 1-999999 -

Department ID DPTID 1-999999 -

Section ID SECID 1-999999 -

Category ID CTGID 1-999999 -

Grade ID GRDID 1-999999 -

-
Designation ID DSGID 1-999999

Device Name device_name Max 30 alphanumeric character

0=controller
1=USB
2=ESS This will indicate the event
Source event_src 3=SMS source to the cosec
4=PIM software.
5=Others
6=APP

Event Time ETIME HH:MM -

0 : denied
Access Allowed or Denied access_allowed -
1: allowed

Matrix COSEC Web API User Guide 94

Table: Obtaining Access Control Events - Response Fields

Field Name Tag Name Valid Values Remarks

When location is
calculated via GPS. This
GPS Latitude gps_ latitude 9 characters parameter will contain :
latitude
Example: -77.0081

When location is
calculated via GPS. This
GPS Longitude gps_longitude 9 characters parameter will contain :
longitude
Example: 38.8897

When location is
calculated via GSM. This
GSM Latitude gsm_latitude 9 characters
parameter will contain :
latitude

When location is
calculated via GSM. This
GSM Longitude gsm_longitude 9 characters
parameter will contain :
longitude

When location is
calculated via Wi-Fi. This
MAC Address mac_address 17 characters
parameter will contain :
MAC Address of source

Not mandatory. If not

mentioned, default-value
will be online=1 (Online)
0 : Offline
Event Online/Offline Status online_status To be sent by Mobile
1 : Online
Applications to differentiate
in online and offline
events.

Example

For default values,

Sample Request:

[Link]

Sample Response:

IndexNo|UserID|UserName|EventDateTime|EntryExitType|MasterControllerID|DoorControllerID|IDateTime
30904|555013|KRISHNANAND SHIVRATAN PAL|23/02/2013 [Link]|0|48|1| 30905|555013|KRISHNANAND SHIVRATAN PAL|23/02/
2013 [Link]|0|48|1|
30906|8515|KARANSINGH DILBAHADUR DHAMI|23/02/2013 [Link]|0|48|1|
30907|8699|RAJIV RANJAN PRAKASH SINGH|23/02/2013 [Link]|0|48|1|
30908|8515|KARANSINGH DILBAHADUR DHAMI|23/02/2013 [Link]|0|48|1|
30909|8515|KARANSINGH DILBAHADUR DHAMI|23/02/2013 [Link]|0|48|1| 30910|555013|KRISHNANAND SHIVRATAN PAL|23/02/
2013 [Link]|0|48|1|
30911|8515|KARANSINGH DILBAHADUR DHAMI|23/02/2013 [Link]|0|48|1|
30912|8699|RAJIV RANJAN PRAKASH SINGH|23/02/2013 [Link]|0|48|1|
30913|8699|RAJIV RANJAN PRAKASH SINGH|23/02/2013 [Link]|0|48|1|
30914|555013|KRISHNANAND SHIVRATAN PAL|25/02/2013 [Link]|0|48|1|

95 Matrix COSEC Web API User Guide

Obtaining Access Control Events by Date

This API is similar to “Obtaining Access Control Events”. However, in this case, the Access Control events can be
obtained for a specified date range.

Action

action=get

Syntax

[Link]

Parameters

Table: Obtaining Access Control Events by Date - Parameters

Argument Valid Values Mandatory Default Value Description

If “field-name” is not
mentioned, then
The list of valid fields is Multiple field-names can be selected,
system should
mentioned in the each separated by “, (comma)”
field-name No consider configured
“Response Fields” e.g.:”indexno, userid, username,
“field-name” for the
section. orgid…”
respective template in
‘API Data Template’.

ddmmyyyyhhmmss- This is date-range. Access Control

date-range ddmmyyyyhhmmss Yes - events stored in the specified date-
range will be fetched.

Response Fields

Table: Obtaining Access Control Events by Date - Response Fields

Field Name Tag Name Valid Values Remarks

Index number INDEXNO numeric 15 digits -

Allowed characters
A-Z
User ID USERID upto 10 characters. a-z
0-9
/_\\.@:

Allowed Characters
A-Z
User Name USERNAME upto 45 characters a-z
0-9
-_. ()[]

Short Name short_name max 15 alphanumeric characters -

Event Date and Time EVENTDATETIME dd/mm/yyyy HH:MM:SS -

Event Date and Time EVENTDATETIME_D datetime as per server configuration

0 : Entry
Entry/Exit Type ENTRYEXITTYPE -
1 : Exit

Master Controller ID MASTERCONTROLLERID 1-65535 Device ID

Door Controller ID DOORCONTROLLERID 1-75 -

Matrix COSEC Web API User Guide 96

Table: Obtaining Access Control Events by Date - Response Fields

Field Name Tag Name Valid Values Remarks

Special Function ID SPECIALFUNCTIONID numeric -

Event ID EVENTID numeric -

0 = Panel,
1 = Direct Door,
2 = Panel Lite
3 = Direct Door V2,
4 = NGT Direct Door,
Panel/Door Type PANEL_DOOR_TYPE -
5 = Wireless Direct Door
6 = Compact Direct Door
7 = PVR Direct Door
8= Vega panel-lite
9= Vega Controller

Event Date EDATE dd/mm/yyyy -

Insertion Date Time IDATETIME datetime as per server configuration

Site ID SITEID 1-999 -

Organization ID ORGID 1-999999 -

Branch ID BRCID 1-999999 -

Department ID DPTID 1-999999 -

Section ID SECID 1-999999 -

Category ID CTGID 1-999999 -

Grade ID GRDID 1-999999 -

-
Designation ID DSGID 1-999999

Device Name device_name Max 30 alphanumeric character

0=controller
1=USB
2=ESS This will indicate the event
Source event_src 3=SMS source to the cosec
4=PIM software.
5=Others
6=APP

Event Time ETIME HH:MM -

0 : denied
Access Allowed or Denied access_allowed -
1: allowed

When location is
calculated via GPS. This
GPS Latitude gps_ latitude 9 characters parameter will contain :
latitude
Example: -77.0081

When location is
calculated via GPS. This
GPS Longitude gps_longitude 9 characters parameter will contain :
longitude
Example: 38.8897

When location is
calculated via GSM. This
GSM Latitude gsm_latitude 9 characters
parameter will contain :
latitude

97 Matrix COSEC Web API User Guide

Table: Obtaining Access Control Events by Date - Response Fields

Field Name Tag Name Valid Values Remarks

When location is
calculated via GSM. This
GSM Longitude gsm_longitude 9 characters
parameter will contain :
longitude

When location is
calculated via Wi-Fi. This
MAC Address mac_address 17 characters
parameter will contain :
MAC Address of source

Not mandatory. If not

mentioned, default-value
will be online=1 (Online)
0 : Offline
Event Online/Offline Status online_status To be sent by Mobile
1 : Online
Applications to differentiate
in online and offline
events.

Example

The following example illustrates a case where no records of access control events are present in the given date
range.

Sample Request:

[Link]

Sample Response:

IndexNo|UserID|UserName|EventDateTime|EntryExitType|MasterControllerID|DoorControllerID|IDateTime
1890|112|PARESH CHAUHAN|01/01/2012 [Link]|0|4|1|01/01/2012 [Link]
1921|443|BHARGAV M PATEL|02/01/2012 [Link]|0|4|1|01/02/2012 [Link]
1923|112|PARESH CHAUHAN|02/01/2012 [Link]|0|4|1|01/02/2012 [Link]
1924|621|patel vishal H|02/01/2012 [Link]|0|4|1|01/02/2012 [Link]
1925|521|PRAVINSINH GANPATSINH CHAUHAN|02/01/2012 [Link]|0|4|1|01/02/2012 [Link]
1926|489|KADIR I MANSURI|02/01/2012 [Link]|0|4|1|01/02/2012 [Link]
1927|424|VIMAL S TADVI|02/01/2012 [Link]|0|4|1|01/02/2012 [Link]
1928|684|JADAV MAYUR G|02/01/2012 [Link]|0|4|1|01/02/2012 [Link]
1929|449|CHINTAN A VARU|02/01/2012 [Link]|0|4|1|01/02/2012 [Link]
1930|644|Dhramesh Thakkar|02/01/2012 [Link]|0|4|1|01/02/2012 [Link]
1931|496|MILAN TRIVEDI|02/01/2012 [Link]|0|4|1|01/02/2012 [Link]
1932|515|KAMLESH KANUBHAI PARMAR|02/01/2012 [Link]|0|4|1|01/02/2012 [Link]
1933|498|RAVINDRA RAJPUT|02/01/2012 [Link]|0|4|1|01/02/2012 [Link]
1934|686|Saikh Sajid Usmanbhai|02/01/2012 [Link]|0|4|1|01/02/2012 [Link]
1935|514|BABU MANSUKHBHAI PALASH|02/01/2012 [Link]|0|4|1|01/02/2012 [Link]
1936|417|RAJESH P MACHHI|02/01/2012 [Link]|0|4|1|01/02/2012 [Link]
1937|434|KISHOR SOLANKI|02/01/2012 [Link]|0|4|1|01/02/2012 [Link]
1938|5|AMBALAL PADHIYAR|02/01/2012 [Link]|0|4|1|01/02/2012 [Link]
1940|4|DEVENDRA L MACHHI|02/01/2012 [Link]|0|4|1|01/02/2012 [Link]

Matrix COSEC Web API User Guide 98

Obtaining Door/Alarm/System Events

This will be used to fetch the COSEC door, alarm and system events for a specified date range. The date should be
insertion date and all the events that are offline and yet to be inserted will be left out.

Action

action=get

Syntax

[Link]

Parameters

Table: Obtaining Door/Alarm/System Events - Parameters

Argument Valid Values Mandatory Default Value Description

If type=1. The response should contain

all door events. Event ID range : 201-
299
0: all (default)
if type=2. The response should contain
1: door
type No 0 (all) all alarm events. Event ID range : 301-
2: alarm
399
3. system
if type=3. The response should contain
all system events. Event ID range :
401-499

This is the event date-range. Events

stored in the specified date-range will
be fetched.
ddmmyyyyhhmmss-
date-range Yes -
ddmmyyyyhhmmss Note: - The events that have already
occurred, but are yet to be inserted, will
not be returned. The record should be
requested again at a later stage.

Response Fields

Table: Obtaining Door/Alarm/System Events - Response Fields

Field Name Tag Name Valid Values Remarks

Master Controller ID mid 1-65535 Device MID

Door Controller ID did 1-75 -

0: all (default)
1: door
Event Type type -
2: alarm
3. system

Site ID siteid 1-999 -

Event Date and Time eventdatetime dd/mm/yyyy HH:MM:SS -

door events: 201-299

Event ID eventid alarm events: 301-399 -
system events: 401-499

99 Matrix COSEC Web API User Guide

Table: Obtaining Door/Alarm/System Events - Response Fields

Field Name Tag Name Valid Values Remarks

Field-1 can be User ID for

event 401 . But
Event Field field-1 As per configuration
Transaction ID for event
403.

Event Field field-2 As per configuration -

Event Field field-3 As per configuration -

Events 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

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

Matrix COSEC Web API User Guide 100

Table: List of Events

Event ID Event Description

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

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

101 Matrix COSEC Web API User Guide

Table: List of Events

Event ID Event Description

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

• Response will not contain the following alarm events :

- 351 : Alarm acknowledged

- 352 : Alarm cleared

• The status changes are not registered as new events, as they are being updated against the current
event itself.

The events returned will be ordered according to the date-time of the event (edatetime)

Matrix COSEC Web API User Guide 102

CHAPTER 12 Sending Commands to
Device

This API can be used to send a command to a COSEC device from a third-party application. Certain commands
can be sent directly to devices to initiate specific actions. The following commands can be sent to a COSEC device
via API:

• Set Date-Time - Sends the current system date and time to the device.

• Normalize Door/Lock Door/Unlock Door - Sends the appropriate commands to the DOOR to reset the
door lock status.

• Delete FP - Sends command to delete the fingerprints (FP) from the fingerprint module of a device.

• Sync Credentials - Sends command to synchronize credentials from the PANEL to the DOORs. It is
recommended to first send the delete fingerprints command to the DOORs before starting the
synchronizing process for finger print templates.

• Clear All Alarms - Sends the command to clear all alarms configured on the COSEC system.

• Factory Defaults - Sends the command to default the device settings to the default factory settings.

• Delete Palms - Sends command to delete the palm templates from a palm vein reader device.

Action

action=command

Syntax

[Link]

Parameters

Table: Sending Commands to Device - Parameters

Argument Valid Values Mandatory Default Value Description

1 to 65000
(panel, panel-lite)
device-id Yes - This is the device identification number.
1 to 65000
(direct doors)

Matrix COSEC Web API User Guide

Table: Sending Commands to Device - Parameters

Argument Valid Values Mandatory Default Value Description

This is the type of device to which

command is to be sent.

Here,

0 = Panel,
0,1,2,3,4,5,6,7,8,9 1 = Direct Door V1,
device-type Yes - 2 = Panel Lite
3 = Direct Door V2,
4 = NGT Direct Door,
5 = Wireless Direct Door
6 = Path Controller
7 = PVR Direct Door
8 = Vega Panel-Lite
9 = Vega Controller

Vaild only when command is to be sent

to a Panel Door.

Note: If this value is not specified with

Panel-door-no 1 to 75 No -
device type 0 or 2 then the
interpretation is that the command is
intended for the corresponding Panel or
Panel-lite.

1 - set date-time
2 - normalize door
3 - lock door
4 - unlock door
5 - delete FP (clears all
command-type Yes - To specify a command.
finger prints)
6 - sync credentials
7 - clear all alarms
8 - factory defaults
9 - delete palms

Applicable device-commands based on device-type:

a) Panel: Applicable Commands: 1, 7, 8

b) Panel Door: Applicable Commands: 2 - 7 and 9 (if it is a PVR Door)

c) Direct Door: Applicable Commands: 1 - 5, 7, 8 and 9 (if it is a PVR Door)

Example

The following is an example of a command sent to a panel door for credentials synchronization:

Sample Request:

[Link]
no=1;command-type=6;

Sample Response:

success: Command received successfully

Matrix COSEC Web API User Guide 104

Now, in the next example, a command is sent to the same device to clear all alarms.

Sample Request:

[Link]
no=1;command-type=7;

Sample Response:

failed: No alarms to clear

In this case, the selected device has no alarms to be cleared.

105 Matrix COSEC Web API User Guide

CHAPTER 13 User Count on Device

Request the total count of users assigned on a device by specifying the device type and device ID.

Action

action=get

Syntax

[Link]

Parameters

Table: User Count on Device - Parameters

Argument Valid Values Mandatory Default Value Description

1 to 65000
(panel, panel-lite)
device-id Yes - This is the device identification number.
1 to 65000
(direct doors)

This is the type of device to which

command is to be sent.

Here,

0 = Panel,
0,1,2,3,4,5,6,7,8,9 1 = Direct Door V1,
device-type Yes - 2 = Panel Lite
3 = Direct Door V2,
4 = NGT Direct Door,
5 = Wireless Direct Door
6 = Path Controller
7 = PVR Direct Door
8 = Vega Panel-Lite
9 = Vega Controller

Example

The following is an example of a request sent to “matrixserver” to obtain the user count for a Direct Door V2 with
device-id=1,

Sample Request:

[Link]

Matrix COSEC Web API User Guide

Sample Response:

DeviceID|DeviceName|UserCount|TotalUserCapacity
11|RnD Basement V2|464|2000
<EOT>

107 Matrix COSEC Web API User Guide

CHAPTER 14 Error Responses

The called HTTP request shall be parsed by the system before it returns an appropriate response depending on the
nature of success or failure. Some common response messages are as follows:

• If a request is successful:

<success: successful>

• If an argument is mentioned but no value is provided:

<failed: Incomplete command :“[argument-name]=”>

• If any unexpected arguments are encountered or for other syntax errors:

<failed: Invalid syntax :“#”>

• For incorrect argument values:

<failed: Invalid command :“[argument-name]=*”>

• If a mandatory argument is missing:

<failed: Incomplete command :“#”>

• “ * ” Specifies the value mentioned in the request against its respective arguments.

• “ # ” specifies the entire request string.

Example

The following examples illustrate some common error response cases that the user may encounter when sending
an HTTP query:

Error Request:

Argument action mentioned but no value given.

[Link]

Matrix COSEC Web API User Guide 108

Error Response:

Request failed: Incomplete command : action=

Error Request:

• Invalid type (invalid value).

[Link]

Error Response:

Request failed: Invalid command : type=paneldoor123

Error Request:

• Invalid range.

[Link]

Error Response:

Request failed: Invalid command : device=g_1-g_9

Error Request:

• Mandatory fields not mentioned.

[Link]

Error Response:

Request failed: Incomplete command : userid=

109 Matrix COSEC Web API User Guide

SECURITY SOLUTIONS

MATRIX COMSEC PVT. LTD.

Corporate Office:
394-GIDC, Makarpura, Vadodara - 390010, India.
Ph.:+91 265 2630555, Fax: +91 265 2636598
E-mail: Info@[Link]

Manufacturing Unit:
15 & 19 GIDC, Waghodia - 391760, Dist. Vadodara, India.
Ph.: +91 2668 263172/73

Customer Care:
Ph.: +91 265 2630555
E-mail: [Link]@[Link], Support@[Link]

[Link]