COSEC Web API

User Guide

SECURITY SOLUTI ONS

 SECURITY SOLUTIONS

COSEC Web API 2.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 27
Release date: March 28, 2023
 Contents
List of Tables ........................................................................................................................................................ i

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

API Overview................................................................................................................................................... 3

Devices .......................................................................................................................................................... 19
Getting a Device List ......................................................................................................................................... 20
Assigning Users to Device ................................................................................................................................ 23
Revoking Users from Device ............................................................................................................................. 26
Adding a New Device ........................................................................................................................................ 28
Deleting a Device .............................................................................................................................................. 33
Obtaining Device List with Status ...................................................................................................................... 35
Updating Device Configuration ......................................................................................................................... 37
Getting a Device Group ..................................................................................................................................... 42
Adding a New Device Group ............................................................................................................................. 44

Sites ............................................................................................................................................................... 45
Obtaining Data on Existing Sites ....................................................................................................................... 46
Adding a New Site ............................................................................................................................................. 48
Updating a Site .................................................................................................................................................. 49

Users ............................................................................................................................................................. 51
Accessing User Data ......................................................................................................................................... 53
Adding/Editing a User ....................................................................................................................................... 65
Adding User Photograph ................................................................................................................................... 83
Deleting a User ................................................................................................................................................. 85
Enrolling a User ................................................................................................................................................. 87
Setting Credentials on Device ........................................................................................................................... 89
Deleting Credentials from Device ...................................................................................................................... 91
Searching a User .............................................................................................................................................. 93
Fetching Reporting Group Members ................................................................................................................. 99

Enterprise Structure ................................................................................................................................... 101

Obtaining Enterprise Group Details ................................................................................................................ 103
Adding an Enterprise Group ............................................................................................................................ 105
Updating Enterprise Group Details ................................................................................................................. 106
Obtaining Custom Group details ..................................................................................................................... 108
Adding Custom Group details ......................................................................................................................... 110
Updating Custom Enterprise Group ................................................................................................................ 111

Time and Attendance.................................................................................................................................. 113

Getting Daily Attendance Data ........................................................................................................................ 115
Getting Monthly Attendance Data ................................................................................................................... 137
Getting Attendance Correction Details ............................................................................................................ 145
Applying for Attendance Correction ................................................................................................................ 153
Deleting Attendance Correction Applications .................................................................................................. 156
Approving Attendance Correction ................................................................................................................... 157
Getting Short Leave/Official IN-OUT Entries ................................................................................................... 159
Making Short Leave/Official IN-OUT Entries ................................................................................................... 166
Short Leave/Official In-Out Authorization ........................................................................................................ 169
Getting Attendance Records for Authorization ................................................................................................ 171
Authorizing Attendance ................................................................................................................................... 178
 Getting Event Records for Authorization ......................................................................................................... 179
Authorizing Events .......................................................................................................................................... 185
Getting Overtime/C-OFF Authorization Records ............................................................................................. 186
Authorizing Overtime/C-OFF ........................................................................................................................... 206
Processing Monthly Attendance ...................................................................................................................... 208
In/Out Reasons ............................................................................................................................................... 210
Getting Shift Wise Count ................................................................................................................................. 211
Getting Site Wise Count .................................................................................................................................. 213
Getting Shift-Site Wise Count ......................................................................................................................... 215
Getting Site Wise User Detail .......................................................................................................................... 216
Getting Overtime Application .......................................................................................................................... 218
Setting Overtime Application ........................................................................................................................... 223
Updating Overtime Application ........................................................................................................................ 224
Deleting Overtime Application ......................................................................................................................... 225
Overtime Approval .......................................................................................................................................... 226

Leave Management..................................................................................................................................... 227

Getting Leave Balance Details ........................................................................................................................ 228
Getting Leave Group Details ........................................................................................................................... 231
Getting Leave Details ...................................................................................................................................... 235
Getting Leave Application Details ................................................................................................................... 238
Setting Leave Balance .................................................................................................................................... 249
Applying for a Leave ....................................................................................................................................... 252
Updating an Applied Leave ............................................................................................................................. 255
Deleting a Pending Application ....................................................................................................................... 258
Approving/Rejecting Leaves ........................................................................................................................... 259
Getting C-OFF Balance Details ....................................................................................................................... 260
Getting C-OFF Details ..................................................................................................................................... 262

Access Control ........................................................................................................................................... 265

Obtaining List of Access Routes ..................................................................................................................... 266
Obtaining Access Route Details ...................................................................................................................... 268

Cafeteria Management ............................................................................................................................... 271

Getting Account Details ................................................................................................................................... 272
Getting Expenditure Summary ........................................................................................................................ 275
Getting Menu Details ....................................................................................................................................... 277
Getting List of Cafeteria Devices ..................................................................................................................... 279
Getting Menu Schedules ................................................................................................................................. 280
Getting Correction Application Details ............................................................................................................ 282
Making a Correction Application ..................................................................................................................... 285
Updating a Correction Application ................................................................................................................... 287
Deleting a Correction Application .................................................................................................................... 288
Getting Expenditure Details ............................................................................................................................ 289

Data Import and Export .............................................................................................................................. 293

Getting Export Template List ........................................................................................................................... 294
Getting Export Template Details ..................................................................................................................... 296
Getting Import Template List ........................................................................................................................... 297
Getting Import Template Details ..................................................................................................................... 298
Getting Template Data .................................................................................................................................... 299

Data Transfer............................................................................................................................................... 309

Retrieving User Data ....................................................................................................................................... 311
Sending User Data .......................................................................................................................................... 315
Deleting User Data .......................................................................................................................................... 319
Events .......................................................................................................................................................... 323
Adding an Event .............................................................................................................................................. 324
Obtaining Time and Attendance Events .......................................................................................................... 329
Obtaining Time and Attendance Events by Date ............................................................................................ 338
Obtaining Access Control Events .................................................................................................................... 343
Obtaining Access Control Events by Date ...................................................................................................... 349
Obtaining Door/Alarm/System Events ............................................................................................................. 354
Obtaining Visitor Events .................................................................................................................................. 358

Sending Commands to Device .................................................................................................................. 361

User Count on Device ................................................................................................................................ 365

Notifications ................................................................................................................................................ 367

Retrieving Notifications ................................................................................................................................... 368
Deleting Notifications ...................................................................................................................................... 370

Login User Details ...................................................................................................................................... 371

Password..................................................................................................................................................... 379

Encryption Key ........................................................................................................................................... 383

IMEI Registration ........................................................................................................................................ 385

Location Master .......................................................................................................................................... 387

COSEC Server Details ................................................................................................................................ 391

Field Visit Management .............................................................................................................................. 395

Getting Field Visit Schedule ............................................................................................................................ 396
Getting Field Visit Punches ............................................................................................................................. 399
Getting Field Visit Correction .......................................................................................................................... 402
Applying for Field Visit Correction ................................................................................................................... 409
Authorizing Field Visit Correction Applications ................................................................................................ 411
Deleting Field Visit Correction Application ...................................................................................................... 413

Job Processing and Costing ..................................................................................................................... 415

Getting Jobs list ............................................................................................................................................... 416
Timesheet details ............................................................................................................................................ 419
Get Timesheet Correction Application ............................................................................................................ 422
Job Costing Process ....................................................................................................................................... 428
Timesheet Correction Application ................................................................................................................... 429
Timesheet Correction Authorization ................................................................................................................ 432

Visitor Management.................................................................................................................................... 433

Getting Vehicle Types ..................................................................................................................................... 436
Getting Visitor Types ....................................................................................................................................... 438
Getting Visit Types .......................................................................................................................................... 440
Getting Visitor Pre-registration details ............................................................................................................. 442
Visitor Pre-registration Application .................................................................................................................. 455
Updating Visitor Pre-registration Application ................................................................................................... 460
Deleting Visitor Pre-registration application .................................................................................................... 464
Getting Additional Visitors details .................................................................................................................... 466
Adding Additional Visitor details ...................................................................................................................... 467
Updating Additional Visitor details ................................................................................................................... 469
Deleting Additional Visitor details .................................................................................................................... 470
Visitor Pre-registration Approval ..................................................................................................................... 471
Visitor Registration .......................................................................................................................................... 473
 Getting Authorized Host User ......................................................................................................................... 480
Getting VMS Setting ........................................................................................................................................ 483
Setting VMS Configuration .............................................................................................................................. 485
Getting Host Unavailability Days ..................................................................................................................... 487
Set Host Unavailability Days ........................................................................................................................... 489
Update Host Unavailability Days ..................................................................................................................... 490
Delete Host Unavailability Days ...................................................................................................................... 492
Getting Visitor Details ...................................................................................................................................... 493
Set Visitor Details ............................................................................................................................................ 497
Deleting Visitor Details .................................................................................................................................... 501
Getting Visitor Profile ...................................................................................................................................... 502
Setting Visitor Profile ....................................................................................................................................... 509
Deleting Visitor Profile ..................................................................................................................................... 519
Getting Invite Visitor Application Details ......................................................................................................... 520
Sending the Invite Visitor Link ......................................................................................................................... 525
Visitor Invites Approval .................................................................................................................................... 528
Set Security Approval ...................................................................................................................................... 531
Set Visit State .................................................................................................................................................. 532
System Account User ...................................................................................................................................... 534
OTP Verification .............................................................................................................................................. 535
Tenant Identifier API ....................................................................................................................................... 537

Contract Worker Management................................................................................................................... 539

Getting Contractor Types ................................................................................................................................ 540
Set Contractor Types ...................................................................................................................................... 544
Delete Contractor Types ................................................................................................................................. 548
Getting Work -Order Details ............................................................................................................................ 549
Setting Work-Order ......................................................................................................................................... 551
Delete Work-Order .......................................................................................................................................... 554
Getting Worker Details .................................................................................................................................... 555
Setting Worker Details .................................................................................................................................... 565
Deleting Worker Details .................................................................................................................................. 578

Integrate Alert API...................................................................................................................................... 579

Alerting COSEC Server ................................................................................................................................... 580

Multiple APIs Call....................................................................................................................................... 583

API Response.............................................................................................................................................. 585

Response Messages ....................................................................................................................................... 585
Response Codes ............................................................................................................................................. 586

Symptoms ................................................................................................................................................... 591

Health Declaration ...................................................................................................................................... 593

Custom Field ............................................................................................................................................... 601

Mark Group Attendance ............................................................................................................................. 605

GET APIs ........................................................................................................................................................ 606
SET APIs ......................................................................................................................................................... 607
DELETE APIs .................................................................................................................................................. 609

Group FR Process ...................................................................................................................................... 611

 List of Tables
Table: URL Structure ........................................................................................................................................9
Table: Fetching Fields in Response ...............................................................................................................12
Table: Common Arguments............................................................................................................................14
Table: Supported APIs....................................................................................................................................16
Table: Getting a Device List - Parameters......................................................................................................20
Table: Getting a Device List - Response fields...............................................................................................20
Table: Assigning Users to Device - Parameters .............................................................................................23
Table: Assigning Users to Device - Parameters .............................................................................................26
Table: Adding a New Device - Parameters.....................................................................................................28
Table: Deleting a Device - Parameters...........................................................................................................33
Table: Obtaining Device Status - Parameters ................................................................................................35
Table: Getting a Device List with Status - Response fields ............................................................................35
Table: Getting a Device Group - Parameters .................................................................................................42
Table: Getting a Device Group - Response fields ..........................................................................................43
Table: Adding a New Device Group - Parameters..........................................................................................44
Table: Obtaining Data on Existing Sites - Parameters ...................................................................................46
Table: Obtaining Data on Existing Sites - Response Fields ...........................................................................46
Table: Adding a New Site - Parameters .........................................................................................................48
Table: Updating a Site - Parameters ..............................................................................................................49
Table: Accessing User Data - Parameters .....................................................................................................53
Table: Accessing User Data - Response Fields .............................................................................................54
Table: Adding/Editing a User - Parameters ....................................................................................................65
Table: Adding User Photograph - Parameters................................................................................................83
Table: Deleting a User - Parameters ..............................................................................................................85
Table: Enrolling a User - Parameters .............................................................................................................87
Table: Setting Credentials on Device - Parameters........................................................................................89
Table: Deleting Credentials from Device - Parameters ..................................................................................91
Table: Searching a User - Parameters ...........................................................................................................93
Table: Searching a User - Response Fields ...................................................................................................95
Table: Fetching Reporting Group Members - Parameters..............................................................................99
Table: Fetching Reporting Group Members - Response Fields ...................................................................100
Table: Obtaining Enterprise Group Details - Parameters .............................................................................103
Table: Obtaining Enterprise Group Details - Response Fields .....................................................................103
Table: Adding an Enterprise Group - Parameters ........................................................................................105
Table: Updating Enterprise Group Details - Parameters ..............................................................................106
Table: Getting Custom Enterprise Group - Parameters................................................................................108
Table: Getting Custom Enterprise Group - Response Fields .......................................................................108
Table: Adding an Enterprise Group - Parameters ........................................................................................110
Table: Getting Daily Attendance Data - Parameters.....................................................................................115
Table: Getting Daily Attendance Data - Response Fields ............................................................................116
Table: Getting Monthly Attendance Data - Parameters ................................................................................137
Table: Getting Monthly Attendance Data - Response Fields........................................................................138
Table: Getting Attendance Correction Details - Parameters.........................................................................146
Table: Getting Attendance Correction Details - Response Fields ................................................................147
Table: Applying for Attendance Correction - Parameters .............................................................................153
Table: Deleting Attendance Correction Applications - Parameters...............................................................156
Table: Approving Attendance Correction - Parameters ................................................................................157
Table: Getting Short Leave/Official IN-OUT Entries - Parameters ...............................................................159
Table: Getting Short Leave/Official IN-OUT Entries - Response Fields .......................................................161
Table: Making Short Leave/Official IN-OUT Entries - Parameters ...............................................................166
Table: Short Leave/Official In-Out Authorization - Parameters.....................................................................169
Table: Getting Attendance Records for Authorization - Parameters.............................................................171
Table: Getting Attendance Records for Authorization - Response Fields ....................................................173
Table: Authorizing Attendance - Parameters................................................................................................178
Table: Getting Event Records for Authorization - Parameters......................................................................179
Table: Getting Event Records for Authorization - Response Fields .............................................................181
Table: Authorizing Events - Parameters .......................................................................................................185
Table: Getting Overtime/C-OFF Authorization Records - Parameters .........................................................186
Table: Getting Overtime/C-OFF Authorization Records - Response Fields .................................................188
Table: Authorizing Overtime/C-OFF - Parameters .......................................................................................206
Table: Processing Monthly Attendance - Parameters ..................................................................................208
Table: In/Out Reasons - Response Fields....................................................................................................210
Table: Getting Shift Wise Count- Parameters...............................................................................................211
Table: Getting Shift Wise Count- Response Fields ......................................................................................212
Table: Obtaining Data on Existing Sites - Parameters .................................................................................213
Table: Obtaining Data on Existing Sites - Response Fields .........................................................................214
Table: Getting Shift-Site Wise Count- Parameters .......................................................................................215
Table: Getting Shift-Site Wise Count- Response Fields ...............................................................................215
Table: Getting Site Wise User Details - Parameters.....................................................................................216
Table: Getting Site Wise User Details - Response Fields ............................................................................217
Table: Getting Overtime Application Data - Parameters...............................................................................218
Table: Getting Overtime Application Data - Response Fields ......................................................................219
Table: Setting Overtime Application Data - Parameters ...............................................................................223
Table: Updating Overtime Application Data - Parameters............................................................................224
Table: Deleting Overtime Application Data - Parameters .............................................................................225
Table: Overtime Approval- Parameters ........................................................................................................226
Table: Getting Leave Balance Details - Parameters.....................................................................................228
Table: Getting Leave Balance Details - Response Fields ............................................................................229
Table: Getting Leave Group Details - Parameters........................................................................................231
Table: Getting Leave Group Details - Response Fields ...............................................................................232
Table: Getting Leave Details - Parameters...................................................................................................235
Table: Getting Leave Details - Response Fields ..........................................................................................235
Table: Getting Leave Application Details - Parameters ................................................................................238
Table: Getting Leave Application Details - Response Fields........................................................................240
Table: Setting Leave Balance Leave - Parameters ......................................................................................249
Table: Applying for a Leave - Parameters ....................................................................................................252
Table: Updating an Applied Leave - Parameters..........................................................................................255
Table: Deleting a Pending Application - Parameters ....................................................................................258
Table: Approving/Rejecting Leaves - Parameters ........................................................................................259
Table: Getting C-OFF Balance Details - Parameters ...................................................................................260
Table: Getting C-OFF Balance Details - Response Fields ...........................................................................260
Table: Getting C-OFF Details - Parameters .................................................................................................262
Table: Getting C-OFF Details - Response Fields .........................................................................................263
Table: Obtaining List of Access Routes - Parameters ..................................................................................266
Table: Obtaining List of Access Routes (Smart card) - Response Fields.....................................................266
Table: Obtaining List of Access Routes (Panel) - Response Fields .............................................................267
Table: Obtaining Access Route Details - Parameters ..................................................................................268
Table: Obtaining Access Route Details (Smart card) - Response Fields .....................................................268
Table: Obtaining Access Route Details (Panel) - Response Fields..............................................................268
Table: Getting Cafeteria Account Details - Parameters................................................................................272
Table: Getting Cafeteria Account Details - Response Fields........................................................................273
Table: Getting Cafeteria Expenditure Summary - Parameters .....................................................................275
Table: Getting Cafeteria Expenditure Summary - Response Fields .............................................................276
Table: Getting Menu Details - Parameters ...................................................................................................277
Table: Getting Menu Details - Response Fields ...........................................................................................277
Table: Getting Menu Schedules - Parameters..............................................................................................280
Table: Getting Menu Schedules - Response Fields .....................................................................................281
Table: Getting Correction Application Details - Parameters .........................................................................282
Table: Getting Correction Application Details - Response Fields .................................................................283
Table: Making a Correction Application - Parameters ..................................................................................285
Table: Updating a Correction Application - Parameters ...............................................................................287
Table: Deleting a Correction Application - Parameters.................................................................................288
Table: Getting e-Canteen Expenditure Details - Parameters .......................................................................289
Table: Getting e-Canteen Expenditure Details - Response Fields ...............................................................290
Table: Getting Export Template List - Parameters .......................................................................................294
Table: Getting Export Template List - Response Fields ...............................................................................294
Table: Getting Export Template Details - Parameters ..................................................................................296
Table: Getting Export Template Details - Response Table ..........................................................................296
Table: Getting Import Template List - Response Fields ...............................................................................297
Table: Getting Import Template Details - Parameters ..................................................................................298
Table: Getting Import Template Details - Response Fields ..........................................................................298
Table: Getting Template Data - Parameters.................................................................................................299
Table: Getting Template Data - Response Fields.........................................................................................301
Table: Retrieving User Data - Parameters....................................................................................................311
Table: Sending User Data - Parameters.......................................................................................................315
Table: Deleting User Data - Parameters.......................................................................................................319
Table: Adding an Event - Parameters...........................................................................................................324
Table: Obtaining Time and Attendance Events - Parameters ......................................................................329
Table: Obtaining Time and Attendance Events - Response Fields ..............................................................330
Table: Obtaining Time and Attendance Events by Date - Parameters .........................................................338
Table: Obtaining Time and Attendance Events by Date - Response Fields.................................................338
Table: Obtaining Access Control Events - Parameters ................................................................................343
Table: Obtaining Access Control Events - Response Fields ........................................................................344
Table: Obtaining Access Control Events by Date - Parameters ...................................................................349
Table: Obtaining Access Control Events by Date - Response Fields...........................................................349
Table: Obtaining Door/Alarm/System Events - Parameters .........................................................................354
Table: Obtaining Door/Alarm/System Events - Response Fields .................................................................354
Table: List of Events .....................................................................................................................................355
Table: Obtaining Visitor Events - Parameters...............................................................................................358
Table: Sending Commands to Device - Parameters ....................................................................................362
Table: User Count on Device - Parameters..................................................................................................365
Table: Retrieving Notifications - Parameters ................................................................................................368
Table: Retrieving Notifications - Response Fields ........................................................................................368
Table: Deleting Notifications - Parameters ...................................................................................................370
Table: Getting Login User’s Details - Response Fields ................................................................................371
Table: Changing Password - Parameters.....................................................................................................379
Table: Generating Password - Parameters ..................................................................................................381
Table: Getting Password Encryption Key - Response Fields .......................................................................383
Table: IMEI Number Registration - Parameters............................................................................................385
Table: Location Master - Parameters ...........................................................................................................388
Table: Location Master- Response...............................................................................................................388
Table: Getting COSEC Server’s Details - Response Fields .........................................................................391
Table: Getting Field Visit Schedule Records- Parameters ...........................................................................396
Table: Getting Field Visit Schedule Records - Response Fields ..................................................................397
Table: Getting FVM Punches- Parameters...................................................................................................399
Table: FVM Punches - Response Fields ......................................................................................................400
Table: Getting Field Visit Correction Application Details- Parameters..........................................................402
Table: Getting Field Visit Correction Application Details - Response Fields ................................................403
Table: Applying for Field Visit Correction Application- Parameters ..............................................................409
Table: Authorizing Field Visit Correction Application- Parameters ...............................................................411
Table: Deleting Field Visit Correction Application- Parameters ....................................................................413
Table: Getting jobs list- Parameters .............................................................................................................416
Table: Getting Jobs List - Response Fields ..................................................................................................417
Table: Timesheet correction authorization- Parameters...............................................................................419
Table: Timesheet correction authorization- Response Fields.......................................................................420
Table: Timesheet correction application- Parameters ..................................................................................422
Table: Timesheet correction application- Response Fields ..........................................................................424
Table: Process job costing- Parameters.......................................................................................................428
Table: Timesheet correction application- Parameters ..................................................................................429
Table: Timesheet correction authorization- Parameters...............................................................................432
Table: Getting Vehicle type- Parameters......................................................................................................436
Table: Getting Vehicle type - Response Fields.............................................................................................436
Table: Visitor Type- Parameters ...................................................................................................................438
Table: Visitor Type- Response Fields...........................................................................................................438
Table: Getting Visit Type- Parameters..........................................................................................................440
Table: Getting Visit type - Response Fields..................................................................................................440
Table: Getting Visitor Pre-registration details- Parameters ..........................................................................442
Table: Getting Visitor Pre-registration details - Response Fields .................................................................445
Table: Visitor Pre-registration application- Parameters ................................................................................455
Table: Updating Visitor Pre-registration details- Parameters........................................................................460
Table: Deleting Visitor Pre-registration application- Parameters ..................................................................464
Table: Getting Additional Visitor details- Parameters ...................................................................................466
Table: Getting Additional Visitor details - Response Fields ..........................................................................466
Table: Adding Additional Visitor details- Parameters....................................................................................467
Table: Updating Additional Visitor details- Parameters ................................................................................469
Table: Deleting Additional Visitor details- Parameters..................................................................................470
Table: Visitor Pre-registration approval- Parameters....................................................................................471
Table: Visitor Registration- Parameters........................................................................................................473
Table: Getting Authorized Host Users- Parameters .....................................................................................480
Table: Authorized Host Users - Response Fields.........................................................................................481
Table: Getting VMS Setting- Parameters .....................................................................................................483
Table: Getting VMS Setting - Response Fields ............................................................................................483
Table: Setting VMS Configuration- Parameters............................................................................................485
Table: Getting Host Unavailability Days- Parameters...................................................................................487
Table: Getting Host Unavailability Days - Response Fields .........................................................................487
Table: Set Host Unavailability Days- Parameters.........................................................................................489
Table: Update Host Unavailability Days- Parameters...................................................................................490
Table: Delete Host Unavailability Days- Parameters....................................................................................492
Table: Getting Visitor Details- Parameters ...................................................................................................493
Table: Getting Visitor Details - Response Fields ..........................................................................................494
Table: Set Visitor Details- Parameters..........................................................................................................497
Table: Delete Visitor Details- Parameters.....................................................................................................501
Table: Getting Visitor Profile- Parameters ....................................................................................................502
Table: Getting Visitor Profile - Response Fields ...........................................................................................503
Table: Getting Invite Visitor Details - Parameters.........................................................................................520
Table: Set Invite Visitor- Parameters ............................................................................................................525
Table: Set Visitor Invites Approval- Parameters ...........................................................................................528
Table: Set Security Approval- Parameters ...................................................................................................531
Table: Set Visit State- Parameters ...............................................................................................................532
Table: System Account User - Response Fields ..........................................................................................534
Table: OTP Verification- Parameters............................................................................................................535
Table: Tenant Identifier API- Parameters .....................................................................................................537
Table: Tenant Identifier API - Response Fields ............................................................................................537
Table: Getting Contractor type- Parameters.................................................................................................540
Table: Getting Contractor type - Response Fields........................................................................................540
Table: Deleting Visit Type- Parameters ........................................................................................................548
Table: Getting Work Order Details- Parameters...........................................................................................549
Table: Getting Work Order Details - Response Fields..................................................................................549
Table: Setting Work Order- Parameters .......................................................................................................551
Table: Deleting Work Order- Parameters .....................................................................................................554
Table: Getting Worker details- Parameters ..................................................................................................555
Table: Getting Worker details - Response Fields .........................................................................................556
Table: Setting Worker details- Parameters...................................................................................................565
Table: Sending Integrate Alert to COSEC Server - Parameters...................................................................580
Table: Multiple APIs Call- Parameters..........................................................................................................583
Table: API Codes..........................................................................................................................................586
Table: Action Codes .....................................................................................................................................588
Table: Category and Actual Response Codes..............................................................................................588
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 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
• HTTPs: Hypertext Transfer Protocol Secure
• 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.

Matrix COSEC Web API User Guide 1

 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.

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 34 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.
• User rights required.
• 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 28 provides a detailed description of the API response structure.

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

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/ HTTPs API.

2 Matrix COSEC Web API User Guide

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/
HTTPs 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 independent 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/HTTPs to raise a request for the relevant employee records in a specific format.

Thus, COSEC APIs are communicative interfaces that provide effective back-end 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/HTTPs APIs.

• Use basic HTTP/HTTPs Request-Response for interface communication.

• Generate response in either text, XML or JSON 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).

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

Matrix COSEC Web API User Guide 3

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/HTTPs request-response communication

• XML/JSON

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 for the API user on the COSEC Web server.

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

Enabling API Access

COSEC APIs are applicable to any COSEC login user with the appropriate access rights. For COSEC login users
with necessary access rights, the respective login credentials (Username and Password) can be used for API
authentication.

The COSEC server will require Basic Authentication using the login user’s credentials.

API access rights for login user will depend on the following criteria:

Login User Type

COSEC login users may be of two kinds -

• System Account users (e.g. system administrator, system engineer etc.) - These users have login rights to
the COSEC Web application and their page access rights will depend on their role configuration. API

4 Matrix COSEC Web API User Guide

 access for any System Account user can be enabled by a system administrator using the COSEC Web
Application.

Fig. COSEC Login Users

• ESS users (e.g. An employee) - These users have login rights only on the ESS application. ESS users can
be distinguished into Reporting In-charge and Reporting Group members, based on hierarchy. Page
access rights of an ESS user will depend on whether he is a Reporting In-charge or a Reporting Group
member. Users with activated ESS accounts and the ESS module license are enabled for API access by
default.

For ESS users linked with a System Account (e.g. a reporting in-charge who is also a system administrator), the
ESS/System Account credentials can be provided depending on the required API user rights.

License Type

To invoke an API, the user must have the necessary module license for relevant pages on the COSEC Web
Application. For e.g., to retrieve attendance data for a specified month, the login user must have a Time and
Attendance module license.

For more information on the COSEC application modules and licenses, please refer to the COSEC Manual
in your software installation kit. For license requirement of each API, See “Supported APIs” on page 15.

Page Access Rights

Login users must have access rights on the appropriate pages of the COSEC Web Application to use related APIs.
For e.g., to apply for a leave, the user must have rights on the following page:

For System Account User: Leave Management > Application/Approval > Leave Application

For ESS User: ESS > Leave Management > Leave Application

To view page access rights for an API, refer to the User Rights section for the particular API.

Device-wise Rights

Device-wise rights will be required for all APIs which involve COSEC devices in the request to be sent. For the
action=get method, only those device records will be returned on which the login user has device rights. However,
all Event APIs will be exceptions for this verification.

Matrix COSEC Web API User Guide 5

HTTP/HTTPs Request-Response
Basic HTTP/HTTPs communication is based on a request-response paradigm. The message structure for both
request and response has a generic format. The maximum character support for request URL= 2086.

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 availability 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 argument, 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. The Response Codes defined by Matrix
will remain constant. For the response format of COSEC Web APIs, See “API Response” on page 585.

6 Matrix COSEC Web API User Guide

Request Format

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

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

separated by a space:

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

1. Request Line • The requested URL

• The HTTP version to use

For e.g.:

GET http://matrixserver/api.svc/v2/device?action=get 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 http://matrix.com/ HTTP/1.0

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

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

VERSION-HTTP CODE EXPLANATION<crlf>

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

Matrix COSEC Web API User Guide 7

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/HTTPs status code as illustrated in the
following sample response:

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

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

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

Syntax

http://<servername>/api.svc/v2/<request-type>?action=<value>;<argument>=<value>...

https://<servername>/api.svc/v2/<request-type>?action=<value>;<argument>=<value>...

Example: http://192.168.104.12/cosec/api.svc/v2/user?action=get;id=101;
or
https://192.168.104.12/cosec/api.svc/v2/user?action=get;id=101;

The current API version requires an additional version parameter (mandatory) to be mentioned in the
request URL. To know more, See “API Versions” on page 15.

8 Matrix COSEC Web API User Guide

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.

Note:

• All HTTP commands are in plain text, and almost all HTTP requests are sent
http:// using TCP port 80, though any port can be used.
https://
• When SSL encryption is being used, use the “HTTPS” element in the URL.
Default port for SSL communication is 443. However, if any other port is used
(say, “3012”), it must be mentioned in the URL following the IP address or
domain name, separated by a “colon”, as shown below:

https://192.168.1.1:3012/cosec/api.svc/v2/...

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 192.168.1.1/cosec. Then a generic
HTTP query would look like:
<servername>
http://192.168.1.1/cosec/api.svc/v2/...

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

api.svc 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.

Matrix COSEC Web API User Guide 9

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:

http://matrixserver/api.svc/v2/device?action=get;type=panel

https://matrixserver/api.svc/v2/device?action=get;type=panel

Sample Response:

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

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
• JSON

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,

http://matrixserver/api.svc/v2/device?action=get;type=door;format=text

Sample Response:

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

10 Matrix COSEC Web API User Guide

Sample Request:

To get response in XML,

http://matrixserver/api.svc/v2/device?action=get;type=door;format=xml

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

http://<servername>/api.svc/v2/schema/<request-type>?<argument>=<value>;<argument>=<value>...

https://<servername>/api.svc/v2/schema/<request-type>?<argument>=<value>;<argument>=<value>...

The valid arguments for this request are action and format.

Example

Sample Request:

http://matrixserver/api.svc/v2/schema/user?action=get;format=xml

Matrix COSEC Web API User Guide 11

Sample Response:

Fetching Fields in Response

Users can request specific fields to be returned in the response for all APIs using the action=get method. To filter
the return values for an API request, use the following argument:

Table: Fetching Fields in Response

Argument Valid Values Mandatory Default Value Description

Specify a ‘comma’ separated list of

fields that are to be returned for the
request.

Note: Not applicable for the following

List of return/output All the usual fields will request-types:
field-name field names No be returned, if not
(depending on API) specified. • attendance-daily
• attendance-monthly
• event-ta
• event-ta-date
• event-acs
• event-acs-date

Example

In this sample request, the user requests a list of all paneldoors on the COSEC database with their respective
names and IDs.

Sample Request:

http://matrixserver/api.svc/v2/device?action=get;type=paneldoor;field-name=name,id

Sample Response:

name|id
Main Entry 1|p_3
CDC PD HO|p_3
Acct-Purch|p_4
Production 1|p_4
QC|p_4
Production- 2|p_4
Factory Admin|p_4
Factory Store|p_4
Factory Support|p_4
<EOT>

12 Matrix COSEC Web API User Guide

 If a field-name is requested multiple times (e.g: field-name = id,name,id), then it will appear multiple times
in the response with a number attached to the tag. (e.g. <id>, <name>, <id1> )

Multi-Language Support
• N - Multi-Language characters are not allowed
• Y (Set 1) - Multi-Language characters allowed except Set 1 (` ~ # % ^ * = { } | \ ; " ' < > ?)
• Y (Set 2) - Multi-Language characters allowed except Set 1 (` ~ # % ^ & * = + { } [ ] | \ : ; " ' < > ? /)
• Y (Set 3) - Multi-Language characters allowed except Set 1 (` ~ # % ^ * = + { } | \ : ; " < > ?)
• Y (NA) - Multi-Language characters allowed except the ones that are restricted in API interface.

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

Example:

http://matrixserver/user?action=get;id=1234;id=5678;format=xml

In this case, id = 5678 will be considered.

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

• For all APIs using the set/update methods, sending null (or blank) values will be allowed for non-
mandatory fields. Based on the corresponding page behavior, the API behavior will differ as follows:

i. If null value is allowed for an argument, then it will be stored as null (or blank).
Example: “http://....;reason= “ will overwrite existing value for reason and set it as null (or blank)

ii. If a default value is defined internally, then that default value will be stored for the parameter
Example: http://....;gender= “ will overwrite existing value for gender and set it as “na” (because “na” is
default value for gender)

iii. If blank value is not permitted, an error message will be returned.

Example: “http://....;short-name= “ will return message : “failed: Short name cannot be blank.”

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

• ‘# (hash)’ is also not allowed in the API URL.

• To support special characters used in existing parameters, an option to Encode URL is provided. Third
party apps can encode the URL using standard encoding functions such as :

• JAVA : URLEncoder.encode(url,"UTF-8")
• JavaScript : encodeURIComponent(url)
• ASP .NET : System.Web.HttpUtility.UrlEncode(url)

• Where ‘url’ implies the portion : <request-type>?<argument>=<value>;<argument>=<value>...

Matrix COSEC Web API User Guide 13

 If the URL is encoded, then an encode flag (“encode?”) must be provided in the HTTP Request URL, to
indicate that the server should decode the incoming URL.

Example: http://matrixserver/cosec/api.svc/v2/encode?/<request
type>?<argument>=<value>;<argument>=<value>...

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.

Other Common Arguments

These arguments are also common to all the APIs defined here. If any exception exists then it will be explicitly men-
tioned with the corresponding API.

Table: Common Arguments

Argument Valid Values Mandatory Default Value Description

If format is not mentioned then consider

as "text" format.
format Text, xml, json - -
Note: In case of JSON format, the
response will contain all the "tags" in
lower case.

This argument can be used to filter the

return values of an API request. This
argument is eligible only for action=get
type APIs.

User has to specify a COMMA

separated list of fields that are to be
returned for the request.
List of return/output field
Field-name names (depending on - - If a field-name is requested multiple
API) times (e.g: field-name = id,name,id),
then it will appear multiple times in the
response with a number attached to the
tag. (e.g. <id>, <name>, <id1>)

Note: It is not applicable for

Attendance-Daily, attendance-monthly,
Event-TA, Event-TA-Date, Event-ACS,
Event-ACS-Date.

14 Matrix COSEC Web API User Guide

Table: Common Arguments

Argument Valid Values Mandatory Default Value Description

0 : For any API, if alias names are

configured for a response field-name,
then in the response, the tags will be
0 : alias shown
ignore-alias - - same as the alias names.
1: alias ignored
1: Alias will be ignored. The tag will be
exactly as specified in the Response
Table

0 : Blank
1: COSEC Mobile Apps
To specify the source for the API
api-source 2 : PIM - 0
request.
3 : Third Party App
4 : Device

General Data Protection Regulation (GDPR)

General Data Protection Regulation (GDPR) aims in providing safety and privacy to a users data. They limit the
access to a users personal data.

To know more about GDPR, refer COSEC System Manual.

If you have enabled/disabled GDPR in COSEC Web Server > Admin > System Configuration > Global Policy >
Basic then, whenever any API request is hit to the server, while the GDPR process is ongoing, the server will
respond with the below mentioned response code.

Response Code - GDPR

• Response Code= 0000002007
Return message: "failed: 0000002007: Server access denied"

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.

API Versions
For COSEC Web APIs, different versions are maintained to differentiate among existing APIs being used by third-
party applications, and any changes or revisions made. The current version is COSEC Web API Version 2.0 and
supports additional features and functions as compared to COSEC Web API Version 1.0.

Some feature-wise additions in COSEC Web API V2.0:

• Access Rights added for ESS users.

• Response Codes based on Response categories
• User rights and Device rights verification for each API.

Matrix COSEC Web API User Guide 15

To know more about the supported APIs in V1.0 and V2.0, see the table below.

Table: Supported APIs

Supported APIs V1.0 V2.0

Getting a Device List Yes Yes

Assigning Users to Devices Yes Yes

Revoking Users from Device Yes Yes

Adding a New Device Yes Yes

Deleting a Device Yes Yes

Obtaining Device Status Yes Yes

Updating Device Configuration Yes Yes

Obtaining Data on Existing Sites Yes Yes

Adding a New Site No Yes

Updating a Site No Yes

Accessing User Data Yes Yes

Adding/Editing a User Yes Yes

Adding User Photograph Yes Yes

Deleting a User Yes Yes

Enrolling a User Yes Yes

Setting Credentials on Device Yes Yes

Deleting Credentials from Device Yes Yes

Searching a User No Yes

Fetching Reporting Group Members No Yes

Obtaining Enterprise Group Details Yes Yes

Obtaining List of Renamed Groups Yes No *

Adding an Enterprise Group No Yes

Updating an Enterprise Group No Yes

Getting Daily Attendance Details Yes Yes

Getting Monthly Attendance Details Yes Yes

Getting Attendance Correction Details No Yes

Applying for Attendance Correction No Yes

Deleting Attendance Correction Applications No Yes

Approving Attendance Correction No Yes

Getting Short Leave/Official IN-OUT Entries No Yes

Making Short Leave/Official IN-OUT Entries No Yes

Short Leave/Official IN-OUT Authorization No Yes

Getting Attendance Records for Authorization No Yes

Authorizing Attendance No Yes

Getting Overtime/C-OFF Authorization Records No Yes

Authorizing Overtime/C-OFF No Yes

Processing Monthly Attendance No Yes

16 Matrix COSEC Web API User Guide

Table: Supported APIs

Supported APIs V1.0 V2.0

In/Out Reasons No Yes

Getting Shift Schedules of Users No Yes

Getting Shift Details No Yes

Getting Holiday Schedule No Yes

Getting Leave Balance Details No Yes

Getting Leave Group Details No Yes

Getting Leave Details No Yes

Getting Leave Application Details No Yes

Applying for a Leave No Yes

Updating an Applied Leave No Yes

Deleting a Pending Application No Yes

Approving/Rejecting Leaves No Yes

Getting C-OFF Balance Details No Yes

Getting C-OFF Details No Yes

Obtaining List of Access Routes Yes Yes

Obtaining Access Route Details Yes Yes

Getting e-Canteen Account Details No Yes

Getting e-Canteen Expenditure Summary No Yes

Getting e-Canteen Menu Details No Yes

Getting List of e-Canteen Devices No Yes

Getting e-Canteen Menu Schedules No Yes

Getting Correction Application Details No Yes

Making a Correction Application No Yes

Updating a Correction Application No Yes

Deleting a Correction Application No Yes

Getting e-Canteen Expenditure Details No Yes

Getting Export Template List Yes Yes

Getting Export Template Details Yes Yes

Getting Import Template List Yes Yes

Getting Import template Details Yes Yes

Getting Template Data Yes Yes

Retrieving User Data Yes Yes

Sending User Data Yes Yes

Deleting User Data No Yes

Adding an Event Yes Yes

Obtaining Time and Attendance Event Details Yes Yes

Obtaining Time and Attendance Event Details

Yes Yes
(By Date)

Obtaining Access Control Event Details Yes Yes

Matrix COSEC Web API User Guide 17

Table: Supported APIs

Supported APIs V1.0 V2.0

Obtaining Access Control Event Details (By

Yes Yes
Date)

Obtaining Door/Alarm/System Event Details Yes Yes

Sending Commands to Device Yes Yes

Getting User Count on Devices Yes Yes

Retrieving Notifications No Yes

Deleting Notifications No Yes

Login User Details No Yes

Changing Password No Yes

Encryption Key No Yes

IMEI Registration No Yes

COSEC Server Details No Yes

Field Visit Management No Yes

Job Processing and Costing No Yes

Visitor Management No Yes

Integrate Alert No Yes

* This API is no longer supported V2.0 onwards. If this API is called, the response will simply return the original group names.

To use the APIs supported in Version 2.0, it is mandatory to mention the version number in the request URL.

Example:

http://<servername>/api.svc/v2/<request-type>?action=<value>;<argument>=<value>...

18 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

http://<servername>/api.svc/v2/device?action=<method>;<argument>=<value>...

The Devices API allows you to perform the following functions:

Devices
• Getting a Device List

• Assigning Users to Device

• Revoking Users from Device

• Adding a New Device

• Deleting a Device

• Obtaining Device List with Status

• Updating Device Configuration

Device Group

• Getting a Device Group

• Adding a New Device Group

User Rights

User Rights

System Account Enabled.

User must have rights on following pages (COSEC Web Application):

Devices > Device List (For action=get)

Devices > Device Configuration (For other methods).

ESS Enabled if user has ESS rights enabled (for action=get only).

Matrix COSEC Web API User Guide 19

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

http://<servername>/api.svc/v2/device?action=get;<argument>=<value>...

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

Records will be fetched only for those devices on which the login user has device rights.

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

This is the category of

door, panel, group, paneldoor devices for which
Type type
members are to be
fetched.

20 Matrix COSEC Web API User Guide

Table: Getting a Device List - Response fields

Field Name Tag Name Valid Values Remarks

0 = Panel
1 = Door V1
2 = Panel Lite
3 = Door V2
4 = NGT Direct Door
5 = Wireless Direct Door
6 = Path Controller
7 = PVR Direct Door
Device Type device-type 8 = Panel200 This is the device type.
9 = Vega Controller
11 = ARC Controller
12 = Door V3
15 = Door FMX
19 = Door V4
17= ARC DC200
20 = ARGO
21 = ARGO FACE

Only for type=door and

type=paneldoor
0 = Advanced Access Control
Application Type application-type 1 = Basic Access Control
Note: e-Canteen devices
2 = e-Canteen
can also be fetched.

For Panels:0
1-255 (device-type=8) For Direct Doors:1
Door ID did
0-99 (All Others) For Panel Doors: As
Configured

IP Address ip - -

RS-485 is applicable only

RS-485 Address rs-485 -
for panel doors.

MAC Address mac - -

Example

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

Sample Request:

http://matrixserver/api.svc/v2/device?action=get

Sample Response:

id|name|siteid|type|device-type|application-type
d_6|RnD 1st Flr|1|door|1|0
d_8|RnD 3rd Flr|1|door|1|0
d_11|Rnd Basement V2|1|door|3|0
d_12|RnD 2nd Flr V2|1|door|3|0
d_16|Canteen HO|1|door|3|2
p_3|HO Panel Lite||panel|2|
p_4|Factory Panel||panel|0|
p_6|vega panel lite||panel|8|
p_7|vega panel lite||panel|8|
p_3|CDC PD HO|1|paneldoor|2|
p_3|Main Entry 1|2|paneldoor|2|
<EOT>

Matrix COSEC Web API User Guide 21

 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,

http://matrixserver/api.svc/v2/device?action=get;type=door

Sample Response:

id|name|siteid|type|device-type|application-type
d_6|RnD 1st Flr|1|door|1|0
d_8|RnD 3rd Flr|1|door|1|0
d_11|Rnd Basement V2|1|door|3|0
d_12|RnD 2nd Flr V2|1|door|3|0
d_16|Canteen HO|1|door|3|2
d_17|RnD 4th Flr|1|door|3|0
<EOT>

Sample Request:

For type=group (in XML format),

http://matrixserver/api.svc/v2/device?action=get;type=group;format=xml

Sample Response:

22 Matrix COSEC Web API User Guide

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

http://<servername>/api.svc/v2/device?action=assign;<argument>=<value>...

Parameters

Table: Assigning Users to Device - Parameters

Argument Valid Values Mandatory Default Value Description

Yes - To specify the device with the device

type and device ID.
all,
p_1 to p_999, Here, p means panel, d means direct
d_1 to d_9999, doors and g means group, while, p_1
device
g_1 to g_99999 will stand for a panel device with ID = 1,
pd_1_1 to pd= panel door
pd_65535_255
System should allow more than one
device group against a user.

If argument range is not mentioned and

individual argument ID is specified,
1 to 999999 (for all the
then User id should be considered.
ranges except all &
user)
Argument ID can have multiple ids as
value separated with comma.
Max 15 alphanumeric
Id Yes - For example Id=1,2,…..999
characters (for user)
A to Z
In case user-id /user-id & user-filter are
a to z
provided along with id/id & range,
0 to 9
priority should always be given to user-
/_\\.@:
id / user-id & user-filter. Value of id/id &
range to be ignored in that case.

All In this argument only single value

Organization should be allowed.
Branch
Department If argument range's value is specified
Designation as "All", ids of all the users that login
Section User (If argument user has rights over will return
Range No
Category Range is not specified)
Grade In case user-id /user-id & user-filter are
User provided along with id/id & range,
Custom-group-1 priority should always be given to user-
Custom-group-2 id / user-id & user-filter. Value of id/id &
custom-group-3 range to be ignored in that case.

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.

Matrix COSEC Web API User Guide 23

 The login user must have necessary rights on the device for this request.

Example

Following are some sample cases for this function.

Sample Request:

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

http://matrixserver/api.svc/v2/device?action=assign;device=g_1,g_2

Sample Response:

failed: <response code> : Invalid command : device=g_1,g_2 only single group against a user

24 Matrix COSEC Web API User Guide

Sample Request:

To assign user to all devices.

http://matrixserver/api.svc/v2/device?action=assign

Sample Response:

success: <response code> : successful

Sample Request:

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

http://matrixserver/api.svc/v2/device?action=assign;device=p_1;id=1

Sample Response:

success: <response code> : successful

Sample Request:

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

http://matrixserver/api.svc/v2/device?action=assign;device=p_1,d_1,g_1

Sample Response:

success: <response code> : successful

Matrix COSEC Web API User Guide 25

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

http://<servername>/api.svc/v2/device?action=revoke;<argument>=<value>...

Parameters

Table: Assigning Users to Device - Parameters

Argument Valid Values Mandatory Default Value Description

Yes - To specify the device with the device

type and device ID.
all,
p_1 to p_999, Here, p means panel, d means direct
d_1 to d_9999, doors and g means group, while, p_1
device
g_1 to g_99999 will stand for a panel device with ID = 1,
pd_1_1 to pd= panel door
pd_65535_255
Note: System should allow more than
one group against a user.

System should allow user to select

multiple id, each separated by
"(comma)" e.g.:"1,3,7,9 "
Or
Select a range of id E.g."1-50".

1 to 999999 (for all the Note: System should allow more than
ranges except all & one group against a user.
user)
If argument range is not mentioned and
Max 15 alphanumeric individual argument ID is specified,
Id Yes -
characters (for user) then User id should be considered.
A to Z
a to z Argument ID can have multiple ids as
0 to 9 value separated with comma.
/_\\.@: For example Id=1,2,…..999

In case user-id /user-id & user-filter are

provided along with id/id & range,
priority should always be given to user-
id / user-id & user-filter. Value of id/id &
range to be ignored in that case.

26 Matrix COSEC Web API User Guide

Table: Assigning Users to Device - Parameters

Argument Valid Values Mandatory Default Value Description

All In this argument only single value

Organization should be allowed.
Branch
Department If argument range's value is specified
Designation as "All", ids of all the users that login
Section User (If argument user has rights over will return
Range No
Category Range is not specified)
Grade In case user-id /user-id & user-filter are
User provided along with id/id & range,
Custom-group-1 priority should always be given to user-
Custom-group-2 id / user-id & user-filter. Value of id/id &
custom-group-3 range to be ignored in that case.

Note: If any device is un-assigned against any user via API, then allow the deletion of that door/ device group. But
if the device(s) or a device belonging to any device group is selected for deletion and is a part of the Access Rule
which is assigned to that user, then that door(s) must be retained against that User.

Example

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

Sample Request:

For revoking all devices.

http://matrixserver/api.svc/v2/device?action=revoke

Sample Response:

success: <response code> : successful

Sample Request:

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

http://matrixserver/api.svc/v2/device?action=revoke;device=p_1;id=1

Sample Response:

success: <response code> : successful

Sample Request:

For “device=p_1,d_1,g_1”.

http://matrixserver/api.svc/v2/device?action=revoke;device=p_1,d_1,g_1

Sample Response:

success: <response code> : successful

Matrix COSEC Web API User Guide 27

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

http://<servername>/api.svc/v2/device?action=set;<argument>=<value>...

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 = Door V1,
2 = Panel Lite
3 = Door V2,
4 = NGT Direct Door,
0,1,2,3,4,5,6,7,8,9,11,12,14,15,
device-type Yes - 5 = Wireless Direct Door
19,17,20, 21
6 = Path Controller
7 = PVR Direct Door
8 = Panel200
9 = Vega Controller
11 = ARC Controller
12 = Door V3
14 = ARC IO800
15 = Door FMX
20 = ARGO
21 = ARGO FACE

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. - “01:23:4567:89:ab”

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.

28 Matrix COSEC Web API User Guide

Table: Adding a New Device - Parameters

Argument Valid Values Mandatory Default Value Description

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.

This is the template on which

fingers templates are enrolled.

For PVR and Door V1, this field

should be ignored (Value should
be always zero irrespective of any
2 and 3 for FMX
value entered).
Door type.
0- Suprema Proprietary
For other doors it
Finger-template- 1- Suprema ISO When finger-reader-type = 2 for
No will be fetched from
format 2- Lumidigm ISO dtype = 20, this field should be
Finger Template
3- Lumidigm Proprietary ignored (Value should be always
Format configured
zero irrespective of any value
in Global Policy
entered).

For other direct doors except Door

V1 and PVR Door, Panel, Panel
Lite and Panel200, valid values
are 0 and 1.

This field is only applicable to

direct doors. This field will define
the application/use of the device.
(this feature enables the
0 = Basic Access Control
1 (Advanced advanced access control features
application 1 = Advanced Access Control No
Access Control) on device).
2 - Cafeteria
Application =2 is applicable for
Device types =
3,4,5,9,12,15,19,20,21

This field is applicable to direct

0= card
doors only
1= finger
2= card & PIN
Note:
3= finger & PIN
Options 0,1,2,3,4,5,6 and 12 are
4= card & finger
applicable only to device with
5= card & finger & PIN
finger print reader.
6= Any
7= palm
Options 0,2,6,7,8,9,10 and 11 are
8= palm & PIN
applicable for devices with Palm
9= card & palm
access-mode No 6 (Any) Vein Reader.
10= card & PIN & palm
11= palm & group
For Path Controllers, modes 2, 3,
12= finger then card
and 5 are not applicable.
13= palm then card
14= None
Not applicable for ARC Controller.
15= Face
16= Card & Face
Options 15, 16, 17, 18 are
17= PIN & Face
applicable only for FMX Doors and
18= finger & Face
Vega Controllers and ARGO.
20= Card then Biometrics

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.

Matrix COSEC Web API User Guide 29

Table: Adding a New Device - Parameters

Argument Valid Values Mandatory Default Value Description

This will set the Internal Reader IO

0=entry type (entry or exit).
ir-mode No 0 (entry)
1=exit
Not applicable for ARC Controller.

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

This will identify the finger/palm

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

Not applicable for ARC Controller.

This is the external reader mode.

0= entry
er-mode No 1 (exit)
1= exit
Not applicable for ARC Controller.

0= none
1= em prox reader
2= hid prox reader
This will determine the external
3= mifare reader
reader IO type.
4=hid iclass u reader
5= finger reader
For device type=1 (direct door
6= hid icalss w-reader
V1), er-types (8,9,10) are not
8= uhf reader
er-type No 0 (none) applicable.
9= combo exit reader
10= mifare w reader
er-type=5 is not applicable to
11=PIN - W reader
PVR door type.
13=CB - U Reader
14=CB - W Reader
Not applicable for ARC Controller.
15=ATOM RD300
16=ATOM RD200
17=ATOM RD100

This parameter will be used to

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

30 Matrix COSEC Web API User Guide

Table: Adding a New Device - Parameters

Argument Valid Values Mandatory Default Value Description

0 = none
rg1-wiegand 1 (Short-Range
1 = Short-Range Reader No
Reader)
2 = Long-Range Reader

0 = None
1 = EM Prox Reader
2 = HID Prox Reader
3 = MiFare Reader
4 = HID iClass-U Reader 1
rg1-rs485 No
5 = Combo Reader (EM Prox Reader)
13=CB - U Reader
15=ATOM RD300
16=ATOM RD200
17=ATOM RD100

rg1-mode 0 = entry
No 0 (entry)
1 = exit

0 = Card
1 = Finger
4 = Card + Finger
6 = Any
rg1-access-mode No 6 (Any)
12 = Finger Then Card
14= None
Applicable for ARC Controller
19=BLE
only.
20= Card then Biometrics
For other device types, these
0 = none
1 (Short-Range parameters will not be applicable.
rg2-wiegand 1 = Short-Range Reader No
Reader)
2 = Long-Range Reader

0 = none
1 = EM Prox Reader
2 = HID Prox Reader
3 = MiFare Reader
4 = HID iClass-U Reader 1 (EM Prox
rg2-rs485 No
5 = Combo Reader Reader)
13=CB - U Reader
15=ATOM RD300
16=ATOM RD200
17=ATOM RD100

0 = entry
rg2-mode No 0 (entry)
1 = exit

0 = Card
1 = Finger
4 = Card + Finger
6 = Any
rg2-access-mode No 6 (Any)
12 = Finger Then Card
14= None
19=BLE
20= Card then Biometrics

Card format ID for Internal

ir-card-format 1-99 No 1
Readers/Reader Group 1

Card Format for External Readers

er-card-format 1-99 No 1
/Reader Group 2

Card format ID for Internal

ir-card-format2 1-99 No
Readers/ Reader Group 1

Card Format for External Readers

er-card-format2 1-99 No
/ Reader Group 2

Matrix COSEC Web API User Guide 31

Table: Adding a New Device - Parameters

Argument Valid Values Mandatory Default Value Description

Card format ID for Internal

ir-card-format3 1-99 No
Readers/ Reader Group 1

Card Format for External Readers

er-card-format3 1-99 No
/ Reader Group 2

Card format ID for Internal

ir-card-format4 1-99 No
Readers/ Reader Group 1

Card Format for External Readers

er-card-format4 1-99 No
/ Reader Group 2

Card format ID for Internal

ir-card-format5 1-99 No
Readers/ Reader Group 1

Card Format for External Readers

er-card-format5 1-99 No
/ Reader Group 2

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

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=00:01:23:45:67:89
• device-group=Research

Sample Request:

http://matrixserver/api.svc/v2/device?action=set;device-type=0;device-
id=1;name=panel;mac=00:01:23:45:67:89;device-group=Research

Sample Response:

success: <response code> : successful

32 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

http://<servername>/api.svc/v2/device?action=delete;<argument>=<value>...

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 = Door V1,
2 = Panel Lite
3 = Door V2,
4 = NGT Direct Door,
5 = Wireless Direct Door
0,1,2,3,4,5,6,7,8,9,11,
device-type Yes - 6 = Path Controller
12,14,15,19,17,20, 21
7 = PVR Direct Door
8 = Panel200
9 = Vega Controller
11 = ARC Controller
12 = Door V3
14 = ARC IO 800
15 = Door FMX
19 = Door V4
17 = ARC DC 200
20 = ARGO
21 = ARGO FACE

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:

http://matrixserver/api.svc/v2/device?action=delete;device-type=1;device-id=1

Matrix COSEC Web API User Guide 33

Sample Response:

success: <response code> : successful

34 Matrix COSEC Web API User Guide

Obtaining Device List with 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

http://<servername>/api.svc/v2/device?action=list;<argument>=<value>......

Parameters

Table: Obtaining Device Status - Parameters

Argument Valid Values Mandatory Default Value Description

all, connected,
disconnected,
To specify the devices to be listed on
status online,offline,unknown No all
the basis of their status.
(Applicable to Panel
Doors only)

Response Fields

Table: Getting a Device List with Status - Response fields

Field Name Tag Name Valid Values Remarks

0 = Panel,
1 = Direct Door,
2 = Panel Lite
3 = Direct Door V2,
4 = NGT Direct Door,
5 = Wireless Direct Door
6 = Compact Direct Door
7 = PVR Direct Door
8= Panel200
Enum - 13 is reserved for
Device Type device-type 9= Vega Controller
COSEC SAMAY Door V3.
11 = Arc Controller
12 = Door V3
14 = ARC IO 800
15 = Door FMX
18 = MODE
19 = Door V4
17 = ARC DC 200
20 = ARGO
21 = ARGO FACE

Device ID device-id 1-65535

Name name Max 30 alphanumeric character

For Panels : 0
1-255 (device-type = 8) For Direct Doors : 1
Door ID did For Panel Doors : As
0-99 (All Others) configured

0: Inactive
Active active
1: active

Matrix COSEC Web API User Guide 35

Table: Getting a Device List with Status - Response fields

Field Name Tag Name Valid Values Remarks

Device IP ip

For Device type= MODE, it

Device MAC mac 40 characters
would display UUID

Panel/Direct Doors:
disconnected (0)
connected (1)

Panel Doors:
status status
If Panel's status=0: Unknown
Else: offline (0), online (1/3)
upgrading (2)
unknown (4)

DD/MM/YYYY HH:MM:SS AM/

Connect Time connect-time
PM

DD/MM/YYYY HH:MM:SS AM/

Disconnect Time disconnect-time
PM

Example

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

Sample Request:

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

http://matrixserver/api.svc/v2/device?action=list;status=connected

Sample Response:

success: <response code> : No records found

Sample Request:

When “status=all”,

http://matrixserver/api.svc/v2/device?action=list;status=all

Sample Response:

device-type|device-id|name|active|ip|mac|status|connect-time|disconnect-time
0|1|Panel-1|1||00:4f:4e:67:89:08|disconnected||10/3/2013 9:00:19 AM
1|1|door|1|192.168.103.50|00:01:23:45:67:89|disconnected|10/3/2011 10:19:55 AM|10/3/2013 9:00:19 AM
4|2|NGTDoor1|1||00:3f:4e:67:89:08|disconnected||10/3/2013 9:00:19 AM
3|3|NGT Door|1||00:1b:09:90:76:00|disconnected||10/3/2013 9:00:19 AM
3|6|5453|1||00:1b:09:90:76:06|disconnected||10/3/2013 9:00:19 AM
<EOT>

36 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

http://<servername>/api.svc/v2/device?action=update;<argument>=<value>......

Parameters

Table: Updating Device Configuration - 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,
2 = Panel Lite
3 = Direct Door V2,
4 = NGT Direct Door,
5 = Wireless Direct Door
6 = Compact Direct Door
0,1,2,3,4,5,6,7,8,9,11,12,14,15, 7 = PVR Direct Door
device-type Yes -
19,17,20,21 8= Panel-lite V2
9= Vega Controller
11 = Arc Controller
12 = Door V3
14 = ARC IO 800
15 = Door FMX
16=Path V2
18 = MODE
19 = Door V4
17 = ARC DC 200
20 = ARGO
21 = ARGO FACE

1 to 65535 (panel, panel-lite) This is the device identification

device-id Yes -
1 to 65535 (direct doors) number of the device type (MID).

name Maximum 15 characters No - This is the name of the device.

This is the MAC Address of the

Maximum 17 characters (each device.
mac No -
byte separated by “:”)
E.g. - “01:23:4567:89:ab”

This is the name of the device

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

Matrix COSEC Web API User Guide 37

Argument Valid Values Mandatory Default Value Description

0 = inactive The enabled/disabled status of the

active No
1 = active 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.

For other direct This is the template on which

0- Suprema Proprietary doors except Door fingers templates are enrolled.
1- Suprema ISO V1 and PVR Door, When finger-reader-type = 2 for
Finger-template-
2- Lumidigm ISO No Panel, panel Lite dtype = 20, this field should be
format
3- Lumidigm Proprietary and Panel lite V2, ignored (Value should be always
valid values are 0 zero irrespective of any value
and 1. entered).

This field is only applicable to

direct doors. This field will define
1 - basic access control
the application/use of the device.
application 0 - advanced access control No
(this feature enables the
advanced access control features
on device).

This field is applicable to direct

doors only

Biometrics for option = 20; finger

should be considered for devices
with finger print reader and palm
should be considered for devices
with palm vein reader respectively
0= card
Note:
1= finger
Options 0,1,2,3,4,5,6 and 12 are
2= card & PIN
applicable only to device with
3= finger & PIN
finger print reader.
4= card & finger
5= card & finger & PIN
Options 0,2,6,7,8,9,10, 11, 13 and
6= Any (default)
21 are applicable for devices with
7= palm
Palm Vein Reader.
8= palm & PIN
9= card & palm
access-mode No For CDC type door 2, 3, and 5
10= card & PIN & palm
modes are not applicable.
11= palm & group
12= finger then card
Options 15, 16, 17, 18 are
13= palm then card
applicable only for FMX Doors and
14= None
Vega Controllers and ARGO.
15= Face
16= Card & Face
Options 15,16,18 will also be
17= PIN & Face
applicable for Path V2
18= finger & Face
20= Card then Biometrics
Options 0,2,6,14,15,16 and 17
only are applicable to ARGO
FACE

If FR license is not available or

balance is not available, and
options 15/16/17/18 is selected for
device-type=9 or 15, skip this
parameter

This parameter will toggle the

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

38 Matrix COSEC Web API User Guide

 Argument Valid Values Mandatory Default Value Description

This will set the Internal Reader IO

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

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

this will identify the finger/palm

reader type as an internal reader
0= none
finger-reader-type 1= finger reader No Note: palm reader is applicable for
2= palm reader PVR door and ARGO door type

Not applicable for Arc Controller

This is the external reader mode.

0= entry
er-mode No
1= exit

0= none
1= em prox reader
This will determine the external
2= hid prox reader
reader IO type.
3= mifare reader
4= hid iclass u reader
For device type=1 (direct door
5= finger reader
V1), er-types (8,9,10) are not
6= hid iclass w-reader
applicable.
8= uhf reader
er-type No
9= combo exit reader
er-type=5 is not applicable to
10= mifare w reader
PVR device type and Door FMX
11= PIN - W Reader
13= CB - U Reader
er-type 5 not applicable to ARGO
14= CB - W Reader
Door when value passed in finger-
15= ATOM RD300
reader-type = 2.
16= ATOM RD200
17= ATOM RD100

This parameter will be used to

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

0 = none
1 = Short - Range Reader
rg1-wiegand
2 = Long - Range Reader
11 = PIN - W Reader
14 = CB - W Reader

0 = None
1 = EM Prox Reader
2 = HID Prox Reader
3 = MiFare Reader
4 = HID iClass-U Reader
rg1-rs485 No
5 = Combo Reader
13 = CB - U Reader
15 = ATOM RD300
16 = ATOM RD200
17 = ATOM RD100

rg1-mode 0 = entry
No
1 = exit

Matrix COSEC Web API User Guide 39

Argument Valid Values Mandatory Default Value Description

0 = Card
1 = Finger
2 = Card + PIN
3 = Biomertric + PIN
4 = Card + Finger
5 = Biometric + Card + PIN
6 = Any
rg1-access-mode No
12 = Finger Then Card
14 = None
19 = BLE
20 = Card then Biometrics
15 = Face
16 = Card + Face
18 = Biometric + Face

0 = none
1= Short - Range Reader
rg2-wiegand 2 = Long - Range Reader No
11 = PIN - W Reader
14 = CB - W Reader

0 = none
1 = EM Prox Reader
2 = HID Prox Reader
3 = MiFare Reader
4 = HID iClass- U Reader
rg2-rs485 No
5 = Combo Reader
13 = CB - U Reader
15 = ATOM RD300
16 = ATOM RD200
17 = ATOM RD100

0 = entry
rg2-mode No
1 = exit

0 = Card
1 = Finger
2 = Card + PIN
3 = Biomertric + PIN
4 = Card + Finger
5 = Biometric + Card + PIN
6 = Any
rg2-access-mode No
12 = Finger Then Card
14 = None
19 = BLE
20 = Card then Biometrics
15 = Face
16 = Card + Face
18 = Biometric + Face

Card format ID for Internal

ir-card-format 1-99 No 1
Readers/Reader Group 1

Card Format for External Readers

er-card-format 1-99 No 1
/Reader Group 2

Card format ID for Internal

ir-card-format2 1-99 No
Readers/ Reader Group 1

Card Format for External Readers

er-card-format2 1-99 No
/ Reader Group 2

Card format ID for Internal

ir-card-format3 1-99 No
Readers/ Reader Group 1

Card Format for External Readers

er-card-format3 1-99 No
/ Reader Group 2

40 Matrix COSEC Web API User Guide

 Argument Valid Values Mandatory Default Value Description

Card format ID for Internal

ir-card-format4 1-99 No
Readers/ Reader Group 1

Card Format for External Readers

er-card-format4 1-99 No
/ Reader Group 2

Card format ID for Internal

ir-card-format5 1-99 No
Readers/ Reader Group 1

Card Format for External Readers

er-card-format5 1-99 No
/ Reader Group 2

The Login User must have rights on the device which is to be updated.
Action = update not applicable to Panel Doors.

Example

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

Sample Request:

To update a Direct Door V2 named “RndBasementV2”.

http://matrixserver/api.svc/v2/device?action=update;device-id=11;device-type=3;name=RndBasementV2

Sample Response:

success: <response code> : successful

Sample Request:

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

http://matrixserver/api.svc/v2/device?action=update;device-id=33;device-
type=9;mac=23:56:66:33:33:23;device-group=RnD

Sample Response:

failed: <response code> : Mac is already associated with another device.

Matrix COSEC Web API User Guide 41

Getting a Device Group

This API allows the user to obtain a list of devices assigned to a specific device group.

Action

action=get

Syntax

http://<servername>/api.svc/v2/device-group?action=get;<argument>=<value>...

User Rights

User Rights

System Account Enabled.

User must have rights on following page:

Devices > Masters> Device Group

ESS Disabled

Parameters

Table: Getting a Device Group - Parameters

Argument Valid Values Mandatory Default Value Description

0: all
range No all -
1: Individual

You can select multiple ids, each

Id 1-99999 - - separated by ", (comma)" e.g.:"1, 3, 7,
9…"

A-Z
a-z To select multiple group names, each
Name 0-9 - - separated by ", (comma)"
()_-. e.g.:"DG1,DG2,…"
[space]

Note 1 : (For range= individual)If valid Id and Name both are specified, then priority should be given to ID and it
should fetch device details as per entered Id.

Note 2 : (For range= individual) If provided Id or Name both contain valid values/arguments, return messages as
specified for Id only.

Note 3: (For range= individual)If either Id or Name contains valid values, it should fetch device details as per
entered valid argument and values. e.g., If invalid Id has been entered, but valid name is mentioned, then it should
fetch devices as per entered name.

42 Matrix COSEC Web API User Guide

Response Fields

Table: Getting a Device Group - Response fields

Field Name Tag Name Valid Values Remarks

Device Group ID devicegroup-id

Device Group Name devicegroup-name

Device ID device-id 1-65535

0 = Panel,
1 = Direct Door,
2 = Panel Lite
3 = Direct Door V2,
4 = NGT Direct Door,
5 = Wireless Direct Door
6 = Compact Direct Door
7 = PVR Direct Door
8= Panel200
Device Type device-type
9= Vega Controller
11 = Arc Controller
12 = Door V3
14 = ARC IO 800
15 = Door FMX
18 = MODE
17 = ARC DC 200
20 = ARGO
21 = ARGO FACE

For Panels : 0
1-255 (device-type = 8)
For Direct Doors : 1
Door ID did
For Panel Doors : As
0-99 (All Others)
configured

Name name Max 30 alphanumeric character

1: active
Active active
0: Inactive

Device IP ip

Device MAC mac 40 characters

Panel/Direct Doors:
disconnected (0)
connected (1)

Panel Doors:
status status If Panel's status=0: Unknown
Else: offline (0), online (1/3)
upgrading (2)
unknown (4)

DD/MM/YYYY HH:MM:SS AM/

Connect Time connect-time
PM

DD/MM/YYYY HH:MM:SS AM/

Disconnect Time disconnect-time
PM

Matrix COSEC Web API User Guide 43

Adding a New Device Group

This API allows the user to set a list of device group/super group.The device can be assigned to a specified device
group and configured based on site requirements.

Action

action=set

Syntax

http://<servername>/api.svc/v2/device-group?action=set;<argument>=<value>...

Parameters

Table: Adding a New Device Group - Parameters

Argument Valid Values Mandatory Default Value Description

A-Z
a-z
0-9 This is the name of group to be
Name ()_-. Yes - created.
[space]

Max. 30 characters

Type 0 = Device Group This is the type of device group,

Yes 0 (Device Group)
1 = Super Group which user wants to create.

44 Matrix COSEC Web API User Guide

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 and add information about specific sites using COSEC. The http query to access site data from the COSEC
server should resemble the following syntax:

Syntax

http://<servername>/api.svc/v2/site?action=<method>;<argument>=<value>...

The Sites APIs allow you to perform the following functions:

• Obtaining Data on Existing Sites

• Adding a New Site

• Updating a Site

User Rights

User Rights

System Account Enabled

ESS Disabled

Matrix COSEC Web API User Guide 45

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

http://<servername>/api.svc/v2/site?action=get;<argument>=<value>...

Parameters

Table: Obtaining Data on Existing Sites - Parameters

Argument Valid Values Mandatory Default Value Description

id 1 to 999, all No all This is the Site ID

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,

http://matrixserver/api.svc/v2/site?action=get

Sample Response:

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

Sample Request:

Syntax with valid action but no record available,

http://matrixserver/api.svc/v2/site?action=get

46 Matrix COSEC Web API User Guide

Sample Response:

success: <response code> : No records found

Matrix COSEC Web API User Guide 47

Adding a New Site

This interface can be used to create a new site.

Action

action=set

Syntax

http://<servername>/api.svc/v2/site?action=set;<argument>=<value>...

Parameters

Table: Adding a New Site - Parameters

Argument Valid Values Mandatory Default Value Description

id 1 to 999 Yes - The Site ID

maximum 30
name alphanumeric Yes - The Site Name
characters

This indicate whether the specified site

default 1: Default site No Not a default site
is a default site or not.

Example

Sample Request:

With values “id=1”, “name=Site-1”,

http://matrixserver/api.svc/v2/site?action=set;id=1;name=Site-1

Sample Response:

success : successful

48 Matrix COSEC Web API User Guide

Updating a Site

This function can be used to update the configuration of an existing site on the COSEC database.

Action

action=update

Syntax

http://<servername>/api.svc/v2/site?action=update;<argument>=<value>...

Parameters

Table: Updating a Site - Parameters

Argument Valid Values Mandatory Default Value Description

id 1 to 999 Yes - The Site ID

maximum 30
name alphanumeric Yes - The Site Name
characters

This indicate whether the specified site

default 1: Default site No Not a default site
is a default site or not.

Matrix COSEC Web API User Guide 49

50 Matrix COSEC Web API User Guide
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:
Action=get
• Accessing User Data

Action=set
• Adding/Editing a User

Action=setphoto
• Adding User Photograph

Action=delete
• Deleting a User

Action=enroll
• Enrolling a User

Action=set-credential
• Setting Credentials on Device

Action=del-credential
• Deleting Credentials from Device

Action=get
• Searching a User

Action=get
• Fetching Reporting Group Members

User Rights

User Rights

Enabled.

User must have rights on following pages (COSEC Web Application):

System Account
Users > User List (For action=get)
Users > User Configuration (For other actions)

Matrix COSEC Web API User Guide 51

User Rights

Enabled if user has ESS rights enabled.

Only For action=get and action=set

ESS
Note : For action =set, the following option should be enabled (COSEC Web Application):

User Configuration > ESS > Settings > Edit Basic Details

52 Matrix COSEC Web API User Guide

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

http://<servername>/api.svc/v2/user?action=get;<argument>=<value>...

Parameters

Table: Accessing User Data - Parameters

Argument Valid Values Mandatory Default Value Description

This is used to fetch the data for

selected range of users.

Note: Response shall be provided with

All, organization, If “id” parameter is not
an error message, in case of invalid
branch, department, mentioned, consider
range.
designation, section, range=all.
Range category, grade, user, No
Note: Here “all” means the IDs of all
custom-group-1, If “id” parameter is
the users that login user has rights over
custom-group-2, mentioned, consider
custom-group-3 range=user
Note: If range is not mentioned and “id”
is specified, it will be considered as
range = user. And the IDs mentioned
will be considered as user IDs.

This can be the organization or user id

(as per the selected range).
1 to 999999 (for all the
Yes (if Note: Multiple IDs can be selected,
ranges except all &
mentioned each separated by a ‘comma’.
id user) -
range is other e.g.:”1, 3, 7, 9…”
Max 15 alphanumeric
than “all”)
characters (for user)
Note: If neither range nor id are
mentioned, return data for all the users
the login user has rights on.

0 : if user is not a
worker
Cwm-enabled No
1: if user is worker

Any of the field names

that can be updated These are the fields that can be
field-name No all
using set option (list is specified to fetch User’s specific data.
available in set table)

Matrix COSEC Web API User Guide 53

Table: Accessing User Data - Parameters

Argument Valid Values Mandatory Default Value Description

Non mandatory field.

Default value = 0.

Conditions:
1.Argument mentioned, but value not
specified, then ignore this parameter.

2.If filter=0 is specified, return all users

configured in the system.

3.If filter=1 is specified, return only

active users configured in the system.

4.If filter=2 is specified, return only

inactive users configured in the system.
0 : All
filter 1 : Active Users No 0 : All
2 : Inactive Users
Note:
If filter=1 is specified and multiple-ids
are passed or any enterprise group is
passed, out of which some of them are
inactive, then do not return those users
and vice-versa should also be
applicable.

If filter=2 is specified and multiple-ids

are passed or any enterprise group is
passed, out of which some of them are
active, then do not return those users
and vice-versa should also be
applicable.

Response Fields

Table: Accessing User Data - Response Fields

Field Name Tag Name Valid Values Remarks

Allowed Characters
A-Z
Id id max 15 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 -
2 : Inactive and Revoke Devices

Module module U- T&A User -

54 Matrix COSEC Web API User Guide

Table: Accessing User Data - Response Fields

Field Name Tag Name Valid Values Remarks

Date of Birth date-of-birth ddmmyyyy -

Joining Date joining-date ddmmyyyy -

Confirmation Date confirmation-date ddmmyyyy -

Leaving Date leaving-date ddmmyyyy -

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

PF No. pf-no max 30 alphanumeric characters -

max 50 alphanumeric characters

Vehicle Registration No vehicle-reg-no -
and comma(,)

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 -

Aadhar No. aadhar-no max 12 numeric characters -

UAN uan max 12 numeric characters -

Voter ID voter-id max 10 alphanumeric characters -

Visa No. visa-no max 30 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-,A1–
Blood Group blood-group ,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 -

Matrix COSEC Web API User Guide 55

Table: Accessing User Data - Response Fields

Field Name Tag Name Valid Values Remarks

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 10 alphanumeric characters -

Permanent State permanent-state max 40 alphanumeric characters -

Permanent Country permanent-country max 20 alphanumeric characters -

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 - 9999 -

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 1 - 999 -

56 Matrix COSEC Web API User Guide

Table: Accessing User Data - Response Fields

Field Name Tag Name Valid Values Remarks

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

Employment Profile employment-profile 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 -

Hour Exception hour-exception max 4 alphanumeric characters -

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

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 0-999999 -

max 20 numeric characters

Value will be “0” if login
Card-1 card-1
max 21 characters= 20 numeric + user is ESS user.
comma

max 20 numeric characters

Value will be “0” if login
Card-2 card-2
max 21 characters= 20 numeric + user is ESS user.
comma

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 -

If more than one group is

assigned, then it should
Device Group ID device-group-id
fetch multiple device group
id separated with comma.

If more than one group is

assigned, then it should
Device Group Name device-group fetch multiple device group
name separated with
comma.

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

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

Matrix COSEC Web API User Guide 57

Table: Accessing User Data - Response Fields

Field Name Tag Name Valid Values Remarks

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 -

If user has palm enrolled, the

PVR Group Number pvr_group PVR group number will be PVR Group Number
returned here.

Total Number of fingers (all

Enrolled Fingers enrolled_fingers 0-30 the template types)
enrolled for this user

Number of palms enrolled

Enrolled Palms enrolled_palms 0-10
for this user

ID of the reporting group to

Reporting Group ID rg_id 1-999
which user belongs

Name of the reporting

Reporting Group Name rg_name upto 30 characters group to which user
belongs

Reporting Group Incharge 1’s User ID of reporting group

rg_incharge_1 upto 15 characters
ID incharge 1

Reporting Group Incharge 2’s User ID of reporting group

rg_incharge_2 upto 15 characters
ID incharge 2

Reporting Group Incharge 3’s User ID of reporting group

rg_incharge_3 upto 15 characters
ID incharge 3

Reporting Group Incharge 4’s User ID of reporting group

rg_incharge_4 upto 15 characters
ID incharge 4

Reporting Group Incharge 5’s User ID of reporting group

rg_incharge_5 upto 15 characters
ID incharge 5

upto 40 characters. Allowed

characters:
IMEI Number imei -
Alphanumeric
-

58 Matrix COSEC Web API User Guide

Table: Accessing User Data - Response Fields

Field Name Tag Name Valid Values Remarks

0: Pending
IMEI Authorized or not imei-authorized 1: Authorized -
2: Rejected

Valid Characters :
A-Z
Max 100 characters a-z
Custom Field 1 -10 field1-10
ddmmyyyy 0-9
space
[]().-_/

Week Off Group week-off-group 1-99 Numeric Only

0 : Disabled
Punch Marking Via API punch-api -
1 : Enabled

0 : Disabled
Auto-Punch Marking auto-attendance -
1 : Enabled

0 : Disabled
Manual Punch Marking manual-punch -
1 : Enabled

0 : None
Location Data Mandatory from
location-mandatory 1 : Any Location -
Apps
2 : Configured Locations

0 : Disabled
Door Access Through API door-access-api -
1 : Enabled

0 : Disabled
FVM Flag FVM-enable -
1 : Enabled

0: None
Job Assignment Type job-assignment-type 1: Fixed -
2: Device Based

0: Not Blacklisted
Blacklisted blacklisted -
1: Blacklisted

Number of fingers enrolled

Enrolled Fingers - Suprema suprema-proprietary-count
0-10 in suprema proprietary
Proprietary
type against a user

Number of fingers enrolled

Enrolled Fingers - Suprema
suprema-iso-count 0-10 in suprema ISO type
ISO
against a user.

Number of fingers enrolled

Enrolled Fingers - Lumidigm
lumidigm-iso-count 0-10 in Lumidigm ISO type
ISO
against a user.

Restrict Half Day 0 : Disabled

Restrict-half-day
Considerations 1 : Enabled

Should return the

Organization Name organization-name Organization Name of
User

Should return the Branch

Branch Name branch-name
Name of User

Matrix COSEC Web API User Guide 59

Table: Accessing User Data - Response Fields

Field Name Tag Name Valid Values Remarks

Should return the

Department Name department-name
Department Name of User

Should return the Category

Category Name category-name
Name of User

Should return the Grade

Grade Name grade-name
Name of User

Should return the

Designation Name designation-name
Designation Name of User

Should return the Section

Section Name section-name
Name of User

Restrict Half Day Restrict-half-day 0 : Disabled

Considerations 1 : Enabled

Custom Group 1 ID customgroup1ID 1-999999

Custom Group 2 ID customgroup2ID 1-999999

Custom Group 3 ID customgroup3ID 1-999999

Custom Group 1 Code customgroup1_code max 6 alphanumeric characters

Custom Group 2 Code customgroup2_code max 6 alphanumeric characters

Custom Group 3 Code customgroup3_code max 6 alphanumeric characters

Allowed Characters
A-Z
Custom Group 1 Name customgroup1_name 45 Characters a-z
0-9
-_. ()[]

Allowed Characters
A-Z
Custom Group 2 Name customgroup2_name 45 Characters a-z
0-9
-_. ()[]

Allowed Characters
A-Z
Custom Group 3 Name customgroup3_name 45 Characters a-z
0-9
-_. ()[]

Cafeteria Usage Policy Cafeteria-usage-policy 1-99

Show Attendance Details On 0 : Disabled

show-atd-details
Device 1 : Enabled

60 Matrix COSEC Web API User Guide

Table: Accessing User Data - Response Fields

Field Name Tag Name Valid Values Remarks

Allowed Characters

A -Z
a-z
0-9
()
[]
_ (underscore)
- (Hyphen)
. (full Stop)
Full Name full-name max 200 alphanumeric characters
/
&
, (comma)
@
' (single quote)
[Space]

When Multi Language is

On, Invalid Character set =
Set3

ID of the approval policy

Approval Policy ID approval-policy 1-999 which is assigned to
selected user.

Returns the Approval

Approval Policy Name approval-policy-name 30 Characters Policy Name of the
selected Policy ID.

Returns the time zone

0: Server Timezone
Timezone for Punch Marking Punch-marking-timezone selected for punch
1: Local Timezone
marking.

enable-elevator-access- Returns the status of EAC

Elevator Access Control 0 or 1
control feature

Returns the number of

Elevator Floor Group elevator-floor-group 1 - 99
floor groups configured.

0 : Disabled Returns the Status of FR

Enable Face Recognition enable-fr
1 : Enabled as enabled/disabled

0 : For Attendance
Enable Face Recognition For enable-fr-for 1 : For Access Control
2 : Both

0: Disabled
Enable Self Enrollment FR enable-fr-self-enroll
1: Enabled

1 - enable bypass
Bypass Face bypass-face Bypass Face
0 - disable bypass

Total Number of faces

Enrolled faces enrolled_faces 0-40
enrolled for this user

0: Unauthorized Host Returns the value set for

Authorized Host User auth-host-user
1: Authorized Host User.

If Enable FR/Punch
0 : None
Marking Via API/Manual
1 : Attendance
Punch Marking is disabled
Face Mandatory For Punch face-mandatory 2 : Access Control
for a user, face-mandatory
3 : Both
tag will be available only
for value 0 : None

Matrix COSEC Web API User Guide 61

Table: Accessing User Data - Response Fields

Field Name Tag Name Valid Values Remarks

Max 15 alphanumeric characters

A-Z
Prefix prefix a-z
0-9
/_\\.@:

PIN Authentication For Door 0 : Disabled

pin-authentication
Access 1 : Enabled

Driving License Expiry Date driving-license-expiry ddmmyyyy

Passport Expiry Date passport-expiry ddmmyyyy

Max 50 chars
Valid Values :
A-Z
a-z
Blacklisted reason Blacklisted-reason
0-9
[space]
!@$*()_-+\[],.:

enabled only when

Reason for punching from 0 : unchecked
punch-reason-flg Location Mandatory For
unassigned location 1 : checked
Punch = 0,1

12: driving-license
13: passport-no Uploaded document tag is
14: pan added for checking the
16: pf-no status of uploaded images
18: esi-no for respective field.
21: field1 Multiple values are
22: field2 possible in this field.
Uploaded-doc uploaded-doc 23: field3
24: field4 If documents/images are
41: field5 present in field1,2 and 5
42: field6 then uploaded-doc should
43: field7 contain value of field1,
44: field8 field 2 and 5 be provided in
respective field.
45: field9
46: field10

1: Checked
Authorized Host User Flag Authorized-Host-User
0: Unchecked

This is the ID of the device

group.
If more than one group is
Visitor Device Group ID Visitor-device-group-id Max 5 numeric characters
assigned, then it should
fetch multiple device group
id separated with comma.

This is the name of the

device group.
If more than one group is
Visitor Group Name Visitor-device-group max 30 characters assigned, then it should
fetch multiple device group
name separated with
comma.

62 Matrix COSEC Web API User Guide

Table: Accessing User Data - Response Fields

Field Name Tag Name Valid Values Remarks

0= None
Enable Offline-Transaction enable-offline-transaction 1= Allow Without Discount
2= Allow With Discount

0: Disabled Returns value from User

APTA Face Anti-Spoofing apta-face-anti-spoofing
1: Enabled Configuration > ESS.

15 characters Job ID can have multiple

ids as value with comma
Job ID = 0 - 4294967295 separation.
For eg : 1, 2, 3, ....
4294967295
0 = Job Assignment Type
= "Fixed" or "None"

1-4294967292 = Job
Reference ID
corresponding to
respective Job Codes
Assigned Job assigned_job
4294967293 = Job
Reference ID selected =
Continue Job

4294967294 = Job
Reference ID selected =
Default Job

4294967295 = Job
Reference ID selected =
None

1 : enabled
Capture Photo capture-photo 0 : disabled

Max Allowed Limit max-allowed-limit 0.01 to 999999.99

Max Usage Limit max-usage-limit 0.01 to 999999.99

0.01 to 999999.99 This defines the max

usage limit per day of the
canteen user.

For Account Type= Pre-

Paid when this parameter
is passed while firing API-
details should be received
as per configured for the
Max Usage Limit Per Day max-usage-limit-day Pre-Paid account user.

For Account Type= Post-

Paid when this parameter
is passed while firing API-
details should be received
as per configured for the
Post-Paid account user.

Matrix COSEC Web API User Guide 63

Example1

Sample Request: A sample request for fetching employee data with specific fields.

http://192.168.104.16/cosec/api.svc/v2/user?action=get;id=836,837,838,840;field-name=id,name,reference-
code,active,gender,marital-status,blood-group,nationality

Sample Response:

id|name|reference-code|active|gender|marital-status|blood-group|nationality
836|RAJUBHAI VANKAR|836|1|male|married|b+|Indian
837|SHIRIN Y PATEL|837|1|female|unmarried|a-|Indian
838|VIPUL B SOLANKI|838|1|male|unmarried|o+|Indian
840|KANTIBHAI VASAVA|840|1|male|na|a+|Indian
<EOT>

Example2

Sample Request: A sample request for fetching all the data of an employee.

http://192.168.104.12/cosec/api.svc/v2/user?action=get;id=101;

Sample Response:

id|reference-code|name|short-name|active|module|date-of-birth|joining-date|confirmation-date|leaving-
date|reason-for-leaving|pf-no|vehicle-reg-no|visa-no|visa-expiry|driving-license|pan|esi-no|passport-
no|aadhar-no|uan|voter-id|height|weight|gender|blood-group|marital-status|nationality|father-spouse-
name|qualification|experience|medical-history|local-address1|local-address2|local-street|local-
city|local-pincode|local-state|local-country|permanent-address1|permanent-address2|permanent-
street|permanent-city|permanent-pincode|permanent-state|permanent-country|personal-phone|personal-
cell|personal-email|official-phone|official-extension|official-cell|official-email|pin|card-1|card-
2|access-validity-date|active-directory-login|active-directory-username|active-directory-
domain|integration-
reference|organization|branch|department|designation|section|category|grade|leave_group|reporting-
incharge|attendance-policy|latein-policy|earlyout-policy|overtime-policy|absentee-policy|coff-
policy|device-group|device-group-id|smart-access-route|max-route-level|employment-profile|employment-
type|award-penalty|work-profile|roster-policy|roster-attendance-policy|hour-exception|access-
level|bypass-finger|bypass-palm|shiftbased-access|shift-schedule|start-shift|holiday-
schedule|attendance-calc|max-personal-hrs|bus-route|bypass-finpalm|ess-login|ess-detail-
edit|attendance-via-ess|allow-ecanteen|discount-level|account-type|max-allowed-limit|max-usage-
limit|organization_code|branch_code|department_code|designation_code|section_code|category_code|grade_c
ode|field1|field2|field3|field4|week-off-group|location-mandatory|punch-api|auto-attendance|manual-
punch|allow-offline-punch|door-access-api|fvm-enable|blacklisted|job-assignment-
type|device|pvr_group|enrolled_fingers|enrolled_palms|rg_id|rg_name|rg_incharge_1|rg_incharge_2|imei|im
ei-authorized|suprema-proprietary-count|suprema-iso-count|lumidigm-iso-count|organization-name|branch-
name|department-name|category-name|grade-name|designation-name|section-name|restrict-half-
day|customgroup1ID|customgroup2ID|customgroup3ID|customgroup1_code|customgroup2_code|customgroup3_code|
customgroup1_name|customgroup2_name|customgroup3_name|cafeteria-usage-policy|show-atd-details|full-
name|approval-policy|approval-policy-name
101|101|Khushbu|Khushbu|1|U|||||||||||||||||||NA|NA|NA||||||||||||||||||||||[email protected]|
|||||0|0||0||||1|1|1|1|1|1|1|1||1|1|1|1|1|1|DG1|1||75||||||||8|0|0|0|1|1|1|1|||0|1|1||0|0|0|0.00|0.00|O
RG1|BRC1|DPT1|DSG1|SEC1|CTG1|GRD1||||||0|1|0|0|0|0|0||0|p_4,d_2,d_4,d_9,d_12,p_3,d_10,d_8,d_5,d_6|2|1|1
|||||||1|0|0|Organization-1|Branch-1|Department-1|Category-1|Grade-1|Designation-1|Section-
1|0|1|1|1|CG1|CG2|CG3|Custom Group 1|Custom Group 2|Custom Group 3||1|Khushbu||
<EOT>

64 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

http://<servername>/api.svc/v2/user?action=set;<argument>=<value>...

Parameters

ESS users can edit only the parameters marked by **

Table: Adding/Editing a User - Parameters

Argument Valid Values Mandatory Default Value Description

This is the User Id.

For ESS User, the User ID should be

same as Login User’s ID

When Auto Generate ID flag is OFF in

15 alphanumeric Char. Global Policy then: Either “id” or “Prefix
A to Z Auto-generation-serial-length” or only
id a to z Yes - “Auto-generation-serial-length” should
0 to 9 be mentioned in API.
/_\\.@:
When Auto Generate ID flag is ON in
Global Policy then: id/Prefix + Auto-
generation-serial-length/ only Auto-
generation-serial-length” not required to
be mentioned in API.

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
-_. ()[]

Matrix COSEC Web API User Guide 65

Table: Adding/Editing a User - Parameters

Argument Valid Values Mandatory Default Value Description

Max 200 chars

A -Z
a-z
0-9
()
[]
_ (underscore)
- (Hyphen) Either "name" or "full-name" is a
. (full Stop) Yes (if name mandatory field to be mentioned in API.
full-name -
/ not mentioned) I.e. if "name" tag is mentioned than "full-
& name" is optional and vice versa.
, (comma)
@
'(single quote)
[Space]

When Multi Language is On,

Invalid Character set = Set3

This is the short name of User.

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

This is a field that shows whether user

is active or not.
It has two values 0 and 1 for inactive
0 : Inactive and active respectively.
1 : Active
active No 1
2 : Inactive and Revoke Note: If active is supplied as 1 and 2,
Devices the user is blacklisted then error code
"0070203002" will be generated with
validation message "User is
Blacklisted."

This value specifies the user type.

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

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.

This is the joining date of the user.

Note: - joining-date should be higher

than date-of-birth.

Y (if Non-editable if login user is an ESS

confirmation-
joining-date ddmmyyyy format User.
date or leaving- -
date to be
configured) Joining Date should not be allowed
blank in case of confirmation date or
leaving date value exists.

Allow joining date same as confirmation

date from User API.

66 Matrix COSEC Web API User Guide

Table: Adding/Editing a User - Parameters

Argument Valid Values Mandatory Default Value Description

This is the confirmation date of the user.

confirmation- ddmmyyyy format
No -
date 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.

Reason-for- Max 15 Alphanumeric This is the reason of leaving an

No -
leaving Characters organization.

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

Max 50 Alphanumeric This is the Vehicle Registration No of

vehicle-reg-no No -
Characters and comma(,) the user.

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.

This is the Aadhar Number of the user.

If Aadhaar no entered is not Unique

then it will display validation; “Aadhaar
No. already exists for User: id”
aadhar-no ** max 12 numeric characters No -
If Aadhar no is mandatory but still it is
not entered then it will display
validation; “Enter Aadhaar No”

uan ** max 12 numeric characters No - This is the UAN of the user.

max 10 alphanumeric
voter-id ** No - This is the Voter ID of the user.
characters

Yes (If visa-

Max 30 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.

integration- Max 20 Alphanumeric This is the integration reference for the

No -
reference 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

Matrix COSEC Web API User Guide 67

Table: Adding/Editing a User - Parameters

Argument Valid Values Mandatory Default Value Description

NA,A+,A-,B+,B-,AB+,AB-,o+,o-
,A1–,A1+, A1B-,
blood-group ** 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

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

No -
name ** 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

medical-history max 50 alphanumeric

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

This is the local pin code for local

local-pincode ** max 10 numeric characters No -
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

permanent- max 30 alphanumeric This is the permanent address 1 of the

No -
address1 ** characters user.

permanent- max 30 alphanumeric This is the permanent address 2 of the

No -
address2 ** characters user.

permanent- max 20 alphanumeric This is the street for permanent address

No -
street ** characters 1.

permanent-city max 30 alphanumeric

No - This is the city for permanent address 1.
** characters

permanent- This is the local pin code for permanent

max 10 numeric characters No -
pincode ** address 1.

permanent-state max 40 alphanumeric This is the state for permanent address

No -
** characters 1.

permanent- max 20 alphanumeric This is the country for permanent

No -
country ** characters address 1.

personal-phone This is the personal phone number of

max 32 numeric characters or - No -
** the user.

This is the personal mobile number of

personal-cell ** max 30 numeric characters or - No -
the user.

68 Matrix COSEC Web API User Guide

Table: Adding/Editing a User - Parameters

Argument Valid Values Mandatory Default Value Description

max 100 alphanumeric This is the personal email address of

personal-email ** No -
characters the user.

This is the official phone number of the

official-phone ** max 30 numeric characters or - No -
user.

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

This is the official mobile number of the

official-cell ** max 30 numeric characters or - No -
user.

max 100 alphanumeric This is the official email address of the

official-email ** No -
characters user.

Default
organization of
respective
system account
user who is
creating/
updating user
organization 1 to 999999 No This is the ‘Organization’ of the user.
OR

Default
organization
defined in
Enterprise
structure

Default Branch
of respective
system account
user who is
creating/
updating user
branch 1 to 999999 No This is the ‘Branch’ of the user.
OR

Default branch
defined in
Enterprise
structure

Default
Department of
respective
system account
user who is
creating/
updating user
department 1 to 999999 No This is the ‘Department’ of the user.
OR

Default
department
defined in
Enterprise
structure

Matrix COSEC Web API User Guide 69

Table: Adding/Editing a User - Parameters

Argument Valid Values Mandatory Default Value Description

Default Section
of respective
system account
user who is
creating/
updating user
section 1 to 999999 No This is the ‘Section’ of the user.
OR

Default section
defined in
Enterprise
structure

Default
Category of
respective
system account
user who is
creating/
updating user
category 1 to 999999 No This is the ‘Category’ of the user.
OR

Default
category
defined in
Enterprise
structure

Default Grade
of respective
system account
user who is
creating/
updating user
grade 1 to 999999 No This is the ‘Grade’ of the user.
OR

Default grade
defined in
Enterprise
structure

Default
designation of
respective
system account
user who is
creating/
updating user
designation 1 to 999999 No This is the ‘Designation’ of the user.
OR

Default
designation
defined in
Enterprise
structure

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

1 to 9999 No -
incharge user

This field enables/disables the users

ess-login 1 or 0 No 0
ESS login.

70 Matrix COSEC Web API User Guide

Table: Adding/Editing a User - Parameters

Argument Valid Values Mandatory Default Value Description

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.

attendance-via- This enables or disables the users

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

active-directory- This enables/disables the users ESS

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

This is the user’s Active directory

username.

Yes (if active- Note: The active directory username

active-directory- max 128 alphanumeric directory-login provided should not be repeated for any
-
username characters to be other user. Also the active directory
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-

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

This enables/disables the attendance

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

max-personal- This configures the max number of

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

This is the bus route for the user. This is

bus-route 1 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
employment- max 4 alphanumeric Employment This is the roster user’s Employment
No
profile characters contract defined contract.
in Roster

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

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

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

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

roster- Default Policy

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

max 4 alphanumeric This is the hour exception assigned to

hour-exception No -
characters the roster user.

Matrix COSEC Web API User Guide 71

Table: Adding/Editing a User - Parameters

Argument Valid Values Mandatory Default Value Description

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

Default Late In
This is the ‘Late-In policy’ of the user.
Policy defined
lateIn-policy 1 to 99 No in Time &
For a user the policy can be updated
Attendance/
99999 times.
Policies

Default Early
This is the ‘Early-out policy’ of the user.
Out Policy
earlyOut-policy 1 to 99 No defined in Time
For a user the policy can be updated
& Attendance/
99999 times.
Policies

Default This is the ‘Overtime policy’ of the user.

Overtime Policy
overtime-policy 1 to 99 No defined in Time
& Attendance/ For a user the policy can be updated
Policies 99999 times.

Default
This is the ‘Absentee policy’ of the user.
Absentee Policy
absentee-policy 1 to 99 No defined in Time
For a user the policy can be updated
& Attendance/
99999 times.
Policies

Default COFF
This is the ‘COFF policy’ of the user.
Policy defined
coff-policy 1 to 99 No in Time &
For a user the policy can be updated
Attendance/
99999 times.
Policies

This is the access control system pin

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

This is the card number 1 of the user,

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

This is the card number 2 of the user,

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

This is the Access Validity date of the

access-validity- user. Setting this will automatically
ddmmyyyy format No -
date 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.

72 Matrix COSEC Web API User Guide

Table: Adding/Editing a User - Parameters

Argument Valid Values Mandatory Default Value Description

This determines whether the user can

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

This parameter determines the

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

First Shift This field assigns the shift schedule to

shift-schedule 1 to 99 No
Schedule the user.

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

first holiday This field defines the users allowed

holiday-schedule 1 to 99 No
schedule holidays.

This is the ID of the device group.

Note: Any value SET from this API will

overwrite the existing value.

If from the entered Device Group IDs

Maximum length 600
device-group-id only partial values are valid, then assign
NUMCHAR
the valid Device Groups mentioned.

When 99 device (maximum device

allowed) with individual ID of 5
NUMcharacter is SET then 600
NUMcharacter are allowed.

This is the name of the device group.

Multiple device group names are

allowed to pass.

device-group - If maximum 99 device group names are

added, there is a possibility that it would
lead to exceed maximum URL limit.
In such cases the server will notify the
SA via message and the SA needs to
hit multiple API.

smart-access- This field assigns the access route to

1 to 99 No -
route 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.

Matrix COSEC Web API User Guide 73

Table: Adding/Editing a User - Parameters

Argument Valid Values Mandatory Default Value Description

This parameter determines the user’s

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

This defines the max allowed limit for

As specified in
the canteen user for a month.
max-allowed- eCanteen/
0.01 to 999999.99 No
limit Account
This parameter is only for the postpaid
configuration
account users.

This defines the max usage limit per

month for the canteen user beyond
which the user’s canteen account will
be blocked.

As specified in For Account Type= Pre-Paid when this

eCanteen/ parameter is passed while firing API-
max-usage-limit 0.01 to 999999.99 No
Account details should be set for the Pre-Paid
configuration account user.

For Account Type= Post-Paid when this

parameter is passed while firing API-
details should be set for the Post-Paid
account user.

Default
organization
code of
respective
system account
user who is
creating/
organization_co max 6 alphanumeric updating user Organization ID and Organization Code
No
de characters cannot be specified together.
OR

Default
organization
code defined in
Enterprise
structure

Default branch
code of
respective
system account
user who is
creating/
max 6 alphanumeric updating user Branch ID and Branch Code cannot be
branch_code No
characters specified together.
OR

Default branch
code defined in
Enterprise
structure

74 Matrix COSEC Web API User Guide

Table: Adding/Editing a User - Parameters

Argument Valid Values Mandatory Default Value Description

Default
department
code of
respective
system account
user who is
creating/
department_cod max 6 alphanumeric updating user Department ID and Department Code
No
e characters cannot be specified together.
OR

Default
department
code defined in
Enterprise
structure

Default
category code
of respective
system account
user who is
creating/
updating user
max 6 alphanumeric Category ID and Category Code cannot
category_code No
characters be specified together.
OR

Default
category code
defined in
Enterprise
structure

Default grade
code of
respective
system account
user who is
creating/
max 6 alphanumeric updating user Grade ID and Grade Code cannot be
grade_code No
characters specified together.
OR

Default grade
code defined in
Enterprise
structure

Default
designation
code of
respective
system account
user who is
creating/
designation_cod max 6 alphanumeric updating user Designation ID and Designation Code
No
e characters cannot be specified together.
OR

Default
designation
code defined in
Enterprise
structure

Matrix COSEC Web API User Guide 75

Table: Adding/Editing a User - Parameters

Argument Valid Values Mandatory Default Value Description

Default section
code of
respective
system account
user who is
creating/
max 6 alphanumeric updating user Section ID and Section Code cannot be
section_code No
characters specified together.
OR

Default section
code defined in
Enterprise
structure

To specify a leave group ID, for a leave

leave_group 2 Digits - -
group to be assigned to the user.

numeric
week-off-group No - To assign a week-off group to the user
1-99

0 : Disabled
punch-api Punch Marking Via API
1 : Enabled No 1

0 : Disabled Auto-Punch Marking

auto-attendance No 0
1 : Enabled

0 : Disabled Manual Punch Marking

manual-punch No 0
1 : Enabled

Location Data Mandatory from Apps

0 : None
location- Note: - If location is not mentioned in
1 : Any Location No 0
mandatory event when Location mandatory for
2 : Configured Locations
punch is checked then access will be
denied.

0: Disabled It will show invalid argument message if

door-access-api door-access-api 0
1: Enabled value is not 0/1.

FVM-enable 0 or 1 0 FVM Enable Flag.

0 : None
job-assignment-
1 : Fixed 0 If value other than 0, 1, 2 added, return
type
2 : Device Based message for Invalid Argument Value

0 : Disabled
'Restrict Half Day Considerations' flag.
restrict-half-day OR 0
1 : Enabled

76 Matrix COSEC Web API User Guide

Table: Adding/Editing a User - Parameters

Argument Valid Values Mandatory Default Value Description

Default
customgroup1I
D of respective
system account
user who is
creating/
updating user
This is the ID of 'Custom Group 1' of the
customgroup1ID 1-999999 No
user.
OR

Default
customgroup1I
D defined in
Enterprise
structure

Default
customgroup2I
D of respective
system account
user who is
creating/
updating user
This is the ID of 'Custom Group 2' of the
customgroup2ID 1-999999 No
user.
OR

Default
customgroup2I
D defined in
Enterprise
structure

Default
customgroup3I
D of respective
system account
user who is
creating/
updating user
This is the ID of 'Custom Group 3' of the
customgroup3ID 1-999999 No
user.
OR

Default
customgroup3I
D defined in
Enterprise
structure

Default
customgroup1
code of
respective
system account
user who is
creating/
When this code is specified, the system
customgroup1_c max 6 alphanumeric updating user
No will get the code's corresponding id and
ode characters
apply this id to the user.
OR

Default
customgroup1
code defined in
Enterprise
structure

Matrix COSEC Web API User Guide 77

Table: Adding/Editing a User - Parameters

Argument Valid Values Mandatory Default Value Description

Default
customgroup2
code of
respective
system account
user who is
creating/
When this code is specified, the system
customgroup2_c max 6 alphanumeric updating user
No will get the code's corresponding id and
ode characters
apply this id to the user.
OR

Default
customgroup2
code defined in
Enterprise
structure

Default cus-
tomgroup3 code
of respective
system account
user who is cre-
ating/updating
user When this code is specified, the system
customgroup3_c max 6 alphanumeric
No will get the code's corresponding id and
ode characters
OR apply this id to the user.

Default cus-
tomgroup3 code
defined in
Enterprise
structure

To specify Cafeteria usage policy for

the user. If not specified, then cafeteria
cafeteria-usage-
1-99 No - usage policy mapped with specified
policy
enterprise group will be assigned to
user.

0: Disabled If Show-atd-details is not specified, by

Show-atd-details No 1
1: Enabled default it is enabled.

Reporting group is must before

approval-Policy 1 to 999 No -
assigning Approval policy.

Local Time Zone-The date-time of the

punch will be as per the time zone of
the place from where the punch is
0: Server Time
Punch-marking- 0: Server Time Zone marked.
No Zone
timezone 1 : Local Time Zone
Server Time Zone-The date- time of the
punch will be as per the server time
zone.

enable-elevator- It enables/disables Elevator Access

1 or 0 No 0
access-control Control for the user.

This field assigns the floor group for

which user can have elevator rights.
elevator-floor-
1 to 99 No -
group
Applicable only when "elevator-access-
control =1"

0: Disabled It enables/disable Face Recognition for

enable-fr No -
1: Enabled the user.

78 Matrix COSEC Web API User Guide

Table: Adding/Editing a User - Parameters

Argument Valid Values Mandatory Default Value Description

It is used to bypass the face image of

Bypass-face 1 or 0 No 0
user for any access control feature.

It is used to make Face Mandatory For

0 : None Punch via APTA.
1 : Attendance
face-mandatory
2 : Access Control This field should be updated only if
3 : Both "Punch Marking Via API" and "Manual
Punch Marking" is set as 1

Max 15 alphanumeric
If Id is mentioned, ignore this
prefix characters
parameter.
A-Z
No The Prefix tag shows the fixed text
a-z
which is to be used while creating new
0-9
User Id's
/_ .@:

Mandatory if ID is not mentioned.

If Id is mentioned, ignore this
Auto-generation-
parameter.
serial-length
1 to 15 No -
It shows the number of characters that
are to be appended after prefix text.
Also, these numbers of characters will
follow a sequential order.

"The 'zero-padding' tag defines whether

Zero-padding 0: unchecked in mentioned <auto-generation-serial-
No
1: checked length> '0(zero)' is to be appended or
not.

pin- 0 : Disabled This provide pin authentication on the

No 0
authentication 1 : Enabled devices.

driving-license-
This is the date of expiry of Driving
expiry ddmmyyyy No -
License

passport-expiry
ddmmyyyy No - This is the date of expiry of Passport.

This is a field that shows whether user/

0 : Not Blacklisted
worker is blacklisted or not.
1 : Blacklisted
Blacklisted No - NOTE: If an user is already blacklisted
2 : Blacklist and Revoke
and Blacklisted = 1 or 2 is passed, then
Devices
no action should be performed.

Max 50 Chars
A-Z
Blacklisted-
a-z This specifies the reason for being
reason No -
0-9 blacklist.
[space]
!@$*()_-+\[],.:

0 : unchecked enabled only when Location Mandatory

punch-reason-flg No 0
1 : checked For Punch = 0 (None) / 1 (Any Location)

Matrix COSEC Web API User Guide 79

Table: Adding/Editing a User - Parameters

Argument Valid Values Mandatory Default Value Description

If control type for repeated

custom fields is selected as
Textbox in Global Policy:

Max 100 Alphanumeric

Characters:
A-Z
field<no>
a-z
0-9
(where <no> will
[]().-_ / Mandatory field, if ‘Active’ & ‘Mandatory’
vary from 1 to
<Space> - checkbox is checked for respective
10, the user has
No custom fields in Global Policy.
to enter any one
number here If control type for repeated
from 1 to 10) custom fields is selected as
Date in Global Policy:

ddmmyyyy

When Multi Language is

enabled, Invalid character set =
SET1

authorized-host- 0: Pending This is a flag for making a user

user 1: Authorized No - Authorized Host User

visitor-device-
Max 600 Varcharacters No - This is the ID of the visitor device group.
group-id

0= None
This is a field that allows to configure
enable-offline- 1= Allow Without Discount
No 0 the transaction type to be allowed when
transaction 2= Allow With Discount
device is offline.

1 : enabled In capturing the snap of users when

capture-photo No 0
0 : disabled punching from application like APTA.

This field should be updated only if

“Punch Marking Via API” and “Manual
apta-face-anti- 0 : Disabled
No 0 Punch Marking” is set as 1 and “Punch
spoofing 1 : Enabled
Mandatory For Punch” is set as 1 or 2
or 3 else should be validated.

This defines the max usage limit per

day for the canteen user beyond which
the user’s canteen account will be
blocked.

As specified in For Account Type= Pre-Paid when this

max-usage-limit- eCanteen/ parameter is passed while firing API-
0.01 to 999999.99 NA
day Account details should be set for the Pre-Paid
configuration account user.

For Account Type= Post-Paid when this

parameter is passed while firing API-
details should be set for the Post-Paid
account user.

80 Matrix COSEC Web API User Guide

 The assigned Device Group can be revoked from the user by passing the value of “device-group” as empty
or blank. e.g: "http://localhost/COSEC/api.svc/v2/user?action=set;id=1542;device-group= "

When "device-group-id" (Device Group ID) & "device-group" (Device Group Name) both are supplied with
an API request, "device-group-id" will be considered first. But If "Device-group-id" is supplied with blank or
empty value & "device-group" is supplied with valid value, in this case device group with supplied valid
device group name will be assigned.

If maximum limit in case of IDs is reached, for e.g., if auto - generation serial length=2 and zero-padding
=1, and all IDs from 00 to 99 are already existing, then message returns: " failed: Maximum limit reached
for this configuration for ID creation. "

Example1

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

http://192.168.104.16/cosec/api.svc/v2/user?action=set;id=202;name=sam;module=U

Sample Response:

success: <response code> : successful

Example2

Sample Request:

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

http://192.168.104.16/cosec/api.svc/v2/user?action=set;id=202;date-of-
birth=22061978;gender=male;nationality=indian;blood-group=b+

Sample Response:

success: <response code> : successful

Example3

Sample Request:

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

http://matrixserver/api.svc/v2/user?action=set;id=202;name=Samuel Jackson

Sample Response:

success: <response code> : successful

Example4

Sample Request:

Matrix COSEC Web API User Guide 81

To set the Reporting group and Approval policy for the user.

http://192.168.104.12/cosec/api.svc/v2/user?action=set;id=2;name =Isha Shinde;module =U;reporting-

incharge=1;approval-Policy=5

Here Reporting In-charge is Reporting Group ID

Sample Response:

success: 0070200001 : successful

82 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

http://<servername>/api.svc/v2/user?action=setphoto;<argument>=<value>...

Parameters

Table: Adding User Photograph - Parameters

Argument Valid Values Mandatory Default Value Description

Max 15 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 image.jpg
is located in the following FTP location: ftp://abc/xyz/image.jpg

Sample Request:

http://matrixserver/api.svc/v2/user?action=setphoto;id=202;path=ftp://abc/xyz/
image.jpg;ftpusername=sam;ftppassword=1234

Matrix COSEC Web API User Guide 83

Sample Response:

success: <response code> : successful

84 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

http://<servername>/api.svc/v2/user?action=delete;<argument>=<value>...

Parameters

Table: Deleting a User - Parameters

Argument Valid Values Mandatory Default Value Description

This can have values mentioned in

Range.

1 to 999999 (for all the If argument range is not mentioned and

ranges except all & individual argument ID is specified,
user) then User id should be considered.
Yes
Max 15 alphanumeric Argument ID can have multiple ids as
Id -
characters (for user) No (Range = value separated with comma.
A to Z All) For example Id=1,2,…..999.
a to z
0 to 9 In case user-id /user-id & user-filter are
/_\\.@: provided along with id/id & range,
priority should always be given to user-
id / user-id & user-filter. Value of id/id &
range to be ignored in that case.

All In this argument only single value

Organization should be allowed.
Branch
Department If argument range's value is specified
Designation as "All", ids of all the users that login
Section User (If argument user has rights over will return
Range No
Category Range is not specified)
Grade In case user-id /user-id & user-filter are
User provided along with id/id & range,
Custom-group-1 priority should always be given to user-
Custom-group-2 id / user-id & user-filter.
custom-group-3

Example

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

Sample Request:

http://matrixserver/api.svc/v2/user?action=delete;id=202

Matrix COSEC Web API User Guide 85

Sample Response:

success: <response code> : successful

86 Matrix COSEC Web API User Guide

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

http://<servername>/api.svc/v2/user?action=enroll;<argument>=<value>...

Parameters

Table: Enrolling a User - Parameters

Argument Valid Values Mandatory Default Value Description

Max 15 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 = Door V1,
2 = Panel Lite
3 = Door V2,
4 = NGT Direct Door,
5 = Wireless Direct Door
6 = Path Controller
device-type 0-9 Yes -
7 = PVR Direct Door
8 = Panel200
9 = Vega Controller
11 = Arc Controller
12 = Door V3
15 = Door FMX
19 = Door V4
17 = ARC DC 200
20 = ARGO
21 = ARGO FACE

This is the device identification number

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

Note: Login user must have necessary

rights on the device on which the
enrollment is to be performed.

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

Matrix COSEC Web API User Guide 87

Table: Enrolling a User - Parameters

Argument Valid Values Mandatory Default Value Description

This is the type of enrollment.

fp,
Note: - Only Read-Only cards
card,
enroll-type Yes - supported.
palm
duressfp
Enroll-type=duressfp added to support
Duress Finger Enrollment.

1 to 10 (for enroll-
This is the count for the enroll type
type=fp)
(finger print, card or palm) to be
1,2 (for enroll-
enrolled for the respective user id.
type=card)
enroll-count Yes -
1 to 10 (for enroll-
If user tries to enroll more than two
type=palm)
duress fingers, then as per existing, the
1,2 (for enroll-
user will be restricted from device side.
type=duressfp)

Example

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

Sample Request:

http://matrixserver/api.svc/v2/user?action=enroll;id=1;device-type=1;device-id=1;enroll-type=fp;enroll-
count=2

Sample Response:

success: <response code> : successful

88 Matrix COSEC Web API User Guide

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

http://<servername>/api.svc/v2/user?action=set-credential;<argument>=<value>...

Parameters

Table: Setting Credentials on Device - Parameters

Argument Valid Values Mandatory Default Value Description

Max 15 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
Characters (for card)
max 21 characters= 20
This is the data of respective credential
numeric + comma (for
type, which is to be stored at given
data card) Yes -
index number for the respective user
ID.
Note: - For credential
type = finger print, user
should send finger
print templates into
hexadecimal.

0 = normal Finger
duress N 0= normal Finger
1 = duress Finger

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:

http://matrixserver/api.svc/v2/user?action=set-credential;id=1;credential-
type=card;data=12345678901234567890

Matrix COSEC Web API User Guide 89

Sample Response:

success: <response code> : successful

90 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

http://<servername>/api.svc/v2/user?action=del-credential;<argument>=<value>...

Parameters

Table: Deleting Credentials from Device - Parameters

Argument Valid Values Mandatory Default Value Description

This can have values mentioned in

Range.

1 to 999999 (for all the If argument range is not mentioned and

ranges except all & individual argument ID is specified,
user) then User id should be considered.
Yes
Max 15 alphanumeric Argument ID can have multiple ids as
Id No (Range = -
characters (for user) value separated with coma.
All)
A to Z For example Id=1,2,….999
a to z
0 to 9 In case user-id /user-id & user-filter are
/_\\.@: provided along with id/id & range,
priority should always be given to user-
id / user-id & user-filter. Value of id/id &
range to be ignored in that case

All In this argument only single value

Organization should be allowed.
Branch
Department If argument range's value is specified
Designation as "All", ids of all the users that login
Section User (If argument user has rights over will return
Range No
Category Range is not specified)
Grade In case user-id /user-id & user-filter are
User provided along with id/id & range,
Custom-group-1 priority should always be given to user-
Custom-group-2 id / user-id & user-filter. Value of id/id &
custom-group-3 range to be ignored in that case.

This is the type of credential.

When credential-type = fp, should

credential-type fp, card, palm, face Yes - delete the fingerprints for Duress
Finger (along with the parameter which
is used to identify Duress Finger) same
as per normal Finger.

This process is irreversible. Please proceed with caution.

This API supports Read-Only cards only.

Matrix COSEC Web API User Guide 91

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:

http://matrixserver/api.svc/v2/user?action=del-credential;id=1;credential-type=fp

Sample Response:

success: <response code> : successful

92 Matrix COSEC Web API User Guide

Searching a User

This shall be used to search for a particular user based on parameters like user ID, user name or reference code.
This API will help third party applications to fetch user IDs based on username or reference code associated with a
user. This user ID can then be used by the application.

Action

action=get

Syntax

http://<servername>/api.svc/v2/search-user?action=get;<argument>=<value>…

User Rights

User Rights

System Account Enabled.

ESS Enabled. ESS user can fetch details for any other ESS user.

Only those records will be fetched on which the login user has rights.

Parameters

Table: Searching a User - Parameters

Argument Valid Values Mandatory Default Value Description

1: User ID
2: User Name
3: Reference Code
4: Integration Reference
5: Vehicle Registration No
6: Organization Name
7 : Branch Name
This specifies the criteria on which the
search-criteria 8 : Department Name Yes -
search will be based.
9 : Designation Name
10: Section Name
11: Category Name
12: Grade Name
13: Custom Group 1 Name
14: Custom Group 2 Name
15: Custom Group 3 Name

Matrix COSEC Web API User Guide 93

Table: Searching a User - Parameters

Argument Valid Values Mandatory Default Value Description

The valid values for search-string will depend

on the search-criteria.

For search-criteria=1
Allowed Characters:
A-Z
a-z
0-9
/_\\.@:

For search-criteria=2
Allowed Characters:
A-Z
a-z
0-9
-_. ()[]

For search-criteria=3
if search-criteria=2 (i.e. for
1 to 99999999 (max 8 numeric digits)
user-name) minimum three
characters.
search-string Yes - For search-criteria=4
For other options, minimum
max 20 alphanumeric characters
one character.
For search-criteria=5

max 15 alphanumeric characters

For search-criteria=6 to 15

A-Z
a-z
0-9
()[ ]_-
.(full stop)
/&
,(comma)
@
'(single Quote)
[space]
max 45 characters

If record-count=0, or the parameter is not

mentioned at all, all records will be returned
record-count numeric No - for the mentioned search-string. If any other
numeric value is mentioned, then only those
number of records will be returned.

94 Matrix COSEC Web API User Guide

Table: Searching a User - Parameters

Argument Valid Values Mandatory Default Value Description

Non mandatory field.

Default value = 0.

Ignore this field if passed when search-

criteria!=1 or 2 i.e. User ID or User Name.

Conditions:
0 : All 1.Argument mentioned, but value not
filter 1 : Active Users No 0 specified, then ignore this parameter.
2 : Inactive Users
2.If filter=0 is specified, return all users
configured in the system.

3.If filter=1 is specified, return only active

users configured in the system.

4.If filter=2 is specified, return only

inactive users configured in the system

Response Fields

Table: Searching a User - Response Fields

Field Name Tag Name Valid Values Remarks

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

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

Short Name short-name max 15 alphanumeric characters -

1 : Active
Active active -
0 : Inactive

Organization Code organization - -

Branch Code branch - -

Designation Code designation - -

Section Code section - -

Department Code department - -

Category Code category - -

Matrix COSEC Web API User Guide 95

Table: Searching a User - Response Fields

Field Name Tag Name Valid Values Remarks

Grade Code grade - -

male,
Gender gender female, -
na

na, a+, a-, b+, b-, ab+, ab-, o+, o-,

Blood Group blood-group A1+, A1-, A1B-, A1B+, A2-, A2+, -
A2B+, A2B-, B1+

Official Cell official-cell - -

Official Phone official-phone

- -

Official Extension
official-extension - -

Official Email official-email - -

Personal Cell personal-cell - -

Personal Phone personal-phone

- -

Personal Email personal-email - -

Reporting Group ID rg_id 1-9999 -

Reporting Group Name rg_name - -

In-Charge 1 ID rg_incharge_1 - -

In-Charge 1 Name
rg_incharge_1_name - -

In-Charge 2 ID rg_incharge_2 - -

In-Charge 2 Name
rg_incharge_2_name - -

In-Charge 3 ID rg_incharge_3 - -

In-Charge 3 Name
rg_incharge_3_name - -

96 Matrix COSEC Web API User Guide

Table: Searching a User - Response Fields

Field Name Tag Name Valid Values Remarks

In-Charge 4 ID rg_incharge_4 - -

In-Charge 4 Name
rg_incharge_4_name - -

In-Charge 5 ID rg_incharge_5 - -

In-Charge 5 Name
rg_incharge_5_name - -

Vehicle Registration No vehicle-reg-no - -

This will give the code as

specified in User Config >
Reference Code reference-code 1 to 99999999
Basic > Optional >
Reference ID

Organization Name organization-name Return Organization Name

of User based on search
criteria

Return Branch Name of

Branch Name branch-name User based on search
criteria

Return Designation Name

Designation Name designation-name of User based on search
criteria

Return Section Name of

Section Name section-name User based on search
criteria

Return Department Name

Department Name department-name of User based on search
criteria

Return Category Name of

Category Name category-name User based on search
criteria

Return Grade Name of

Grade Name grade-name User based on search
criteria

Custom Group 1 Code customgroup1_code

Return Custom Group 1

Custom Group 1 Name customgroup1_Name Name of User based on
search criteria

Custom Group 2 Code customgroup2_code

Return Custom Group 1

Custom Group 2 Name customgroup2_Name Name of User based on
search criteria

Matrix COSEC Web API User Guide 97

Table: Searching a User - Response Fields

Field Name Tag Name Valid Values Remarks

Custom Group 3 Code customgroup3_code

Return Custom Group 1

Custom Group 3 Name customgroup3_Name Name of User based on
search criteria

Return Approval Policy ID

Approval Policy ID approval-policy 1-999
of the User

Return Approval Policy

Approval Policy Name approval-policy-name
Name of the User

Example

This example demonstrates a sample request to search a user

Sample Request:

http://192.168.104.12/cosec/api.svc/v2/search-user?action=get;search-criteria=1;search-string=1

Sample Response:

user-id|user-name|short-
name|active|organization|branch|designation|section|department|category|grade|gender|blood-
group|official-cell|official-phone|official-extension|official-email|personal-cell|personal-
phone|personal-
email|rg_id|rg_name|rg_incharge_1|rg_incharge_1_name|rg_incharge_2|rg_incharge_2_name|vehicle-reg-
no|reference-code|organization-name|branch-name|designation-name|section-name|department-name|category-
name|grade-
name|customgroup1_code|customgroup1_name|customgroup2_code|customgroup2_name|customgroup3_code|customgr
oup3_name|approval-policy|approval-policy-name
1|Chirag|Chirag|1|ORG1|BRC1|DSG1|SEC1|DPT1|CTG1|GRD1|NA|NA||||||||1|QA
Group|101|Khushbu||||1|Organization-1|Branch-1|Designation-1|Section-1|Department-1|Category-1|Grade-
1|CG1|Custom Group 1|CG2|Custom Group 2|CG3|Custom Group 3||
101|Khushbu|Khushbu|1|ORG1|BRC1|DSG1|SEC1|DPT1|CTG1|GRD1|NA|NA|||||||[email protected]||||||||
101|Organization-1|Branch-1|Designation-1|Section-1|Department-1|Category-1|Grade-1|CG1|Custom Group
1|CG2|Custom Group 2|CG3|Custom Group 3||
102|Shruti Patki|Shruti
Patki|1|ORG1|BRC1|DSG1|SEC1|DPT1|CTG1|GRD1|NA|NA|||||||||||||||1689|Organization-1|Branch-
1|Designation-1|Section-1|Department-1|Category-1|Grade-1|CG1|Custom Group 1|CG2|Custom Group
2|CG3|Custom Group 3||
1687|Aditi Ajay Gupta_Ahmedabad|Aditi Ajay
Gupt|1|ORG1|BRC1|DSG1|SEC1|DPT1|CTG1|GRD1|NA|NA|919429063421||||919687624826||[email protected]|
1|QA Group|101|Khushbu||||1687|Organization-1|Branch-1|Designation-1|Section-1|Department-1|Category-
1|Grade-1|CG1|Custom Group 1|CG2|Custom Group 2|CG3|Custom Group 3||
JPC1|Darshna|Darshna|1|ORG1|BRC1|DSG1|SEC1|DPT1|CTG1|GRD1|NA|NA||||||||1|QA
Group|101|Khushbu||||102|Organization-1|Branch-1|Designation-1|Section-1|Department-1|Category-1|Grade-
1|CG1|Custom Group 1|CG2|Custom Group 2|CG3|Custom Group 3||
<EOT>

98 Matrix COSEC Web API User Guide

Fetching Reporting Group Members

This API can get a list of all the members assigned to the logged-in user’s reporting group. The login user must be
a reporting in-charge to call this API.

Action

action=get

Syntax

http://<servername>/api.svc/v2/group-members?action=get;<argument>=<value>...

User Rights

User Rights

System Account Enabled

ESS Enabled

Parameters

Table: Fetching Reporting Group Members - Parameters

Argument Valid Values Mandatory Default Value Description

The Reporting In-charge’s User ID.

userid 15 Char. Yes -
Note: Returns only those records on
which the Login user has rights.

0 : User Id Used to search for a particular member

search-by No -
1: User Name in the user’s reporting group.

A set of characters to identify the user,

based on username or user ID.
Yes (Only if
e.g. :
search-by
search-string one/three characters -
argument is
http://matrix-server/api.svc/v2/ group-
provided)
members?action=get;userid=1234;sear
ch-by=1;search-string=kma

To specify the number of records that

should be returned.

If record-count=0, or the parameter is

not mentioned, then all the records will
record-count numeric No -
be returned.

If any other numeric value is mentioned

then only those number of records will
be returned.

Matrix COSEC Web API User Guide 99

Table: Fetching Reporting Group Members - Parameters

Argument Valid Values Mandatory Default Value Description

Non mandatory field.

Default value = 0.

Conditions:

1.Argument mentioned, but value not

0 : All specified, then ignore this parameter.
filter 1 : Active Users No 0
2 : Inactive Users 2.If filter=0 is specified, return all users
configured in the system.

3.If filter=1 is specified, return only

active users configured in the system.

4.If filter=2 is specified, return only

inactive users configured in the system.

Response Fields

Table: Fetching Reporting Group Members - Response Fields

Field Name Tag Name Valid Values Remarks

Reporting group ID for

Reporting Group Id group-id 1-9999 which the logged in user is
reporting group in-charge.

Reporting group Name for

Reporting Group Name group-name upto 30 characters which the logged in user is
reporting group in-charge.

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

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

Short Name short-name upto 15 alphanumeric characters -

The system will allow all the configured RIC’s in the Reporting Group for fetching the information.

100 Matrix COSEC Web API User Guide

CHAPTER 6 Enterprise Structure

The Enterprise Structure APIs allow the user to retrieve, set, as well as update data related to various groups as
per the requirements of 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

http://<servername>/api.svc/v2/<enterprise-group>?action=<value>;<argument>=<value>...

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:

http://<servername>/api.svc/v2/organization?action=<value>;<argument>=<value>...

Similarly, for Branch, send:

http://<servername>/api.svc/v2/branch?action=<value>;<argument>=<value>...

Matrix COSEC Web API User Guide 101

 If an enterprise group is renamed on the COSEC system (say, “organization” renamed as “company”), the
<request-type> used in the URL should still use the original group name (i.e. “organization”) as defined on
COSEC, irrespective of the renaming.

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

• Obtaining Enterprise Group Details

• Adding an Enterprise Group
• Updating Enterprise Group Details
• Obtaining Custom Group details
• Adding Custom Group details
• Updating Custom Enterprise Group

User Rights

User Rights

Enabled.

User must have rights on the following pages, depending on the type of enterprise group to
be accessed (COSEC Web Application):

Enterprise Structure > Organization

System Account
Enterprise Structure > Branch
Enterprise Structure > Department
Enterprise Structure > Designation
Enterprise Structure > Section
Enterprise Structure > Category
Enterprise Structure > Grade

ESS Enabled if user has ESS rights enabled.

102 Matrix COSEC Web API User Guide

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

http://<servername>/api.svc/v2/<enterprise-group>?action=get;<argument>=<value>...

Parameters

Table: Obtaining Enterprise Group Details - Parameters

Argument Valid Values Mandatory Default Value Description

1-999999 This is the ID of the specific enterprise

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

Response Fields

Table: Obtaining Enterprise Group Details - Response Fields

Field Name Tag Name Valid Values Remarks

ID id 1-999999 -

Allowed Characters
A-Z
Code code 6 characters. (max) a-z
0-9
_

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

Allowed Characters
A-Z
Short Name short-name 15 characters a-z
0-9
-_. ()

Allowed Characters
A-Z
Description description 250 characters (max). a-z
0-9
_.,()[]:@!$*+/\-

0 : not default
default default -
1 : set as default

Matrix COSEC Web API User Guide 103

Table: Obtaining Enterprise Group Details - Response Fields

Field Name Tag Name Valid Values Remarks

Returned only for

“Designation” group. This
Wage Level wage-level Max 4 characters
field is returned only if
Roster license is available.

Returned only for

6 hex values string.
“Department” group. This
color-code color-code Range from
argument is valid only if
000000 – FFFFFF
Roster license is available.

Example

Fetching an organization by ID ‘7’.

Sample Request:

http://matrixserver/api.svc/v2/organization?action=get;id=7

Sample Response:

id|code|name|short-name|description|default
7|APEX|Apex Industries Pvt. Ltd.|Apex Industries||0
<EOT>

104 Matrix COSEC Web API User Guide

Adding an Enterprise Group

User can add a new Organization, Branch, Department etc. and set its configuration on the COSEC system.

Action

action=set

Syntax

http://<servername>/api.svc/v2/<enterprise-group>?action=set;<argument>=<value>...

Parameters

Table: Adding an Enterprise Group - Parameters

Argument Valid Values Mandatory Default Value Description

6 Characters. (max)
Duplicate Code is not
allowed
Allowed Characters
code Yes - The Enterprise Group Code.
A-Z
a-z
0-9
_

45 characters
Allowed Characters
The Enterprise Group name. If valid
A-Z
name Yes - characters are more than 45; then it will
a-z
be ignored.
0-9
-_. ()[]

15 characters
Allowed Characters
By default, first 15 For short-name. If these characters
A-Z
short-name No characters of Name contain “[]”, the short-name becomes
a-z
will be considered. invalid.
0-9
-_. ()

250 characters (max)

Allowed Characters
A-Z Stored as blank, if no A description about the Enterprise
description No
a-z value supplied. Group, if required.
0-9
_.,()[]:@!$*+/\-

0 (not default) or 1 (set To specify whether the group is a

default No Not default
as default) default group or not.

This argument must be supplied only

for the “Department” group.
6 hex values string.
color-code Range from No -
This argument is valid only if Roster
000000 – FFFFFF
license is available else this parameter
can be ignored.

Yes (Only for This argument must be supplied only

Valid wage level ID, as
“Designation” for “Designation” group.
defined/created in
wage-level group and - This field is mandatory only if roster
cosec web roster.
Roster license is available. Else this field can
Max 4 chars
License) be ignored.

Matrix COSEC Web API User Guide 105

Updating Enterprise Group Details

Send a request to update the configuration for an existing Organization, Branch, Department etc. on the COSEC
database.

Action

action=update

Syntax

http://<servername>/api.svc/v2/<enterprise-group>?action=update;<argument>=<value>...

Parameters

Table: Updating Enterprise Group Details - Parameters

Argument Valid Values Mandatory Default Value Description

This is the Enterprise Group ID. The ID

id 1-999999 Yes - is system-generated everytime a new
group is defined.

6 Characters. (max)
Duplicate Code is not
allowed
Allowed Characters
code Yes - The Enterprise Group Code.
A-Z
a-z
0-9
_

45 characters
Allowed Characters The Enterprise Group name. If valid
A-Z characters are more than 45; then it will
name Yes -
a-z be ignored.
0-9
-_. ()[]

15 characters
Allowed Characters
By default, first 15 For short-name. If these characters
A-Z
short-name No characters of Name contain “[]”, the short-name becomes
a-z
will be considered. invalid.
0-9
-_. ()

250 characters (max)

Allowed Characters
A-Z Stored as blank, if no To edit the Enterprise Group
description No
a-z value supplied. description.
0-9
_.,()[]:@!$*+/\-

0 (not default) or 1 (set To specify whether the group is a

default No Not default
as default) default group or not.

This argument must be supplied only

for the “Department” group.
6 hex values string.
color-code Range from No -
This argument is valid only if Roster
000000 – FFFFFF
license is available else this parameter
can be ignored.

106 Matrix COSEC Web API User Guide

Table: Updating Enterprise Group Details - Parameters

Argument Valid Values Mandatory Default Value Description

This argument must be supplied only

Yes (Only for
Valid wage level ID, as for “Designation” group.
“Designation”
defined/created in
wage-level group and -
cosec web roster. This field is mandatory only if roster
Roster
Max 4 chars license is available. Else this field can
License)
be ignored.

Matrix COSEC Web API User Guide 107

Obtaining Custom Group details

This API is used to fetch the list of custom enterprise group’s ID and its name. You can get the details of Custom
Group1, Custom Group2, Custom Group3.

Action

action= get

Syntax

http://<servername>/api.svc/v2/custom-group-1?action=get;<argument>=<value>...

For Custom group2 and Custom group3 update the syntax with custom-group-2 and custom group-3 respec-
tively.

Parameters

Table: Getting Custom Enterprise Group - Parameters

Argument Valid Values Mandatory Default Value Description

This is the min to max range. In case of

a system with only 1-50 id defined then
valid range shall be 1-50.
Id 1-999999 Yes all
The user can select multiple id, each
separated by ", (comma)" e.g.:"1, 3, 7,
9" or a range of id E.g."1-50".

Response Fields

Table: Getting Custom Enterprise Group - Response Fields

Field Name Tag Name Valid Values Remarks

ID id 1-999999 -

Allowed Characters
A-Z
Code code 6 characters. (max) a-z
0-9
_

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

Allowed Characters
A-Z
Short Name short-name 15 Characters a-z
0-9
-_. ()[]

Allowed Characters
A-Z
Description description 250 characters (max). a-z
0-9
_.,()[]:@!$*+/-

108 Matrix COSEC Web API User Guide

Table: Getting Custom Enterprise Group - Response Fields

Field Name Tag Name Valid Values Remarks

0 : not default
default default -
1 : set as default

Matrix COSEC Web API User Guide 109

Adding Custom Group details

This API is used to add the custom enterprise group. You can add Custom Group1, Custom Group2 and Custom
Group3.

Action

action= set

Syntax

http://<servername>/api.svc/v2/custom-group-1?action=set;<argument>=<value>...

For Custom group2 and Custom group3 update the syntax with custom-group-2 and custom group-3
respectively.

Parameters

Table: Adding an Enterprise Group - Parameters

Argument Valid Values Mandatory Default Value Description

45 characters
Allowed Characters
A-Z
name Yes - The Custom Enterprise Group name.
a-z
0-9
-_. ()[] [space]

6 Characters. (max)
Duplicate Code is not
allowed
Allowed Characters
code Yes - The Custom Enterprise Group Code.
A-Z
a-z
0-9
_

15 characters
Allowed Characters
By default, first 15 For short-name. If these characters
A-Z
short-name No characters of Name contain “[]”, the short-name becomes
a-z
will be considered. invalid.
0-9
-_. ()

250 characters (max)

Allowed Characters
A-Z Stored as blank, if no A description about the Enterprise
description No
a-z value supplied. Group, if required.
0-9
_.,()[]:@!$*+/\-

0 (not default) or 1 (set To specify whether the group is a

default No Not default
as default) default group or not.

110 Matrix COSEC Web API User Guide

Updating Custom Enterprise Group

This API is used to update the custom enterprise group. You can get the details of Custom Group1, Custom
Group2, Custom Group3.

Action

action= update

Syntax

http://<servername>/api.svc/v2/custom-group-1?action=update;<argument>=<value>...

For Custom group2 and Custom group3 update the syntax with custom-group-2 and custom group-3
respectively.

Parameters

Same as Adding Custom Group details.

Matrix COSEC Web API User Guide 111

112 Matrix COSEC Web API User Guide
CHAPTER 7 Time and Attendance

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

Get APIs
• Getting Daily Attendance Data

• Getting Monthly Attendance Data

• Getting Attendance Correction Details

• Getting Short Leave/Official IN-OUT Entries

• Getting Attendance Records for Authorization

• Getting Event Records for Authorization

• Getting Overtime/C-OFF Authorization Records

• In/Out Reasons

• Getting Shift Wise Count

• Getting Site Wise Count

• Getting Shift-Site Wise Count

• Getting Site Wise User Detail

• Getting Overtime Application

Set APIs

• Applying for Attendance Correction

• Approving Attendance Correction

• Making Short Leave/Official IN-OUT Entries

• Short Leave/Official In-Out Authorization

Matrix COSEC Web API User Guide 113

 • Authorizing Attendance

• Authorizing Events

• Authorizing Overtime/C-OFF

• Setting Overtime Application

• Overtime Approval

Update API

• Updating Overtime Application

Delete API

• Deleting Attendance Correction Applications

• Deleting Overtime Application

Command API

• Processing Monthly Attendance

114 Matrix COSEC Web API User Guide

Getting Daily Attendance Data

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

Action

action=get

Syntax

http://<servername>/api.svc/v2/attendance-daily?action=get;<argument>=<value>...

User Rights

User Rights

System Account Enabled

ESS Enabled

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
designation All, if range is not
System support mentioned ranges.
section mentioned, then
range
category consider it to be "all"
grade by default.
custom-group-1
custom-group-2
custom-group-3
user

Matrix COSEC Web API User Guide 115

Table: Getting Daily Attendance Data - Parameters

Argument Valid Values Mandatory Default Value Description

1 to 999 (for all the

ranges except all &
user)
15 alphanumeric Each range (except all) shall have
Char. (for user) specific id.
A to Z System should allow user to select
Yes, if
a to z multiple id, each separated by ",
mentioned
Id 0 to 9 (comma)" e.g.:"1, 3, 7, 9…"
range is other
/_\\.@: Or
than all.
Note: This is the min to Select a range of id
max range. In case of E.g."1-50".
a system with only 1-
50 id defined then valid
range shall be 1-50.

If mentioned, only those records will be

shown for which:
shift-end-elapsed HH:MM-HH:MM No - [API Request Date Time - Range(to)]
<= Working Shift End Date Time <=
[API Request Date Time - Range(from)]

0: display name (As

per export template
config) If “return-field-name” is not mentioned
return-field-name 1: actual field (As per No - the response will be as per existing
view column) system (i.e. 0 = display name)
2: both

0 : inactive
Active Return users as per their active flag
1: active No 1
status.
2:all

0
0 = Process Date If parameter is not
filter-date-by 1 = Process Date No mentioned the
Updated response will be as per
existing system.

Response Fields

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

User ID USERID 15 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 -

116 Matrix COSEC Web API User Guide

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

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 -

Process Date Updated PROCESSDATE_U 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 -

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 -

Matrix COSEC Web API User Guide 117

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

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

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 -

118 Matrix COSEC Web API User Guide

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

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 HHHHHH: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 -

Authorized OT AUTHORIZEDOVERTIME HHHHHH:MM -

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 -

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 -

Matrix COSEC Web API User Guide 119

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

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

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

120 Matrix COSEC Web API User Guide

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

Calculated as per Net-

Net Work Hours NETWORKHRS HHHHHH: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 available.Else
blank. From V10R2,
In/Out Reason for Punch 1 punch_reason1 30 alphanumeric characters
Manually entered reasons
will also be considered.

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 -

Actual OT for OT1 OVERTIME1 minutes Value of actual overtime

Actual OT for OT2 OVERTIME2 minutes Value of actual overtime

Actual OT for OT3 OVERTIME3 minutes Value of actual overtime

Actual OT for OT4 OVERTIME4 minutes Value of actual overtime

Actual OT for OT5 OVERTIME5 minutes Value of actual overtime

Value of authorized
Authorized OT for OT1 AUTHOT1 minutes
overtime

Value of authorized
Authorized OT for OT2 AUTHOT2 minutes
overtime

Value of authorized
Authorized OT for OT3 AUTHOT3 minutes
overtime

Value of authorized
Authorized OT for OT4 AUTHOT4 minutes
overtime

Value of authorized
Authorized OT for OT5 AUTHOT5 minutes
overtime

Valid Characters :
A-Z
a-z
Custom Field 1-10 field1-10 upto 100 characters
0-9
space
[]().-_

Short Leave Count short_leave_count 0-99 Availed Short Leave Count

Matrix COSEC Web API User Guide 121

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

Availed Short Leave

Short Leave Hours short_leave_hours HH:MM
Duration

Official Hours official_hours HH:MM Availed Official Duration

Allowed Characters
A-Z
Organization Name organization_name 40 Characters a-z
0-9
-_. ()[]

Allowed Characters
A-Z
Branch Name branch_name 40 Characters a-z
0-9
-_. ()[]

Allowed Characters
A-Z
Designation Name designation_name 30 Characters a-z
0-9
-_. ()[]

Allowed Characters
A-Z
Section Name section_name 30 Characters a-z
0-9
-_. ()[]

Allowed Characters
A-Z
Department Name department_name 30 Characters a-z
0-9
-_. ()[]

Allowed Characters
A-Z
Category Name category_name 30 Characters a-z
0-9
-_. ()[]

Allowed Characters
A-Z
Grade Name grade_name 30 Characters a-z
0-9
-_. ()[]

Custom Group 1 ID CustomGroup1ID 1-999999

Custom Group 2 ID CustomGroup2ID 1-999999

Custom Group 3 ID CustomGroup3ID 1-999999

Allowed Characters
A-Z
Custom Group 1 Name CustomGroup1_Name 45 Characters a-z
0-9
-_. ()[]

122 Matrix COSEC Web API User Guide

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

Allowed Characters
A-Z
Custom Group 2 Name CustomGroup2_Name 45 Characters a-z
0-9
-_. ()[]

Allowed Characters
A-Z
Custom Group 3 Name CustomGroup3_Name 45 Characters a-z
0-9
-_. ()[]

Allowed Characters

A -Z
a-z
0-9
()
[]
_ (underscore)
- (Hyphen)

Full Name full-name max 200 alphanumeric characters . (full Stop)

/
&
, (comma)
@
' (single quote)
[Space]

When Multi Language is

On, Invalid Character set =
Set3

Defines the total Availed

Hourly Paid Leave Hours
Hourly Paid Leave Hours AVAILEDPLHOURS HH:MM
for that particular
attendance day

Defines the total Availed

Hourly Unpaid Leave
Hourly Unpaid Leave Hours AVAILEDULHOURS HH:MM
Hours for that particular
attendance day

For Panels : 0
1-255 (device-type = 8)
For Direct Doors : 1
Door ID for Punch1 DID1
For Panel Doors : As
0-99 (All Others)
configured

5 numeric digits
Master Controller ID for
MID1 Device mid
Punch1
1-65535

Matrix COSEC Web API User Guide 123

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

This specifies the device

type, as set in cosec.

0 =Panel,
1 =Direct Door,
2 =Panel Lite
3 =Direct Door V2,
4 =NGT Direct Door,
5 =Wireless Direct Door
6 =Compact Direct Door
7 =PVR Direct Door
Device Type for Punch1 DTYPE1 2 numeric digits
8 =Panel-lite V2
9 =Vega Controller
11 =Arc Controller
12 =Door V3
15 =Door FMX
16 =Path V2
18 =MODE
19 =Door V4
17 =ARC DC 200
20 =ARGO
21=ARGO FACE

For Panels : 0
1-255 (device-type = 8)
For Direct Doors : 1
Door ID for Punch2 DID2
For Panel Doors : As
0-99 (All Others)
configured

5 numeric digits
Master Controller ID for
MID2 Device mid
Punch2
1-65535

124 Matrix COSEC Web API User Guide

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

This specifies the device

type, as set in cosec.

0 =Panel,
1 =Direct Door,
2 =Panel Lite
3 =Direct Door V2,
4 =NGT Direct Door,
5 =Wireless Direct Door
6 =Compact Direct Door
7 =PVR Direct Door
Device Type for Punch2 DTYPE2 2 numeric digits
8 =Panel-lite V2
9 =Vega Controller
11 =Arc Controller
12 =Door V3
15 =Door FMX
16 =Path V2
18 =MODE
19 =Door V4
17 =ARC DC 200
20 =ARGO
21 =ARGO FACE

For Panels : 0
1-255 (device-type = 8)
For Direct Doors : 1
Door ID for Punch3 DID3
For Panel Doors : As
0-99 (All Others)
configured

5 numeric digits
Master Controller ID for
MID3 Device mid
Punch3
1-65535

Matrix COSEC Web API User Guide 125

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

This specifies the device

type, as set in cosec.

0 =Panel,
1 =Direct Door,
2 =Panel Lite
3 =Direct Door V2,
4 =NGT Direct Door,
5 =Wireless Direct Door
6 =Compact Direct Door
7 =PVR Direct Door
Device Type for Punch3 DTYPE3 2 numeric digits
8 =Panel-lite V2
9 =Vega Controller
11 =Arc Controller
12 =Door V3
15 =Door FMX
16 =Path V2
18 =MODE
19 =Door V4
17 =ARC DC 200
20 =ARGO
21 =ARGO FACE

For Panels : 0
1-255 (device-type = 8)
For Direct Doors : 1
Door ID for Punch4 DID4
For Panel Doors : As
0-99 (All Others)
configured

5 numeric digits
Master Controller ID for
MID4 Device mid
Punch4
1-65535

126 Matrix COSEC Web API User Guide

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

This specifies the device

type, as set in cosec.

0 =Panel,
1 =Direct Door,
2 =Panel Lite
3 =Direct Door V2,
4 =NGT Direct Door,
5 =Wireless Direct Door
6 =Compact Direct Door
7 =PVR Direct Door
Device Type for Punch4 DTYPE4 2 numeric digits
8 =Panel-lite V2
9 =Vega Controller
11 =Arc Controller
12 =Door V3
15 =Door FMX
16 =Path V2
18 =MODE
19 =Door V4
17 =ARC DC 200
20 =ARGO
21 =ARGO FACE

For Panels : 0
1-255 (device-type = 8)
For Direct Doors : 1
Door ID for Punch5 DID5
For Panel Doors : As
0-99 (All Others)
configured

5 numeric digits
Master Controller ID for
MID5 Device mid
Punch5
1-65535

Matrix COSEC Web API User Guide 127

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

This specifies the device

type, as set in cosec.

0 =Panel,
1 =Direct Door,
2 =Panel Lite
3 =Direct Door V2,
4 =NGT Direct Door,
5 =Wireless Direct Door
6 =Compact Direct Door
7 =PVR Direct Door
Device Type for Punch5 DTYPE5 2 numeric digits
8 =Panel-lite V2
9 =Vega Controller
11 =Arc Controller
12 =Door V3
15 =Door FMX
16 =Path V2
18 =MODE
19 =Door V4
17 =ARC DC 200
20 =ARGO
21 =ARGO FACE

For Panels : 0
1-255 (device-type = 8)
For Direct Doors : 1
Door ID for Punch6 DID6
For Panel Doors : As
0-99 (All Others)
configured

5 numeric digits
Master Controller ID for
MID6 Device mid
Punch6
1-65535

128 Matrix COSEC Web API User Guide

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

This specifies the device

type, as set in cosec.

0 =Panel,
1 =Direct Door,
2 =Panel Lite
3 =Direct Door V2,
4 =NGT Direct Door,
5 =Wireless Direct Door
6 =Compact Direct Door
7 =PVR Direct Door
Device Type for Punch6 DTYPE6 2 numeric digits
8 =Panel-lite V2
9 =Vega Controller
11 =Arc Controller
12 =Door V3
15 =Door FMX
16 =Path V2
18 =MODE
19 =Door V4
17 =ARC DC 200
20 =ARGO
21 =ARGO FACE

For Panels : 0
1-255 (device-type = 8)
For Direct Doors : 1
Door ID for Punch7 DID7
For Panel Doors : As
0-99 (All Others)
configured

5 numeric digits
Master Controller ID for
MID7 Device mid
Punch7
1-65535

Matrix COSEC Web API User Guide 129

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

This specifies the device

type, as set in cosec.

0 =Panel,
1 =Direct Door,
2 =Panel Lite
3 =Direct Door V2,
4 =NGT Direct Door,
5 =Wireless Direct Door
6 =Compact Direct Door
7 =PVR Direct Door
Device Type for Punch7 DTYPE7 2 numeric digits
8 =Panel-lite V2
9 =Vega Controller
11 =Arc Controller
12 =Door V3
15 =Door FMX
16 =Path V2
18 =MODE
19 =Door V4
17 =ARC DC 200
20 =ARGO
21 =ARGO FACE

For Panels : 0
1-255 (device-type = 8)
For Direct Doors : 1
Door ID for Punch8 DID8
For Panel Doors : As
0-99 (All Others)
configured

5 numeric digits
Master Controller ID for
MID8 Device mid
Punch8
1-65535

130 Matrix COSEC Web API User Guide

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

This specifies the device

type, as set in cosec.

0 =Panel,
1 =Direct Door,
2 =Panel Lite
3 =Direct Door V2,
4 =NGT Direct Door,
5 =Wireless Direct Door
6 =Compact Direct Door
7 =PVR Direct Door
Device Type for Punch8 DTYPE8 2 numeric digits
8 =Panel-lite V2
9 =Vega Controller
11 =Arc Controller
12 =Door V3
15 =Door FMX
16 =Path V2
18 =MODE
19 =Door V4
17 =ARC DC 200
20 =ARGO
21 =ARGO FACE

For Panels : 0
1-255 (device-type = 8)
For Direct Doors : 1
Door ID for Punch9 DID9
For Panel Doors : As
0-99 (All Others)
configured

5 numeric digits
Master Controller ID for
MID9 Device mid
Punch9
1-65535

Matrix COSEC Web API User Guide 131

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

This specifies the device

type, as set in cosec.

0 =Panel,
1 =Direct Door,
2 =Panel Lite
3 =Direct Door V2,
4 =NGT Direct Door,
5 =Wireless Direct Door
6 =Compact Direct Door
7 =PVR Direct Door
Device Type for Punch9 DTYPE9 2 numeric digits
8 =Panel-lite V2
9 =Vega Controller
11 =Arc Controller
12 =Door V3
15 =Door FMX
16 =Path V2
18 =MODE
19 =Door V4
17 =ARC DC 200
20 =ARGO
21 =ARGO FACE

For Panels : 0
1-255 (device-type = 8)
For Direct Doors : 1
Door ID for Punch10 DID10
For Panel Doors : As
0-99 (All Others)
configured

5 numeric digits
Master Controller ID for
MID10 Device mid
Punch10
1-65535

132 Matrix COSEC Web API User Guide

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

This specifies the device

type, as set in cosec.

0 =Panel,
1 =Direct Door,
2 =Panel Lite
3 =Direct Door V2,
4 =NGT Direct Door,
5 =Wireless Direct Door
6 =Compact Direct Door
7 =PVR Direct Door
Device Type for Punch10 DTYPE10 2 numeric digits
8 =Panel-lite V2
9 =Vega Controller
11 =Arc Controller
12 =Door V3
15 =Door FMX
16 =Path V2
18 =MODE
19 =Door V4
17 =ARC DC 200
20 =ARGO
21 =ARGO FACE

For Panels : 0
1-255 (device-type = 8)
For Direct Doors : 1
Door ID for Punch11 DID11
For Panel Doors : As
0-99 (All Others)
configured

5 numeric digits
Master Controller ID for
MID11 Device mid
Punch11
1-65535

Matrix COSEC Web API User Guide 133

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

This specifies the device

type, as set in cosec.

0 =Panel,
1 =Direct Door,
2 =Panel Lite
3 =Direct Door V2,
4 =NGT Direct Door,
5 =Wireless Direct Door
6 =Compact Direct Door
7 =PVR Direct Door
Device Type for Punch11 DTYPE11 2 numeric digits
8 =Panel-lite V2
9 =Vega Controller
11 =Arc Controller
12 =Door V3
15 =Door FMX
16 =Path V2
18 =MODE
19 =Door V4
17 =ARC DC 200
20 =ARGO
21 =ARGO FACE

For Panels : 0
1-255 (device-type = 8)
For Direct Doors : 1
Door ID for Punch12 DID12
For Panel Doors : As
0-99 (All Others)
configured

5 numeric digits
Master Controller ID for
MID12 Device mid
Punch12
1-65535

134 Matrix COSEC Web API User Guide

Table: Getting Daily Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

This specifies the device

type, as set in cosec.

0 =Panel,
1 =Direct Door,
2 =Panel Lite
3 =Direct Door V2,
4 =NGT Direct Door,
5 =Wireless Direct Door
6 =Compact Direct Door
7 =PVR Direct Door
Device Type for Punch12 DTYPE12 2 numeric digits
8 =Panel-lite V2
9 =Vega Controller
11 =Arc Controller
12 =Door V3
15 =Door FMX
16 =Path V2
18 =MODE
19 =Door V4
17 =ARC DC 200
20 =ARGO
21 =ARGO FACE

Example1
Following are some sample cases for this API:

Sample Request:

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

http://192.168.104.13/cosec/api.svc/v2/attendance-daily?action=get;

Sample Response:

UserID|USER NAME|ProcessDate|Punch1|Punch2|WorkingShift|LateIn|EARLY OUT|Overtime|WorkTime

vegaworker|vegaworker|02/01/2018|01/01/2018 22:23:38||GS||||
<EOT>

Example2

Sample Request:

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

http://192.168.104.11/cosec/api.svc/v2/attendance-daily?action=get;date-range=01102016-
05102016;range=user;Id=1690

Matrix COSEC Web API User Guide 135

Sample Response:

UserID|UserName|Punch1|Punch2|ProcessDate|WorkingShift|LateIn|EarlyOut|Overtime|WorkTime|CustomGroup1_Name|Cust
omGroup2_Name|CustomGroup3_Name
1690|Priyank Bora|||01/10/2016||0|0|0|0|Custom Group 1|Custom Group 2|custom grp 3.2
1690|Priyank Bora|||02/10/2016||0|0|0|0|Custom Group 1|Custom Group 2|custom grp 3.2
1690|Priyank Bora|||03/10/2016||0|0|0|0|Custom Group 1|Custom Group 2|custom grp 3.2
1690|Priyank Bora|||04/10/2016||0|0|0|0|Custom Group 1|Custom Group 2|custom grp 3.2
1690|Priyank Bora|||05/10/2016||0|0|0|0|Custom Group 1|Custom Group 2|custom grp 3.2
<EOT>

Example3

Sample Request:

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

http://matrixserver/api.svc/v2/attendance-daily?action=get;field-name=userid,firsthalf,secondhalf;date-
range=01012013-02012013

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>

136 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

http://<servername>/api.svc/v2/attendance-monthly?action=get;<argument>=<value>...

User Rights

Same as Getting Daily Attendance Data.

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
department
designation Range of users for whom data is to be
section fetched.
range No All
category
grade
custom-group-1
custom-group-2
custom-group-3
user

Matrix COSEC Web API User Guide 137

Table: Getting Monthly Attendance Data - Parameters

Argument Valid Values Mandatory Default Value Description

1 to 999 (for all the

ranges except all &
user)
Each range (except all) shall have
15 alphanumeric chars
specific id.
(for user)
System should allow user to select
A-Z
multiple id, each separated by “,
a-z Yes, if
(coma)” e.g.:”1, 3, 7, 9…”
0-9 mentioned
id - Or
/ _ \\ . @ : ? , - ~ ! $ ` * range is other
Select a range of id
+ than ‘All’.
E.g.”1-50”.
Note: This is the min
Note: - ID is mandatory, if mentioned
to max range. In case
range is other than all.
of a system with only
1-50 id defined then
valid range shall be 1-
50.

0: display name (As

per export template
If “return-field-name” is not mentioned
config)
return-field-name No - the response will be as per existing
1: actual field (As per
system (i.e. 0 = display name)
view column)
2: both

0 : inactive
Active Return users as per their active flag
1: active No 1
status.
2:all

Response Fields

Table: Getting Monthly Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

Allowed Characters
: 15 alphanumeric
Char.
A to Z
User ID USERID 15 characters.
a to z
0 to 9
/ _ \\ . @ : ? , - ~ ! $ `
*+

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

138 Matrix COSEC Web API User Guide

Table: Getting Monthly Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

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 -

Overstay OVERSTAY minutes -

Overstay OVERSTAY_HHMM HH:MM -

Total Overtime OVERTIME minutes -

Total Overtime hrs. OVERTIME HHHHHH: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 HHHHHH:MM -

Manual COFF Credit MANCOFFCR minutes -

Matrix COSEC Web API User Guide 139

Table: Getting Monthly Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

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 HHHHHH:MM
the month

OT for second week

Weekly Overtime component OTW2 minutes
of the month

OT for second week

Weekly Overtime component OTW2 HHHHHH:MM
of the month

OT for third week of

Weekly Overtime component OTW3 minutes
the month

OT for third week of

Weekly Overtime component OTW3 HHHHHH:MM
the month

OT for fourth week

Weekly Overtime component OTW4 minutes
of the month

OT for fourth week

Weekly Overtime component OTW4 HHHHHH: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 HHHHHH: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 -

140 Matrix COSEC Web API User Guide

Table: Getting Monthly Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

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 HHHHHH: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 HHHHHH:MM -

Total OT1 (Actual) TOTAL_OT1 minutes -

Total OT1 (Actual) TOTAL_OT1 HHHHHH:MM -

Total OT2 (Actual) TOTAL_OT2 minutes -

Total OT2 (Actual) TOTAL_OT2 HHHHHH:MM -

Total OT3 (Actual) TOTAL_OT3 minutes -

Total OT3 (Actual) TOTAL_OT3 HHHHHH:MM -

Total OT4 (Actual) TOTAL_OT4 minutes -

Total OT4 (Actual) TOTAL_OT4 HHHHHH:MM -

Total OT5 (Actual) TOTAL_OT5 minutes -

Total OT5 (Actual) TOTAL_OT5 HHHHHH:MM -

Total Authorized OT1 TOTAL_AUTH_OT1 minutes -

Total Authorized OT1 TOTAL_AUTH_OT1 HHHHHH:MM -

Total Authorized OT2 TOTAL_AUTH_OT2 minutes -

Total Authorized OT2 TOTAL_AUTH_OT2 HHHHHH:MM -

Total Authorized OT3 TOTAL_AUTH_OT3 minutes -

Total Authorized OT3 TOTAL_AUTH_OT3 HHHHHH:MM -

Total Authorized OT4 TOTAL_AUTH_OT4 minutes -

Total Authorized OT4 TOTAL_AUTH_OT4 HHHHHH:MM -

Total Authorized OT5 TOTAL_AUTH_OT5 minutes -

Total Authorized OT5 TOTAL_AUTH_OT5 HHHHHH:MM -

Matrix COSEC Web API User Guide 141

Table: Getting Monthly Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

Valid Characters :
A-Z
a-z
Custom Field 1-10 field1-10 upto 30 characters
0-9
space
[]().-_

Availed Short Leave

Short Leave Count short_leave_count 0-9999
Count

Availed Short Leave

Short Leave Hours short_leave_hours HH:MM
Duration

Availed Official
Official Hours official_hours HH:MM
Duration

Maximum Allowed
Max Short Leave Count max_short_leave_count 0-99
Short Leave Count

Maximum Allowed
Max Short Leave Hours max_short_leave_hours HHHH:MM Short Leave
Duration

Availed Late IN
Late In Count late_in_count 0-99
Count

Maximum Allowed
Max Late In Count max_late_in_count 0-99
Late IN Count

Availed Late IN
Late In Duration late_in_duration minutes
Duration

Availed Late IN
Late In Duration late_in_duration_HHMM HHH:MM
Duration HHH:MM

Maximum Allowed
Max Late In Duration max_late_in_duration minutes
Late IN Duration

Maximum Allowed
Max Late In Duration max_late_in_duration_HHMM HHH:MM Late IN Duration
HHH:MM

Availed Early Out

Early Out Count early_out_count 0-99
Count

Maximum Allowed
Max Early Out Count max_early_out_count 0-99
Early Out Count

Availed Early OUT

Early Out Duration early_out_duration minutes
Duration

early_out_duration_HHMM Availed Early OUT

Early Out Duration HHH:MM
Duration HHH:MM

Maximum Allowed
Max Early Out Duration max_early_out_duration minutes
Early OUT Duration

Maximum Allowed
Max Early Out Duration max_early_out_duration_HHMM HHH:MM Early OUT Duration
HHH:MM

Availed Late IN-

Late-IN-Early Out Count late_in_early_out_count 0-99 Early Out Count
(Combined)

Maximum Allowed
Max Late-IN-Early Out Count max_late_in_early_out_count 0-99 Late IN- Early Out
Count (Combined)

142 Matrix COSEC Web API User Guide

Table: Getting Monthly Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

Availed Late IN
Late-IN-Early Out Duration late_in_early_out_duration minutes
Duration HHH:MM

Availed Late IN-

late_in_early_out_duration_
Late-IN-Early Out Duration HHH:MM Early Out Duration
HHMM
HHH:MM

Maximum Allowed
Max Late-IN-Early Out Duration max_late_in_early_out_duration minutes Late IN- Early Out
Duration

Maximum Allowed
max_late_in_early_out_duration_
Max Late-IN-Early Out Duration HHH:MM Late IN- Early Out
HHMM
Duration HHH:MM

Availed Less Work

Less Work Hours Duration less_work_hours_duration minutes
hours Duration

Availed Less Work

less_work_hours_duration_
Less Work Hours Duration HHH:MM hours Duration
HHMM
HHH:MM

Maximum Allowed
Max Less Work Hours Duration max_less_work_hours_duration minutes Less Work Hours
Duration

Maximum Allowed
max_less_work_hours_duration_
Max Less Work Hours Duration HHH:MM Less Work Hours
HHMM
Duration HHH:MM

Custom Group 1 ID CustomGroup1ID 1-999999

Custom Group 2 ID CustomGroup2ID 1-999999

Custom Group 3 ID CustomGroup3ID 1-999999

Allowed Characters

A -Z
a-z
0-9
()
[]
_ (underscore)
- (Hyphen)
. (full Stop)
Full Name full-name max 200 alphanumeric characters
/
&
, (comma)
@
' (single quote)
[Space]

When Multi
Language is On,
Invalid Character set
= Set3

Allowed Chars
Job Allowance Job_Allowance
0-9

Matrix COSEC Web API User Guide 143

Table: Getting Monthly Attendance Data - Response Fields

Field Name Tag Name Valid Values Remarks

Award_Duration Award_Duration Minutes

Award_Duration_HHMM Award_Duration_HHMM HHH:MM

Penalty_Duration Penalty_Duration Minutes

Penalty_Duration_HHMM Penalty_Duration_HHMM HHH:MM

<Leave Type>Days-<Leave <Leave Type>Days-<Leave

0-9 multiples of 0.5
Code> Code>

Defines the total

Availed Hourly Paid
Hourly Paid Leave Hours AVAILEDPLHOURS HH:MM
Leave Hours in that
particular month

Defines the total

Availed Hourly
Hourly Unpaid Leave Hours HULHOURS HH:MM Unpaid Leave Hours
in that particular
month

Example

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

Sample Request:

http:/matrixserver/api.svc/v2/attendance-monthly?action=get;range=organization;id=1

Sample Response:

UserID|UserName|PYear|PMonth|PRDays|ABDays|WorkTime_HHMM|PLDays|TRDays
007|ANAND RATHOD|2015|1|0.0|23.0|000:00|0.0|0.0
1053|JINU SAM|2015|1|19.5|0.5|197:20|2.0|0.0
1054|PARSHV SHAH|2015|1|19.0|1.0|217:27|1.0|0.0
1059|PRATIK PATEL|2015|1|0.0|21.0|000:00|0.0|0.0
1062|MANTHAN PATEL|2015|1|22.0|0.0|199:25|0.0|0.0
1110|Nishit Gandhi|2015|1|20.0|0.0|191:31|2.0|0.0
1256|Arvind|2015|1|0.0|21.0|000:00|0.0|0.0
1309|KAMAL TALUKDAR|2015|1|26.0|0.0|000:00|0.0|0.0
1311|PANKIL GANDA|2015|1|17.5|2.0|160:21|1.5|0.0
<EOT>

144 Matrix COSEC Web API User Guide

Getting Attendance Correction Details

COSEC provides the option for manual correction of attendance data if required. ESS users can apply for
attendance correction in exceptional cases (e.g. a missed OUT punch), and these applications shall require
authorization by either:

a. Any System Account user with rights enabled for attendance correction authorization.
b. Any ESS user with reporting in-charge rights over the applicant.

Based on the status of approval, an Attendance Correction application on COSEC falls in one of the three
categories - Pending, Approved or Rejected.

This API enables the user to fetch the details of all existing attendance correction applications on the COSEC
database as per the specified parameters.

Action

action=get

Syntax

http://<servername>/api.svc/v2/attendance-correction?action=get;<argument>=<value>...

User Rights

User Rights

System Account Enabled.

User must have rights on following pages (COSEC Web Application):

Time and Attendance > Authorization/Approval > Attendance Correction

ESS Enabled.

User must have rights on following ESS pages:

ESS > Time and Attendance > Attendance Correction

Matrix COSEC Web API User Guide 145

Parameters

Table: Getting Attendance Correction Details - Parameters

Argument Valid Values Mandatory Default Value Description

If user-filter=0, a single user’s records

will be returned.

If user-filter=1, records for all the group

members will be returned (applicable
only if the login user is a reporting in-
charge or system account user)
0: individual
user-filter No 0 (individual)
1: group When argument Range & Id or Id is
mentioned and argument user-id is not
provided, default value user-filter=0
should not be considered.

Argument user-filter should only be

applied when argument userid is
provided, else it should be ignored.

For ESS user:

If user-filter=0, the userid should be
login user’s ID or of any user belonging
to the group for which login user is
reporting in-charge.
If user-filter=1, the userid should be
same as login user’s ID. The login user
must be a reporting in-charge.
15 alphanumeric
Char. (for user) For a System Account user:
A to Z If user-filter=0, the userid can be any
userid a to z Yes - user’s id. (If the System Account user
0 to 9 has rights on that user)
/_\\.@: If user-filter=1, the userid can be any
user’s ID (If the System Account user
has rights on that user and the user is a
reporting in-charge).

In case userid & user-filter are provided

along with id/id & range, priority should
always be given to userid & user-filter.
Value of id/id & range to be ignored in
that case.

The actual process date to be

date-range ddmmyyyy-ddmmyyyy No Current date
considered for fetching records.

0: All
1: Pending The status of Attendance Correction
status No 0 (All)
2: Approved application
3: Rejected

All In this argument only single value

Organization should be allowed.
Branch
Department If argument range's value is specified
Designation as "All", ids of all the users that login
Section User (If argument user has rights over will return.
Range No
Category Range is not specified)
Grade In case user-id /user-id & user-filter are
User provided along with id/id & range,
Custom-group-1 priority should always be given to user-
Custom-group-2 id / user-id & user-filter. Value of id/id &
custom-group-3 range to be ignored in that case.

146 Matrix COSEC Web API User Guide

Table: Getting Attendance Correction Details - Parameters

Argument Valid Values Mandatory Default Value Description

If argument range is not mentioned and

individual argument ID is specified,
1 to 999999 (for all the then User id should be considered.
ranges except all &
user) Argument ID can have multiple ids as
Max 15 alphanumeric value with comma separated.
ID characters (for user) No - For example Id=1,2,…..999.
A to Z
a to z In case user-id /user-id & user-filter are
0 to 9 provided along with id/id & range,
/_\\.@: priority should always be given to user-
id / user-id & user-filter. Value of id/id &
range to be ignored in that case.

Response Fields

Table: Getting Attendance Correction Details - Response Fields

Field Name Tag Name Valid Values Remarks

Application ID application-id numeric -

Applied Date applied-date mm/dd/yyyy HH:MM -

Allowed characters: 15
alphanumeric char
A-Z
User ID user-id 15 characters
a-z
0-9
/ _ \\ . @ : ? , - ~ ! $ ` * +

Allowed characters:
A-Z
User Name user-name 40 characters a-z
0-9
-_.()[]

Max. 15 alphanumeric
Short Name short-name -
characters

Attendance Date date mm/dd/yyyy -

Verdict Date verdict-date mm/dd/yyyy HH:MM -

1: pending
Application Status status 2: approved -
3: rejected

Matrix COSEC Web API User Guide 147

Table: Getting Attendance Correction Details - Response Fields

Field Name Tag Name Valid Values Remarks

Previous Punch 1 previous-punch1

Previous Punch 2 previous-punch2 These are the punch

values, before application
Previous Punch 3 previous-punch3 was submitted.
When application is in
Previous Punch 4 previous-punch4
pending state :
Previous Punch 5 previous-punch5 Previous values are
same as the values
Previous Punch 6 previous-punch6 available in daily
mm/dd/yyyy HH:MM attendance template
Previous Punch 7 previous-punch7 response.

Previous Punch 8 previous-punch8 Once an application is

approved, the previous
Previous Punch 9 previous-punch9
values should contain the
Previous Punch 10 previous-punch10 punch values that were
there before application
Previous Punch 11 previous-punch11 was submitted.

Previous Punch 12 previous-punch12

Previous Shift Code previous-shift 2 characters code -

Previous Week-Off Status previous-wo-status 0 or 1 -

Previous PH Status previous-ph-status 0 or 1 -

Changed Punch 1 changed-punch1

Changed Punch 2 changed-punch2

Changed Punch 3 changed-punch3 For a new application

being submitted or for an
Changed Punch 4 changed-punch4
application in pending
Changed Punch 5 changed-punch5 state, these are the
applied values (values
Changed Punch 6 changed-punch6 manually entered by the
mm/dd/yyyy HH:MM user).
Changed Punch 7 changed-punch7 Once an application gets
approved, the changed
Changed Punch 8 changed-punch8 values and actual values
(as available in daily
Changed Punch 9 changed-punch9
attendance template)
Changed Punch 10 changed-punch10 become the same.

Changed Punch 11 changed-punch11

Changed Punch 12 changed-punch12

Changed Shift Code changed-shift 2 character code -

Changed WO Status changed-wo-status 0 or 1 -

Changed PH Status changed-ph-status 0 or 1 -

“0” implies that there is

no associated punch with
Break Start.

Break Start (Associated Values “1-N” imply which

previous-break-start-punch 0, 1 - N
Punch) punch is stored as Break
Start.
E.g. “2” implies that
Punch 2 is stored as
Break Start.

148 Matrix COSEC Web API User Guide

Table: Getting Attendance Correction Details - Response Fields

Field Name Tag Name Valid Values Remarks

Punch time for break

start. If a Punch was
Break Start Time previous-break-start-time mm/dd/yyyy HH:MM overwritten by
subsequent punches, this
will be the event time.

Break Start Special

Break Start SPF previous-break-start-spfid blank or 8
Function ID.

“0” implies that there is

no associated punch with
Break End.

0, Values “1-N” imply which

Break End (Associated Punch) previous-break-end-punch
1-N punch is stored as Break
End.
E.g. “2” implies that
Punch 2 is stored as
Break End.

Punch time for break end.

If a Punch was
Break End Time previous-break-end-time mm/dd/yyyy HH:MM overwritten by
subsequent punches, this
will be the event time.

Break End Special

Break End SPF previous-break-end-spfid blank or 7
Function ID

“0” implies that there is

no associated punch with
Break Start.

Break Start (Associated 0, Values “1-N” imply which

changed-break-start-punch
Punch) 1-N punch is stored as Break
Start.
E.g. “2” implies that
Punch 2 is stored as
Break Start.

Punch time for break

start. If a Punch was
Break Start Time changed-break-start-time mm/dd/yyyy HH:MM overwritten by
subsequent punches, this
will be the event time.

Break Start SPF changed-break-start-spfid blank or 8 -

“0” implies that there is

no associated punch with
Break End.

0, Values “1-N” imply which

Break End (Associated Punch) changed-break-end-punch
1-N punch is stored as Break
End.
E.g. “2” implies that
Punch 2 is stored as
Break End.

Punch time for break end.

If a Punch was
Break End Time changed-break-end-time mm/dd/yyyy HH:MM overwritten by
subsequent punches, this
will be the event time.

Break End SPF changed -break-end-spfid blank or 7 -

Matrix COSEC Web API User Guide 149

Table: Getting Attendance Correction Details - Response Fields

Field Name Tag Name Valid Values Remarks

Allowed Characters
A-Z Reason for applying an
a-z Attendance Correction
Reason reason
0-9 Application as an ESS
! @ $ & ( ) _ -+ [ ] / : . , $ & User
<Space>

Max 15 chars

Allowed Characters
Final RIC ID final-ric A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Final RIC Name final-ric-name a-z
0-9
-_. ()[]

1: pending
Provides status of
Final RIC Verdict final-ric-verdict 2: approved
application.
3: rejected

Max 30 chars
Allowed Characters
A-Z
Final RIC Remark final-ric-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC ID nonfinal-ric A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC Name nonfinal-ric-name
a-z
0-9
-_. ()[]

Non-Final RIC Verdict Date MM/DD/YYYY

nonfinal-ric-verdict-date
Time HH:MM

1: pending
Non-Final RIC Verdict nonfinal-ric -verdict 2: approved
3: rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC Remark nonfinal-ric-remark
a-z
0-9
_.,()[]:@!#$*+/\

150 Matrix COSEC Web API User Guide

Table: Getting Attendance Correction Details - Response Fields

Field Name Tag Name Valid Values Remarks

Max 15 chars

Allowed Characters
Non-Final RIC2 ID nonfinal-ric2 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC2 Name nonfinal-ric2-name
a-z
0-9
-_. ()[]

Non-Final RIC2 Verdict Date MM/DD/YYYY

nonfinal-ric2-verdict-date
Time HH:MM

1: pending
Non-Final RIC2 Verdict nonfinal-ric2-verdict 2: approved
3: rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC2 Remark nonfinal-ric2-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC3 ID nonfinal-ric3 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC3 Name nonfinal-ric3-name
a-z
0-9
-_. ()[]

Non-Final RIC3 Verdict Date MM/DD/YYYY

nonfinal-ric3-verdict-date
Time HH:MM

1: pending
Non-Final RIC3 Verdict nonfinal-ric3-verdict 2: approved
3: rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC3 Remark nonfinal-ric3-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC4 ID nonfinal-ric4 A-Z
a-z
0-9
@_ / : .

Matrix COSEC Web API User Guide 151

Table: Getting Attendance Correction Details - Response Fields

Field Name Tag Name Valid Values Remarks

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC4 Name nonfinal-ric4-name
a-z
0-9
-_. ()[]

Non-Final RIC4 Verdict Date MM/DD/YYYY

nonfinal-ric4-verdict-date
Time HH:MM

1: pending
Non-Final RIC4 Verdict nonfinal-ric4 -verdict 2: approved
3: rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC4 Remark nonfinal-ric4-remark
a-z
0-9
_.,()[]:@!#$*+/\

152 Matrix COSEC Web API User Guide

Applying for Attendance Correction

Use this to submit a new attendance correction request.

Action

action=set

Syntax

http://<servername>/api.svc/v2/attendance-correction?action=set;<argument>=<value>...

User Rights

Same as Getting Attendance Correction Details.

Parameters

Table: Applying for Attendance Correction - Parameters

Argument Valid Values Mandatory Default Value Description

15 alphanumeric
Char. (for user)
A to Z
Login User must have necessary rights
userid a to z Yes -
on this user.
0 to 9
/ _ \\ . @ : ? , - ~ ! $ ` *
+

The date for which application is being

submitted.
process-date ddmmyyyy Yes -
Note: Process Date should not be
greater than current date.

punch1-datetime

punch2-datetime

punch3-datetime

punch4-datetime
HHMM implies that time should be in
punch5-datetime 24-hours format only.
punch6-datetime
Note: Punch Date mentioned in the
ddmmyyyyHHMM No -
punch7-datetime request can be 1 date prior to Process
Date or 2 subsequent dates from the
punch8-datetime process date. Punch date outside this
range will not be allowed.
punch9-datetime

punch10-datetime

punch11-datetime

punch12-datetime

shift two characters Yes - This will contain the configured shift ID.

Matrix COSEC Web API User Guide 153

Table: Applying for Attendance Correction - Parameters

Argument Valid Values Mandatory Default Value Description

This is the Week Off status.

If ‘ph’ is
mentioned,
wo 0, 1 - If wo=1, day status is WO. If both wo=1
then ‘wo’ is
and ph=1 day status is WO
mandatory.

If ‘wo’ is
If ph=1, day status is PH. If both wo=1
mentioned,
ph 0, 1 - and ph=1 day status is WO
then ‘ph’ is
mandatory.

“0” implies that there is no associated

punch with Break Start.
“99” means that a new punch is being
0 : Edit added as Break Start Punch.
break-start-punch 99 : Add No - A value “1-N” implies the value of the
1 – N : Existing existing punch for Break Start.

E.g. If the value is “2”, this implies that

Punch 2 is stored as Break Start.

Punch time for break start. If a Punch

break-start-time ddmmyyyyHHMM No - was overwritten by subsequent
punches, this will be the event time.

“0” implies that there is no associated

punch with Break End.
“99” means that a new punch is being
0 : Edit
added as Break End Punch
break-end-punch 99 : Add No -
A value “1-N” implies the value of the
1 – N : Existing
existing punch for Break Start.
E.g. If the value is “2”, this implies that
Punch 2 is stored as Break Start.

Punch time for break end. If a Punch

was overwritten by subsequent
break-end-time ddmmyyyyHHMM No -
punches, this will be the event time.

Max 50 chars.
Allowed Characters
A-Z
a-z
reason No Personal
0-9
! @ # $ & ( ) _ -+ [ ] / \ :
. , * <Space>

Punch Date mentioned in the request can be 1 date prior to Process Date or 2 subsequent dates from the
process date.

Example

To submit an attendance correction request for the 2nd punch:

Sample Request:

http://matrixserver/api.svc/v2/attendance-correction?action=set;userid=92;process-date=07032014;punch2-
datetime=070320142146;shift=GS

154 Matrix COSEC Web API User Guide

Sample Response:

success: <response code> : saved successfully

Matrix COSEC Web API User Guide 155

Deleting Attendance Correction Applications

This enables the user to delete existing Attendance Correction Applications from the COSEC database by
specifying the Application ID.

Action

action=delete

Syntax

http://<servername>/api.svc/v2/attendance-correction?action=set;<argument>=<value>...

User Rights

Same as Getting Attendance Correction Details.

Parameters

Table: Deleting Attendance Correction Applications - Parameters

Argument Valid Values Mandatory Default Value Description

application-id numeric Yes - This is the identification number for

the attendance correction
application.

156 Matrix COSEC Web API User Guide

Approving Attendance Correction

This shall be used to approve/reject attendance correction applications submitted to a particular user.

Action

action=set

Syntax

http://<servername>/api.svc/v2/attendance-correction-approval?action=set;<argument>=<value>…

User Rights

User Rights

System Account Enabled.

User must have rights on following pages (COSEC Web Application):

Time and Attendance > Authorization/Approval > Attendance Correction

Enabled if User is a reporting group in-charge and has permissions on page: Attendance
ESS
Correction

Parameters

Table: Approving Attendance Correction - Parameters

Argument Valid Values Mandatory Default Value Description

application-id numeric Yes - This is the identification number for

the attendance correction
application. The login user must
have rights on the user ID
associated with this Application ID.

userid 15 characters Yes - This is the identification number for

the user whose attendance
correction is to be approved.

verdict 0: reject Yes - This is the approval verdict to be

1: approve applied to an application. A verdict
can be passed only for applications
that are pending for approval.

remark Max 50 chars No - If Remark not given, default remark

Allowed will appear based on verdict.
Characters
A-Z
a-z
0-9
<Space>

Matrix COSEC Web API User Guide 157

 Any change in Punch timings can cause a change in Break Hours, Work Hours and User’s Absent/Present
status.

If you select Anyone as Authorization Mode, the Reporting Group In-charges will be able to view and
approve the application. Whichever request come first, will be considered and used to mark the verdict on
the application.

158 Matrix COSEC Web API User Guide

Getting Short Leave/Official IN-OUT Entries

This API can be used to fetch details of all Short Leave/Official IN-OUT Entries submitted on the COSEC system.

Action

action=get

Syntax

http://<servername>/api.svc/v2/short-leave-entry?action=get;<argument>=<value>...

User Rights

User Rights

Enabled.

System Account User must have rights on following pages (COSEC Web Application):

Time Attendance > Authorization/Approval > Short Leave/ Official IN-OUT

Enabled.

User must have rights on following ESS pages:

ESS
ESS > Approval/Authorization > Short Leave/Official IN-OUT Authorization

ESS > Time Attendance > Short Leave/Official IN-OUT

Parameter

Table: Getting Short Leave/Official IN-OUT Entries - Parameters

Argument Valid Values Mandatory Default Value Description

If user-filter=0, a single user’s records

will be returned.

If user-filter=1, records for all the group

members will be returned (applicable
only if login user is a reporting in-
charge or system account user)
0: individual
user-filter No 0 (individual)
1: group When argument Range & Id or Id is
mentioned and argument user-id is not
provided, default value of user-filter=0
should not be considered.

Argument user-filter should only be

applied when argument user-id is
provided, else it should be ignored.

Matrix COSEC Web API User Guide 159

Table: Getting Short Leave/Official IN-OUT Entries - Parameters

Argument Valid Values Mandatory Default Value Description

This is the identification number for the

user whose data is to be fetched.

For ESS user:

If user-filter=0, the userid should be
login user’s ID or of any user belonging
to the group for which login user is
reporting in-charge.
If user-filter=1, the userid should be
same as login user’s ID. The login user
15 alphanumeric
must be a reporting in-charge.
Char. (for user)
A to Z
For a System Account user:
userid a to z Yes -
If user-filter=0, the userid can be any
0 to 9
user’s id. (If the System Account user
/_\\.@:
has rights on that user)
If user-filter=1, the userid can be any
user’s ID (If the System Account user
has rights on that user and the user is a
reporting in-charge).

In case userid & user-filter are provided

along with id/id & range, priority should
always be given to userid & user-filter.
Value of id/id & range to be ignored in
that case.

Records for 30 days

prior to current date Date range for which short-leave/official
date-range ddmmyyyy-ddmmyyyy No
will be fetched if no in-out applications need to be fetched.
range is specified.

If entry-type = 2,
Only those records will be returned for
which special function is of type: short-
leave in/short-leave out.
1: Official
entry-type No 2 (Short Leave)
2: Short Leave
If entry-type = 1,
Only those records will be returned for
which special function is of type: official
in/official out.

0: All Applicable in case of short leave/official

1: Pending in-out authorization by Reporting in-
authorization-status No 0 (All)
2: Approved charge, where member’s entries need
3: Rejected to be fetched.

All In this argument only single value

Organization should be allowed.
Branch
Department If argument range's value is specified
Designation as "All", ids of all the users that login
Section User (If argument user has rights over will return
Range No
Category Range is not specified)
Grade In case user-id /user-id & user-filter are
User provided along with id/id & range,
Custom-group-1 priority should always be given to user-
Custom-group-2 id / user-id & user-filter. Value of id/id &
custom-group-3 range to be ignored in that case.

160 Matrix COSEC Web API User Guide

Table: Getting Short Leave/Official IN-OUT Entries - Parameters

Argument Valid Values Mandatory Default Value Description

If argument range is not mentioned and

individual argument ID has specified,
1 to 999999 (for all the then User id should be considered.
ranges except all &
user) Argument ID can have multiple ids as
Max 15 alphanumeric value with comma separated.
ID characters (for user) No - For example Id=1,2,…..999
A to Z
a to z In case user-id /user-id & user-filter are
0 to 9 provided along with id/id & range,
/_\\.@: priority should always be given to user-
id / user-id & user-filter. Value of id/id &
range to be ignored in that case.

Response Fields

Table: Getting Short Leave/Official IN-OUT Entries - Response Fields

Field Name Tag Name Valid Values Remarks

Allowed Characters : 15
alphanumeric Char.
A to Z
User ID user-id 15 characters
a to z
0 to 9
/ _ \\ . @ : ? , - ~ ! $ ` * +

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

Max. 15 alphanumeric
Short Name short-name -
characters

1: Official
Entry Type entry-type -
2: Short Leave

Attendance Date attendance-date mm/dd/yyyy -

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

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

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

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

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

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

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

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

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

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

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

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

Matrix COSEC Web API User Guide 161

Table: Getting Short Leave/Official IN-OUT Entries - Response Fields

Field Name Tag Name Valid Values Remarks

Special Function 1 spfid1

Special Function 2 spfid2

Special Function 3 spfid3

Special Function 4 spfid4 1=Official In,

2=Official Out,
Special Function 5 spfid5 3=ShortLeave In,
4=ShortLeave Out,
Special Function 6 spfid6 5=Regular In,
1-10
6=Regular Out,
Special Function 7 spfid7
7=Lunch In,
Special Function 8 spfid8 8=Lunch Out,
9=Overtime In,
Special Function 9 spfid9 10=Overtime Out

Special Function 10 spfid10

Special Function 11 spfid11

Special Function 12 spfid12

In/Out Reason for Punch 1 punch-reason1 30 alphanumeric characters

In/Out Reason for Punch 2 punch-reason2

In/Out Reason for Punch 3 punch-reason3

In/Out Reason for Punch 4 punch-reason4

In/Out Reason for Punch 5 punch-reason5

In/Out Reason for Punch 6 punch-reason6 From V10R2, manual

entered reasons will also
In/Out Reason for Punch 7 punch-reason7 30 alphanumeric characters be considered.

In/Out Reason for Punch 8 punch-reason8

In/Out Reason for Punch 9 punch-reason9

In/Out Reason for Punch 10 punch-reason10

In/Out Reason for Punch 11 punch-reason11

In/Out Reason for Punch 12 punch-reason12

Shift shift Two character code -

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
<Leave Codes>as
PH : Public Holiday
Second Half secondhalf configured in COSEC
FB : Field Break
RD : Rest Day
IN : Official In
<Leave Codes>

0: Status is not WO
Week-Off wo -
1: Status is WO

162 Matrix COSEC Web API User Guide

Table: Getting Short Leave/Official IN-OUT Entries - Response Fields

Field Name Tag Name Valid Values Remarks

0: Status is not PH
Public Holiday ph -
1: Status is PH

Gross Work Hours gross-workhours HH:MM Gross Work Hours

Extra Work Hours extra-workhours HH:MM Extra Work Hours

Net Work Hours net-workhours HHHHHH:MM Net Work Hours

Applicable in case of
short leave/official in-out
1 : Pending
authorization by a
Authorization Status authorization-status 2 : Approved
Reporting in-charge,
3 : Rejected
where member’s entries
need to be fetched.

DD/MM/YYYY
Applied On application-date
HH:MM

Max 15 chars

Allowed Characters
Final RIC ID final-ric A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Final RIC Name final-ric-name
a-z
0-9
-_. ()[]

MM/DD/YYYY
Final RIC Verdict Date Time final-ric-verdict-date
HH:MM

1: pending
Provides status of
Final RIC Verdict final-ric-verdict 2: approved
application.
3: rejected

Max 30 chars
Allowed Characters
A-Z
Final RIC Remark final-ric-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC ID nonfinal-ric A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC Name nonfinal-ric-name
a-z
0-9
-_. ()[]

Non-Final RIC Verdict Date MM/DD/YYYY

nonfinal-ric-verdict-date
Time HH:MM

Matrix COSEC Web API User Guide 163

Table: Getting Short Leave/Official IN-OUT Entries - Response Fields

Field Name Tag Name Valid Values Remarks

1: pending
Non-Final RIC Verdict nonfinal-ric -verdict 2: approved
3: rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC Remark nonfinal-ric-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC2 ID nonfinal-ric2 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC2 Name nonfinal-ric2-name
a-z
0-9
-_. ()[]

Non-Final RIC2 Verdict Date MM/DD/YYYY

nonfinal-ric2-verdict-date
Time HH:MM

1: pending
Non-Final RIC2 Verdict nonfinal -ric2-verdict 2: approved
3: rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC2 Remark nonfinal-ric2-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC3 ID nonfinal-ric3 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC3 Name nonfinal-ric3-name
a-z
0-9
-_. ()[]

Non-Final RIC3 Verdict Date MM/DD/YYYY

nonfinal-ric3-verdict-date
Time HH:MM

1: pending
Non-Final RIC3 Verdict nonfinal-ric3-verdict 2: approved
3: rejected

164 Matrix COSEC Web API User Guide

Table: Getting Short Leave/Official IN-OUT Entries - Response Fields

Field Name Tag Name Valid Values Remarks

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC3 Remark nonfinal-ric3-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC4 ID nonfinal-ric4 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC4 Name nonfinal-ric4-name
a-z
0-9
-_. ()[]

Non-Final RIC4 Verdict Date MM/DD/YYYY

nonfinal -ric4-verdict-date
Time HH:MM

1: pending
Non-Final RIC4 Verdict nonfinal-ric4-verdict 2: approved
3: rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC4 Remark nonfinal-ric4-remark
a-z
0-9
_.,()[]:@!#$*+/\

Matrix COSEC Web API User Guide 165

Making Short Leave/Official IN-OUT Entries

This can be used to submit Short Leave/Official In-Out Entries to Reporting In-charge for authorization.

Action

action=set

Syntax

http://<servername>/api.svc/v2/short-leave-entry?action=<set>;<argument>=<value>.. .

User Rights

Same as Getting Short Leave/Official IN-OUT Entries.

Parameters

Table: Making Short Leave/Official IN-OUT Entries - Parameters

Argument Valid Values Mandatory Default Value Description

15 alphanumeric char.
(for user)
A to Z
The login user must have appropriate
userid a to z Yes -
rights on this User ID.
0 to 9
/ _ \\ . @ : ? , - ~ ! $ ` *
+

Date for which the entry application

needs to be submitted.
attendance-date ddmmyyyy Yes -
f user has already submitted an entry
for this date, the previous entry will be
over-written.

spfid1

spfid2

spfid3

spfid4

spfid5
Entry markings for punches 1 to 12.
spfid6 0: No Special function
Entry for a punch will be submitted
1: Official No N/A
successfully only if the punch is
spfid7 2: Short Leave
available.
spfid8

spfid9

spfid10

spfid11

spfid12

166 Matrix COSEC Web API User Guide

Table: Making Short Leave/Official IN-OUT Entries - Parameters

Argument Valid Values Mandatory Default Value Description

0: reason-1 0: Reason should be entered manually

1-99: In/Out Reason No N/A by user in reason-1 field.
reason-id1
IDs 1-99: In/Out reason-id as selected by
the User.

0-9, a-z,A- No N/A

reason-1 Reason to be entered by the user.
Z,[space],[,],(,),-,_,

0: Reason should be entered manually

0: reason-2
No N/A by user in reason-2 field.
reason-id2 1-99: In/Out Reason
1-99: In/Out reason-id as selected by
IDs
the User.

0-9, a-z,A- No N/A

reason-2 Reason to be entered by the user.
Z,[space],[,],(,),-,_,

0: Reason should be entered manually

0: reason-3
No N/A by user in reason-3 field.
reason-id3 1-99: In/Out Reason
1-99: In/Out reason-id as selected by
IDs
the User.

0-9, a-z,A- No N/A

reason-3 Reason to be entered by the user.
Z,[space],[,],(,),-,_,

0: Reason should be entered manually

0: reason-4
No N/A by user in reason-4 field.
reason-id4 1-99: In/Out Reason
1-99: In/Out reason-id as selected by
IDs
the User.

0-9, a-z,A- No N/A

reason-4 Reason to be entered by the user.
Z,[space],[,],(,),-,_,

0: Reason should be entered manually

0: reason-5
No N/A by user in reason-5 field.
reason-id5 1-99: In/Out Reason
1-99: In/Out reason-id as selected by
IDs
the User.

0-9, a-z,A- No N/A

reason-5 Reason to be entered by the user.
Z,[space],[,],(,),-,_,

0: Reason should be entered manually

0: reason-6
No N/A by user in reason-6 field.
reason-id6 1-99: In/Out Reason
1-99: In/Out reason-id as selected by
IDs
the User.

0-9, a-z,A- No N/A

reason-6 Reason to be entered by the user.
Z,[space],[,],(,),-,_,

0: Reason should be entered manually

0: reason-7
No N/A by user in reason-7 field.
reason-id7 1-99: In/Out Reason
1-99: In/Out reason-id as selected by
IDs
the User.

0-9, a-z,A- No N/A

reason-7 Reason to be entered by the user.
Z,[space],[,],(,),-,_,

0: Reason should be entered manually

0: reason-8
No N/A by user in reason-8 field.
reason-id8 1-99: In/Out Reason
1-99: In/Out reason-id as selected by
IDs
the User.

0-9, a-z,A- No N/A

reason-8 Reason to be entered by the user.
Z,[space],[,],(,),-,_,

0: Reason should be entered manually

0: reason-9
No N/A by user in reason-9 field.
reason-id9 1-99: In/Out Reason
1-99: In/Out reason-id as selected by
IDs
the User.

Matrix COSEC Web API User Guide 167

Table: Making Short Leave/Official IN-OUT Entries - Parameters

Argument Valid Values Mandatory Default Value Description

0-9, a-z,A- No N/A

reason-9 Reason to be entered by the user.
Z,[space],[,],(,),-,_,

0: Reason should be entered manually

0: reason-10
No N/A by user in reason-10 field.
reason-id10 1-99: In/Out Reason
1-99: In/Out reason-id as selected by
IDs
the User.

0-9, a-z,A- No N/A

reason-10 Reason to be entered by the user.
Z,[space],[,],(,),-,_,

0: Reason should be entered manually

0: reason-11
No N/A by user in reason-11 field.
reason-id11 1-99: In/Out Reason
1-99: In/Out reason-id as selected by
IDs
the User.

0-9, a-z,A- No N/A

reason-11 Reason to be entered by the user.
Z,[space],[,],(,),-,_,

0: Reason should be entered manually

0: reason-12
No N/A by user in reason-12 field.
reason-id12 1-99: In/Out Reason
1-99: In/Out reason-id as selected by
IDs
the User.

0-9, a-z,A- No N/A

reason-12 Reason to be entered by the user.
Z,[space],[,],(,),-,_,

The entry application will submit only the special function value: short-leave or official.
In or Out will depend on the punch-system (2-Punch / 4-Punch / N-Punch etc.) applicable to the user and
shall be determined on the server side.

Possible values are:

•1 : Official In
•2 : Official Out
•3 : Short-Leave In
•4 : Short-Leave Out

168 Matrix COSEC Web API User Guide

Short Leave/Official In-Out Authorization

This API can be used to approve or reject all Short-Leave/Official IN-OUT applications submitted to the Reporting
In-charge.

Action

action=set

Syntax

http://<servername>/api.svc/v2/short-leave-authorization?action=set;<argument>=<value>…

User Rights

User Rights

Enabled.

System Account User must have rights on following pages (COSEC Web Application):

Time Attendance > Authorization/Approval > Short Leave/ Official IN-OUT

Enabled.

ESS User must be a reporting in-charge with rights on the following ESS pages:

ESS > Approval/Authorization> Short Leave/Official IN-OUT Authorization

Parameters

Table: Short Leave/Official In-Out Authorization - Parameters

Argument Valid Values Mandatory Default Value Description

This is the identification number for the

user whose entries are to be
authorized.
For ESS user, It can be the logged in
Userid 15 characters Yes - user’s ID. Or the ID of users assigned
under his reporting group.

For System Account user, it can be

user ID of any user he has rights on.

This is the attendance date for which

Attendance-date ddmmyyyy Yes -
the authorization is to be performed.

1: Official This is the type of entry for which

authorization-for Yes -
2: Short Leave authorization is to be performed.

This is the approval verdict to be

1: approve
applied to an application. A verdict can
verdict 2: reject Yes -
be passed only for applications that are
pending for approval.

Matrix COSEC Web API User Guide 169

Table: Short Leave/Official In-Out Authorization - Parameters

Argument Valid Values Mandatory Default Value Description

Max 50 chars
Allowed Characters
A-Z
remark No -
a-z
0-9
<Space>

170 Matrix COSEC Web API User Guide

Getting Attendance Records for Authorization

This can be used to fetch the attendance records of a single user or multiple users based on a specified date range
and the specified authorization status (i.e. pending or authorized). These records can then be authorized by the
respective supervisors.

Action

action=get

Syntax

http://<servername>/api.svc/v2/attendance-authorization?action=get;<argument>=<value>…

User Rights

User Rights

Enabled.

System Account User must have rights on following pages (COSEC Web Application):

Time Attendance > Authorization/Approval > Daily Attendance

Enabled.

ESS User must be a reporting in-charge with rights on the following ESS pages:

ESS > Approval/Authorization > Attendance Authorization

Parameters

Table: Getting Attendance Records for Authorization - Parameters

Argument Valid Values Mandatory Default Value Description

If user-filter=0, a single user’s records

will be returned.

If user-filter=1, records for all the group

members will be returned (applicable
only if login user is a reporting in-
charge or system account user).
0: individual
User-filter No 0 (individual)
1: group When argument Range & Id or Id is
mentioned and argument user-id is not
provided default value user-filter=0
should not be considered

Argument user-filter should only be

applied when argument user-id is
provided, else it should be ignored.

Matrix COSEC Web API User Guide 171

Table: Getting Attendance Records for Authorization - Parameters

Argument Valid Values Mandatory Default Value Description

This is the identification number for the

user whose data is to be fetched.

For ESS user:

If user-filter=0, the userid should be
login user’s ID or of any user belonging
to the group for which login user is
reporting in-charge.
If user-filter=1, the userid should be
same as login user’s ID. The login user
15 alphanumeric
must be a reporting in-charge.
Char. (for user)
A to Z
For a System Account user:
Userid a to z Yes -
If user-filter=0, the userid can be any
0 to 9
user’s id. (If the System Account user
/_\\.@:
has rights on that user)
If user-filter=1, the userid can be any
user’s ID (If the System Account user
has rights on that user and the user is a
reporting in-charge).

In case userid & user-filter are provided

along with id/id & range, priority should
always be given to userid & user-filter.
Value of id/id & range to be ignored in
that case.

Records for past 30

days up to the current Date range for which records need to
date-range ddmmyyyy-ddmmyyyy No
date will be fetched if be fetched.
no range is specified.

0: Pending Fetch attendance records based on

authorization-status No 0 (Pending)
1: Authorized their authorization status.

All In this argument only single value

Organization should be allowed.
Branch
Department If argument range's value is specified
Designation as "All", ids of all the users that login
Section User (If argument user has rights over will return.
Range No
Category Range is not specified)
Grade In case user-id /user-id & user-filter are
User provided along with id/id & range,
Custom-group-1 priority should always be given to user-
Custom-group-2 id / user-id & user-filter. Value of id/id &
custom-group-3 range to be ignored in that case.

If argument range is not mentioned and

individual argument ID has specified,
1 to 999999 (for all the then User id should be considered.
ranges except all &
user) Argument ID can have multiple ids as
Max 15 alphanumeric value with comma separated.
ID characters (for user) No - For example Id=1,2,…..999.
A to Z
a to z In case user-id /user-id & user-filter are
0 to 9 provided along with id/id & range,
/_\\.@: priority should always be given to user-
id / user-id & user-filter. Value of id/id &
range to be ignored in that case.

172 Matrix COSEC Web API User Guide

Response Fields

Table: Getting Attendance Records for Authorization - Response Fields

Field Name Tag Name Valid Values Remarks

Allowed Characters : 15
alphanumeric Char.
A to Z
User ID user-id 15 characters
a to z
0 to 9
/ _ \\ . @ : ? , - ~ ! $ ` * +

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

Max. 15 alphanumeric
Short Name short-name -
characters

Attendance Date attendance-date mm/dd/yyyy -

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

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

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

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

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

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

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

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

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

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

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

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

Special Function 1 spfid1

Special Function 2 spfid2

Special Function 3 spfid3

Special Function 4 spfid4 1=Official In,

2=Official Out,
Special Function 5 spfid5 3=ShortLeave In,
4=ShortLeave Out,
Special Function 6 spfid6
5=Regular In,
1-10
6=Regular Out,
Special Function 7 spfid7
7=Lunch In,
Special Function 8 spfid8 8=Lunch Out,
9=Overtime In,
Special Function 9 spfid9 10=Overtime Out

Special Function 10 spfid10

Special Function 11 spfid11

Special Function 12 spfid12

Matrix COSEC Web API User Guide 173

Table: Getting Attendance Records for Authorization - Response Fields

Field Name Tag Name Valid Values Remarks

Shift shift Two character code -

Total Overtime total-overtime HHHHHH:MM -

Gross Work Hours gross-workhours HH:MM Gross Work Hours

Extra Work Hours extra-workhours HH:MM Extra Work Hours

Net Work Hours net-workhours HHHHHH:MM Net Work Hours

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
<Leave Codes>as
PH : Public Holiday
Second Half secondhalf configured in COSEC
FB : Field Break
RD : Rest Day
IN : Official In
<Leave Codes>

0: Status is not WO
Week-Off wo -
1: Status is WO

0: Status is not PH
Public Holiday ph -
1: Status is PH

1 : Pending Authorization
Authorization Status authorized 2 : Authorized -

“0” implies that there is

no associated punch with
Break Start.

Break Start (Associated Values “1-N” imply which

break-start-punch 0, 1 - N
Punch) punch is stored as Break
Start.
E.g. “2” implies that
Punch 2 is stored as
Break Start.

Punch time for break

start. If a Punch was
Break Start Time break-start-time mm/dd/yyyy HH:MM overwritten by
subsequent punches, this
will be the event time.

“0” implies that there is

no associated punch with
Break End.

0, Values “1-N” imply which

Break End (Associated Punch) break-end-punch
1-N punch is stored as Break
End.
E.g. “2” implies that
Punch 2 is stored as
Break End.

174 Matrix COSEC Web API User Guide

Table: Getting Attendance Records for Authorization - Response Fields

Field Name Tag Name Valid Values Remarks

Punch time for break end.

If a Punch was
Break End Time break-end-time mm/dd/yyyy HH:MM overwritten by
subsequent punches, this
will be the event time.

A-Z
a-z It displays the Remark
Remark remark 0-9 given while authorization
_.,()[]:@!#$*+/\ of application.

Max 15 chars

Allowed Characters
Final RIC ID final-ric A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Final RIC Name final-ric-name
a-z
0-9
-_. ()[]

MM/DD/YYYY
Final RIC Verdict Date Time final-ric-verdict-date HH:MM

1: pending Provides status of

Final RIC Verdict final-ric-verdict
2: authorized application.

Max 15 chars

Allowed Characters
Non-Final RIC ID nonfinal-ric A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC Name nonfinal-ric-name
a-z
0-9
-_. ()[]

Non-Final RIC Verdict Date MM/DD/YYYY

nonfinal-ric-verdict-date
Time HH:MM

1: pending
Non-Final RIC Verdict nonfinal-ric-verdict
2: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC Remark nonfinal-ric-remark
a-z
0-9
_.,()[]:@!#$*+/\

Matrix COSEC Web API User Guide 175

Table: Getting Attendance Records for Authorization - Response Fields

Field Name Tag Name Valid Values Remarks

Max 15 chars

Allowed Characters
Non-Final RIC2 ID nonfinal-ric2 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC2 Name nonfinal-ric2-name
a-z
0-9
-_. ()[]

Non-Final RIC2 Verdict Date MM/DD/YYYY

nonfinal-ric2-verdict-date
Time HH:MM

1: pending
Non-Final RIC2 Verdict nonfinal-ric2-verdict
2: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC2 Remark nonfinal-ric2-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC3 ID nonfinal-ric3 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC3 Name nonfinal-ric3-name
a-z
0-9
-_. ()[]

Non-Final RIC3 Verdict Date MM/DD/YYYY

nonfinal-ric3-verdict-date
Time HH:MM

1: pending
Non-Final RIC3 Verdict nonfinal -ric3-verdict
2: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC3 Remark nonfinal-ric3-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC4 ID nonfinal-ric4 A-Z
a-z
0-9
@_ / : .

176 Matrix COSEC Web API User Guide

Table: Getting Attendance Records for Authorization - Response Fields

Field Name Tag Name Valid Values Remarks

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC4 Name nonfinal-ric4-name
a-z
0-9
-_. ()[]

Non-Final RIC4 Verdict Date MM/DD/YYYY

nonfinal-ric4-verdict-date
Time HH:MM

1: pending
Non-Final RIC4 Verdict nonfinal-ric4 -verdict
2: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC4 Remark nonfinal-ric4-remark
a-z
0-9
_.,()[]:@!#$*+/\

Matrix COSEC Web API User Guide 177

Authorizing Attendance

This can be used to authorize attendance records for users.

Action

action=set

Syntax

http://<servername>/api.svc/v2/attendance-authorization?action=set;<argument>=<value>…

User Rights

Same as Getting Attendance Records for Authorization.

Parameters

Table: Authorizing Attendance - Parameters

Argument Valid Values Mandatory Default Value Description

This is the identification number for the

user whose attendance record is to be
authorized.
userid 15 characters Yes -
Note: Login user should have
necessary rights on this user to
successfully send authorization
request.

This is the attendance date for which

Attendance-date ddmmyyyy Yes -
records are to be authorized.

1: authorize This is the verdict to be applied to an

verdict 2: revoke Yes - attendance record pending for
authorization.

Max 50 chars
Allowed Characters
A-Z If remark not entered then default value
remark No -
a-z as per the verdict will be applied.
0-9
<Space>

178 Matrix COSEC Web API User Guide

Getting Event Records for Authorization

This can be used to fetch the event records of a single user or multiple users based on a specified date range and
the specified authorization status (i.e. pending or authorized). These records can then be authorized by the
reporting in-charge and system administrator.

Action

action=get

Syntax

http://<servername>/api.svc/v2/event-authorization?action=get;<argument>=<value>…

User Rights

User Rights

Enabled.
System Account
User must have rights on following pages (COSEC Web Application):
Time and Attendance > Authorization/Approval> Event Authorization

Enabled.

ESS User must be a reporting in-charge with rights on the following ESS pages:

ESS > Approval/Authorization > Event Authorization

Parameters

Table: Getting Event Records for Authorization - Parameters

Argument Valid Values Mandatory Default Value Description

If user-filter=0, a single user’s records

will be returned.

If user-filter=1, records for all the group

members will be returned (applicable
only if login user is a reporting in-
charge or system account user)
0: individual
user-filter No 0
1: group When argument Range & Id or Id is
mentioned and argument user-id is not
provided, default value user-filter=0
should not be considered

Argument user-filter should only be

applied when argument user-id is
provided, else it should be ignored.

Matrix COSEC Web API User Guide 179

Table: Getting Event Records for Authorization - Parameters

Argument Valid Values Mandatory Default Value Description

This is the identification number for the

user whose data is to be fetched.

For ESS user:

If user-filter=0, the userid should be of
any user belonging to the group for
which login user is reporting in-charge.
If user-filter=1, the userid should be
15 alphanumeric char. same as login user’s ID. The login user
(for user) must be a reporting in-charge.

A to Z For a System Account user:

a to z If user-filter=0, the userid can be any
userid Yes -
user’s id. (If the System Account user
0 to 9 has rights on that user)
/ _ \\ . @ : ? , - ~ ! $ ` *
+ If user-filter=1, the userid can be any
user’s ID (If the System Account user
has rights on that user and the user is a
reporting in-charge).

In case user-id & user-filter are

provided along with id/id & range,
priority should always be given to user-
id & user-filter. Value of id/id & range to
be ignored in that case.

Records for past 30

days up to the current Date range for which records need to
date-range ddmmyyyy-ddmmyyyy No
date will be fetched if be fetched.
no range is specified.

0: All
Event authorization- Fetch event records based on their
1: Pending No 0 (Pending)
status authorization status.
2: Authorized

All In this argument only single value

Organization should be allowed.
Branch
Department If argument range's value is specified
Designation as "All", ids of all the users that login
Section User (If argument user has rights over will return.
Range No
Category Range is not specified)
Grade In case user-id /user-id & user-filter are
User provided along with id/id & range,
Custom-group-1 priority should always be given to user-
Custom-group-2 id / user-id & user-filter. Value of id/id &
custom-group-3 range to be ignored in that case.

If argument range is not mentioned and

individual argument ID has specified,
then id should be considered of User.

1 to 999999 (for all the Argument ID can have multiple ids as

ranges except all & value with comma separated.
ID user) No - For example Id=1,2,…..999.
Max 15 alphanumeric
characters (for user) In case user-id /user-id & user-filter are
provided along with id/id & range,
priority should always be given to user-
id / user-id & user-filter. Value of id/id &
range to be ignored in that case.

180 Matrix COSEC Web API User Guide

Response Fields

Table: Getting Event Records for Authorization - Response Fields

Field Name Tag Name Valid Values Remarks

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

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

Event DateTime event-datetime mm/dd/yyyy hh:mm:ss

This index number is

Index Number index-no Numbers 18 characters
unique for every event.

0 - In Specifies whether events

I/O Type iotype
1 - Out is In or Out type.

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

Specifies whether the

0 : denied
Access Allowed or Denied access_allowed event came is allowed or
1: allowed
denied.

50 characters for
“Loc_name” tag

If for received event

latitude and longitude/
mac address value match
Valid Values: with any of the configured
gps_ latitude, location then display
gps_longitude, Location Name. Or it will
gsm_latitude, display Location Name
Source/Device/Location
gsm_longitude, as per Google.
Details
Src_device_loc_details ble_code,
ble_name
If event received from
mac_address,
Loc_name, device, then display that
Device_name Device Name.

If latitude and longitude/

mac address doesn’t
match with location and
event not from device
then display the received
value.

0 : Pending Authorization
Status is displayed w.r.t
Authorization Status Auth_status 1: Authorized
logged in user.

Matrix COSEC Web API User Guide 181

Table: Getting Event Records for Authorization - Response Fields

Field Name Tag Name Valid Values Remarks

Max 50 alphanumaric
characters.

A-Z When Multi Language is

Reason punch-reason a-z On, Invalid Character set
0-9 = Set 1
_-
<space>
()[].,/+!@$:*

Max 15 chars

Allowed Characters
Final RIC ID final-ric A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Final RIC Name final-ric-name
a-z
0-9
-_. ()[]

MM/DD/YYYY
Final RIC Verdict Date Time final-ric-verdict-date HH:MM

1: pending
Provides status of
Final RIC Verdict final-ric-verdict 2: authorized
application.

Max 30 chars
Allowed Characters
A-Z
Final RIC Remark final-ric-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC ID nonfinal-ric A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC Name nonfinal-ric-name
a-z
0-9
-_. ()[]

Non-Final RIC Verdict Date MM/DD/YYYY

nonfinal-ric-verdict-date
Time HH:MM

0: pending
Non-Final RIC Verdict nonfinal-ric-verdict
1: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC Remark nonfinal-ric-remark
a-z
0-9
_.,()[]:@!#$*+/\

182 Matrix COSEC Web API User Guide

Table: Getting Event Records for Authorization - Response Fields

Field Name Tag Name Valid Values Remarks

Max 15 chars

Allowed Characters
Non-Final RIC2 ID nonfinal-ric2 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC2 Name nonfinal-ric2-name
a-z
0-9
-_. ()[]

Non-Final RIC2 Verdict Date MM/DD/YYYY

nonfinal-ric2-verdict-date
Time HH:MM

0: pending
Non-Final RIC2 Verdict nonfinal-ric2-verdict
1: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC2 Remark nonfinal-ric2-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC3 ID nonfinal-ric3 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC3 Name nonfinal-ric3-name
a-z
0-9
-_. ()[]

Non-Final RIC3 Verdict Date MM/DD/YYYY

nonfinal-ric3-verdict-date
Time HH:MM

0: pending
Non-Final RIC3 Verdict nonfinal-ric3-verdict
1: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC3 Remark nonfinal-ric3-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC4 ID nonfinal-ric4 A-Z
a-z
0-9
@_ / : .

Matrix COSEC Web API User Guide 183

Table: Getting Event Records for Authorization - Response Fields

Field Name Tag Name Valid Values Remarks

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC4 Name nonfinal-ric4-name
a-z
0-9
-_. ()[]

Non-Final RIC4 Verdict Date MM/DD/YYYY

nonfinal-ric4-verdict-date
Time HH:MM

0: pending
Non-Final RIC4 Verdict nonfinal-ric4-verdict
1: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC4 Remark nonfinal-ric4-remark
a-z
0-9
_.,()[]:@!#$*+/\

Valid values 0,1

0=no photo
Wphoto wphoto
1=with photo

As stored against the

eid eid Max 15 numeric digits
event in the server DB

Type type 2 numeric digits

MID mid 5 numeric digits

Flash Count flash_count 5 numeric digits

Roll Over Count roll_over_count 5 numeric digits

Event Sequence Number event_sequence_no 7 numeric digits

15 characters 0 = Job Assignment Type

= “Fixed” or “None”
0-4294967295
1-4294967294 = Job
Reference ID
Job ID job-id corresponding to
respective Job Codes

4294967295 = Job
Reference ID selected =
None

Allowed Characters
A-Z,
Job Code job-code 15 Characters a-z
0-9
.-_()

Allowed Characters
A-Z
Job Name job-name 30 Characters a-z
0-9
-_.()[]

184 Matrix COSEC Web API User Guide

Authorizing Events

This can be used to authorize events for users.

Action

action=set

Syntax

http://<servername>/api.svc/v2/event-authorization?action=set;<argument>=<value>…

User Rights

Same as Getting Event Records for Authorization.

Parameters

Table: Authorizing Events - Parameters

Argument Valid Values Mandatory Default Value Description

max 8 characters The user is allowed to select multiple

index number each separated by
index-no Yes -
valid values: “(comma)" for authorizing multiple
Numeric events of users.

1: authorize
This is the verdict to be applied to an
verdict Yes -
event record pending for authorization.

Max 50 chars
Allowed Characters
A-Z If remark not entered then default value
remark No -
a-z as per the verdict will be applied.
0-9
<Space>

If any RIC/SA tries to authorize an already authorized application, “Authorizing this event is not allowed”
message will be displayed.

Matrix COSEC Web API User Guide 185

Getting Overtime/C-OFF Authorization Records

To fetch Overtime/C-OFF Authorization records of users and authorize them.

Action

action=get

Syntax

http://<servername>/api.svc/v2/ot-coff-authorization?action=get;<argument>=<value>…

User Rights

User Rights

Enabled.

System Account User must have rights on following pages (COSEC Web Application):

Time Attendance > Authorization/Approval > Overtime/C-OFF

Enabled.

ESS User must be a reporting in-charge with rights on the following ESS pages:

ESS > Time Attendance > Overtime/C-OFF Authorization

Parameters

Table: Getting Overtime/C-OFF Authorization Records - Parameters

Argument Valid Values Mandatory Default Value Description

If user-filter=0, a single user’s records

will be returned.

If user-filter=1, records for all the group

members will be returned (applicable
only if login user is a reporting in-
charge or system account user)
0: individual
User-filter No 0 (individual)
1: group When argument Range & Id or Id is
mentioned and argument user-id is not
provided , default value user-filter=0
should not be considered.

Argument user-filter should only be

applied when argument user-id is
provided, else it should be ignored.

186 Matrix COSEC Web API User Guide

Table: Getting Overtime/C-OFF Authorization Records - Parameters

Argument Valid Values Mandatory Default Value Description

This is the identification number for the

user whose data is to be fetched.

For ESS user:

If user-filter=0, the userid should be

login user’s ID or of any user belonging
to the group for which login user is
reporting in-charge.
If user-filter=1, the userid should be
same as login user’s ID and user
15 alphanumeric should be a reporting in-charge.
Char. (for user)
A to Z For a System Account user:
Userid a to z Yes -
0 to 9 If user-filter=0, the userid can be any
/_\\.@: user’s id.The System account user
must have rights on this user.

If user-filter=1, the userid can be any

user’s ID. The System account user
must have rights on this user and the
user must be a reporting in-charge.

In case userid & user-filter are provided

along with id/id & range, priority should
always be given to userid & user-filter.
Value of id/id & range to be ignored in
that case.

0: Daily To specify the daily or monthly period

Period No 0
1: Monthly for OT-C-OFF authorization records.

Records for 30 days

Date range for which overtime/c-off
prior to current date
Date-range ddmmyyyy-ddmmyyyy No authorization records need to be
will be fetched if no
fetched.
range is specified.

If Monthly period is selected, then

Month-year Mmyyyy No current month-year
specify month-year

0: Pending
To fetch records based on their
Authorization-status 1: Authorized No 0 (Pending)
authorization status.

All In this argument only single value

Organization should be allowed.
Branch
Department If argument range's value is specified
Designation as "All", ids of all the users that login
Section User (If argument user has rights over will return.
Range No
Category Range is not specified)
Grade In case user-id /user-id & user-filter are
User provided along with id/id & range,
Custom-group-1 priority should always be given to user-
Custom-group-2 id / user-id & user-filter. Value of id/id &
custom-group-3 range to be ignored in that case.

Matrix COSEC Web API User Guide 187

Table: Getting Overtime/C-OFF Authorization Records - Parameters

Argument Valid Values Mandatory Default Value Description

If argument range is not mentioned and

individual argument ID has specified,
1 to 999999 (for all the then User id should be considered.
ranges except all &
user) Argument ID can have multiple ids as
Max 15 alphanumeric value with comma separated.
ID characters (for user) No - For example Id=1,2,…..999.
A to Z
a to z In case user-id /user-id & user-filter are
0 to 9 provided along with id/id & range,
/_\\.@: priority should always be given to user-
id / user-id & user-filter. Value of id/id &
range to be ignored in that case.

Response Fields

Table: Getting Overtime/C-OFF Authorization Records - Response Fields

Field Name Tag Name Valid Values Remarks

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

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

Max. 15 alphanumeric
Short Name short-name -
characters

Attendance Date attendance-date mm/dd/yyyy -

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

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

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

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

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

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

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

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

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

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

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

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

188 Matrix COSEC Web API User Guide

Table: Getting Overtime/C-OFF Authorization Records - Response Fields

Field Name Tag Name Valid Values Remarks

Special Function 1 spfid1

Special Function 2 spfid2

Special Function 3 spfid3

Special Function 4 spfid4 1=Official In,

2=Official Out,
Special Function 5 spfid5 3=ShortLeave In,
4=ShortLeave Out,
Special Function 6 spfid6 5=Regular In,
1-10
6=Regular Out,
Special Function 7 spfid7
7=Lunch In,
Special Function 8 spfid8 8=Lunch Out,
9=Overtime In,
Special Function 9 spfid9 10=Overtime Out

Special Function 10 spfid10

Special Function 11 spfid11

Special Function 12 spfid12

Shift shift Two character code -

Return blank if
Actual OT1 ot1 HHHHHH:MM
unavailable.

Return blank if
Actual OT2 ot2 HHHHHH:MM
unavailable.

Return blank if
Actual OT3 ot3 HHHHHH:MM
unavailable.

Return blank if
Actual OT4 ot4 HHHHHH:MM
unavailable.

Return blank if
Actual OT5 ot5 HHHHHH:MM
unavailable.

Return blank if
Authorized OT1 authorized-ot1 HHHHHH:MM
unavailable.

Return blank if
Authorized OT2 authorized-ot2 HHHHHH:MM
unavailable.

Return blank if
Authorized OT3 authorized-ot3 HHHHHH:MM
unavailable.

Return blank if
Authorized OT4 authorized-ot4 HHHHHH:MM
unavailable.

Return blank if
Authorized OT5 authorized-ot5 HHHHHH:MM
unavailable.

Part of actual OT1

Authorized OT1 as C-Off authorized-coff1 HHH:MM component, authorized
as C-Off

Part of actual OT2

Authorized OT2 as C-Off authorized-coff2 HHH:MM component, authorized
as C-Off

Part of actual OT3

Authorized OT3 as C-Off authorized-coff3 HHH:MM component, authorized
as C-Off

Matrix COSEC Web API User Guide 189

Table: Getting Overtime/C-OFF Authorization Records - Response Fields

Field Name Tag Name Valid Values Remarks

Part of actual OT4

Authorized OT4 as C-Off authorized-coff4 HHH:MM component, authorized
as C-Off

Part of actual OT5

Authorized OT5 as C-Off authorized-coff5 HHH:MM component, authorized
as C-Off

Return blank if
unavailable.

Authorized OT1 by In-charge 1 authorized-ot1-ric1 HHH:MM Here, Incharge having

non-final authority is
considered as In-
charge1.

Return blank if
unavailable.

Authorized OT2 by In-charge 1 authorized-ot2-ric1 HHH:MM Here, Incharge having

non-final authority is
considered as In-
charge1.

Return blank if
unavailable.

Authorized OT3 by In-charge 1 authorized-ot3-ric1 HHH:MM Here, Incharge having

non-final authority is
considered as In-
charge1.

Return blank if
unavailable.

Authorized OT4 by In-charge 1 authorized-ot4-ric1 HHH:MM Here, Incharge having

non-final authority is
considered as In-
charge1.

Return blank if
unavailable.

Authorized OT5 by In-charge 1 authorized-ot5-ric1 HHH:MM Here, Incharge having

non-final authority is
considered as In-
charge1.

Part of actual OT1

component, authorized
as C-Off By Incharge1.
Authorized OT1 as C-Off by In-
authorized-coff1-ric1 HHH:MM
charge 1 Here, Incharge having
non-final authority is
considered as In-
charge1.

Part of actual OT2

component, authorized
as C-Off By Incharge1.
Authorized OT2 as C-Off by In-
authorized-coff2-ric1 HHH:MM
charge 1 Here, Incharge having
non-final authority is
considered as In-
charge1.

190 Matrix COSEC Web API User Guide

Table: Getting Overtime/C-OFF Authorization Records - Response Fields

Field Name Tag Name Valid Values Remarks

Part of actual OT3

component, authorized
as C-Off By Incharge1.
Authorized OT3 as C-Off by In-
authorized-coff3-ric1 HHH:MM
charge 1 Here, Incharge having
non-final authority is
considered as In-
charge1.

Part of actual OT4

component, authorized
as C-Off By Incharge1.
Authorized OT4 as C-Off by In-
authorized-coff4-ric1 HHH:MM
charge 1 Here, Incharge having
non-final authority is
considered as In-
charge1.

Part of actual OT5

component, authorized
as C-Off By Incharge1.
Authorized OT5 as C-Off by In-
authorized-coff5-ric1 HHH:MM
charge 1 Here, Incharge having
non-final authority is
considered as In-
charge1.

Return blank if
unavailable.

Authorized OT1 by In-charge 2 authorized-ot1-ric2 HHH:MM Here, Incharge having

non-final authority is
considered as In-
charge2.

Return blank if
unavailable.

Authorized OT2 by In-charge 2 authorized-ot2-ric2 HHH:MM Here, Incharge having

non-final authority is
considered as In-
charge2.

Return blank if
unavailable.

Authorized OT3 by In-charge 2 authorized-ot3-ric2 HHH:MM Here, Incharge having

non-final authority is
considered as In-
charge2.

Return blank if
unavailable.

Authorized OT4 by In-charge 2 authorized-ot4-ric2 HHH:MM Here, Incharge having

non-final authority is
considered as In-
charge2.

Return blank if
unavailable.

Authorized OT5 by In-charge 2 authorized-ot5-ric2 HHH:MM Here, Incharge having

non-final authority is
considered as In-
charge2.

Matrix COSEC Web API User Guide 191

Table: Getting Overtime/C-OFF Authorization Records - Response Fields

Field Name Tag Name Valid Values Remarks

Part of actual OT1

component, authorized
as C-Off By Incharge2.
Authorized OT1 as C-Off by In-
authorized-coff1-ric2 HHH:MM
charge 2 Here, Incharge having
non-final authority is
considered as In-
charge2.

Part of actual OT2

component, authorized
as C-Off By Incharge2.
Authorized OT2 as C-Off by In-
authorized-coff2-ric2 HHH:MM
charge 2 Here, Incharge having
non-final authority is
considered as In-
charge2.

Part of actual OT3

component, authorized
as C-Off By Incharge2.
Authorized OT3 as C-Off by In-
authorized-coff3-ric2 HHH:MM
charge 2 Here, Incharge having
non-final authority is
considered as In-
charge2.

Part of actual OT4

component, authorized
as C-Off By Incharge2.
Authorized OT4 as C-Off by In-
authorized-coff4-ric2 HHH:MM
charge 2 Here, Incharge having
non-final authority is
considered as In-
charge2.

Part of actual OT5

component, authorized
as C-Off By Incharge2.
Authorized OT5 as C-Off by In-
authorized-coff5-ric2 HHH:MM
charge 2 Here, Incharge having
non-final authority is
considered as In-
charge2.

Return blank if
unavailable.

Authorized OT1 by In-charge 3 authorized-ot1-ric3 HHH:MM Here, Incharge having

non-final authority is
considered as In-
charge3.

Return blank if
unavailable.

Here, Incharge having

Authorized OT2 by In-charge 3 authorized-ot2-ric3 HHH:MM
non-final authority is
considered as In-
charge3.

192 Matrix COSEC Web API User Guide

Table: Getting Overtime/C-OFF Authorization Records - Response Fields

Field Name Tag Name Valid Values Remarks

Return blank if
unavailable.

Authorized OT3 by In-charge 3 authorized-ot3-ric3 HHH:MM Here, Incharge having

non-final authority is
considered as In-
charge3.

Return blank if
unavailable.

Authorized OT4 by In-charge 3 authorized-ot4-ric3 HHH:MM Here, Incharge having

non-final authority is
considered as In-
charge3.

Return blank if
unavailable.

Authorized OT5 by In-charge 3 authorized-ot5-ric3 HHH:MM Here, Incharge having

non-final authority is
considered as In-
charge3.

Part of actual OT1

component, authorized
as C-Off By NonFinal
Incharge.
Authorized OT1 as C-Off by In-
authorized-coff1-ric3 HHH:MM
charge 3
Here, Incharge having
non-final authority is
considered as In-
charge3.

Part of actual OT2

component, authorized
as C-Off By NonFinal
Incharge.
Authorized OT2 as C-Off by In-
authorized-coff2-ric3 HHH:MM
charge 3
Here, Incharge having
non-final authority is
considered as In-
charge3.

Part of actual OT3

component, authorized
as C-Off By NonFinal
Incharge.
Authorized OT3 as C-Off by In-
authorized-coff3-ric3 HHH:MM
charge 3
Here, Incharge having
non-final authority is
considered as In-
charge3.

Part of actual OT4

component, authorized
as C-Off By NonFinal
Incharge.
Authorized OT4 as C-Off by In-
authorized-coff4-ric3 HHH:MM
charge 3
Here, Incharge having
non-final authority is
considered as In-
charge3.

Matrix COSEC Web API User Guide 193

Table: Getting Overtime/C-OFF Authorization Records - Response Fields

Field Name Tag Name Valid Values Remarks

Part of actual OT5

component, authorized
as C-Off By NonFinal
Incharge.
Authorized OT5 as C-Off by In-
authorized-coff5-ric3 HHH:MM
charge 3
Here, Incharge having
non-final authority is
considered as In-
charge3.

Return blank if
unavailable.

Authorized OT1 by In-charge 4 authorized-ot1-ric4 HHH:MM Here, Incharge having

non-final authority is
considered as In-
charge4.

Return blank if
unavailable.

Authorized OT2 by In-charge 4 authorized-ot2-ric4 HHH:MM Here, Incharge having

non-final authority is
considered as In-
charge4.

Return blank if
unavailable.

Authorized OT3 by In-charge 4 authorized-ot3-ric4 HHH:MM Here, Incharge having

non-final authority is
considered as In-
charge4.

Return blank if
unavailable.

Authorized OT4 by In-charge 4 authorized-ot4-ric4 HHH:MM Here, Incharge having

non-final authority is
considered as In-
charge4.

Return blank if
unavailable.

Authorized OT5 by In-charge 4 authorized-ot5-ric4 HHH:MM Here, Incharge having

non-final authority is
considered as In-
charge4.

Part of actual OT1

component, authorized
as C-Off By NonFinal
Incharge.
Authorized OT1 as C-Off by In-
authorized-coff1-ric4 HHH:MM
charge 4
Here, Incharge having
non-final authority is
considered as In-
charge4.

194 Matrix COSEC Web API User Guide

Table: Getting Overtime/C-OFF Authorization Records - Response Fields

Field Name Tag Name Valid Values Remarks

Part of actual OT2

component, authorized
as C-Off By NonFinal
Incharge.
Authorized OT2 as C-Off by In-
authorized-coff2-ric4 HHH:MM
charge 4
Here, Incharge having
non-final authority is
considered as In-
charge4.

Part of actual OT3

component, authorized
as C-Off By NonFinal
Incharge.
Authorized OT3 as C-Off by In-
authorized-coff3-ric4 HHH:MM
charge 4
Here, Incharge having
non-final authority is
considered as In-
charge4.

Part of actual OT4

component, authorized
as C-Off By NonFinal
Incharge.
Authorized OT4 as C-Off by In-
authorized-coff4-ric4 HHH:MM
charge 4
Here, Incharge having
non-final authority is
considered as In-
charge4.

Part of actual OT5

component, authorized
as C-Off By NonFinal
Incharge.
Authorized OT5 as C-Off by In-
authorized-coff5-ric4 HHH:MM
charge 4
Here, Incharge having
non-final authority is
considered as In-
charge4.

Return blank if
unavailable.

Authorized OT1 by In-charge 5 authorized-ot1-ric5 HHH:MM Here, Incharge having

non-final authority is
considered as In-
charge5.

Return blank if
unavailable.

Authorized OT2 by In-charge 5 authorized-ot2-ric5 HHH:MM Here, Incharge having

non-final authority is
considered as In-
charge5.

Return blank if
unavailable.

Authorized OT3 by In-charge 5 authorized-ot3-ric5 HHH:MM Here, Incharge having

non-final authority is
considered as In-
charge5.

Matrix COSEC Web API User Guide 195

Table: Getting Overtime/C-OFF Authorization Records - Response Fields

Field Name Tag Name Valid Values Remarks

Return blank if
unavailable.

Authorized OT4 by In-charge 5 authorized-ot4-ric5 HHH:MM Here, Incharge having

non-final authority is
considered as In-
charge5.

Return blank if
unavailable.

Authorized OT5 by In-charge 5 authorized-ot5-ric5 HHH:MM Here, Incharge having

non-final authority is
considered as In-
charge5.

Part of actual OT1

component, authorized
as C-Off By NonFinal
Incharge.
Authorized OT1 as C-Off by In-
authorized-coff1-ric5 HHH:MM
charge 5
Here, Incharge having
non-final authority is
considered as In-
charge5.

Part of actual OT2

component, authorized
as C-Off By NonFinal
Incharge.
Authorized OT2 as C-Off by In-
authorized-coff2-ric5 HHH:MM
charge 5
Here, Incharge having
non-final authority is
considered as In-
charge5.

Part of actual OT3

component, authorized
as C-Off By NonFinal
Incharge.
Authorized OT3 as C-Off by In-
authorized-coff3-ric5 HHH:MM
charge 5
Here, Incharge having
non-final authority is
considered as In-
charge5.

Part of actual OT4

component, authorized
as C-Off By NonFinal
Incharge.
Authorized OT4 as C-Off by In-
authorized-coff4-ric5 HHH:MM
charge 5
Here, Incharge having
non-final authority is
considered as In-
charge5.

Part of actual OT5

component, authorized
as C-Off By NonFinal
Incharge.
Authorized OT5 as C-Off by In-
authorized-coff5-ric5 HHH:MM
charge 5
Here, Incharge having
non-final authority is
considered as In-
charge5.

196 Matrix COSEC Web API User Guide

Table: Getting Overtime/C-OFF Authorization Records - Response Fields

Field Name Tag Name Valid Values Remarks

Return blank if
Total Authorized OT total-authorized-ot HHH:MM
unavailable.

Return blank if
Total Authorized C-Off authorized-coff HHH:MM
unavailable.

Return blank if
Gross Work Hours gross-workhours HH:MM
unavailable.

Return blank if
Extra Work Hours extra-workhours HH:MM
unavailable.

Return blank if
Net Work Hours net-workhours HHHHHHH:MM
unavailable.

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
<Leave Codes>as
PH : Public Holiday
Second Half secondhalf configured in COSEC
FB : Field Break
RD : Rest Day
IN : Official In
<Leave Codes>

0: Status is not WO Should be displayed for

Week-Off wo
1: Status is WO Period=0

0: Status is not PH Should be displayed for

Public Holiday ph
1: Status is PH Period=0

Should be displayed for

Remark for OT1 remark1 50 characters
Period=0

Should be displayed for

Remark for OT2 remark2 50 characters
Period=0

Should be displayed for

Remark for OT3 remark3 50 characters
Period=0

Should be displayed for

Remark for OT4 remark4 50 characters
Period=0

Should be displayed for

Remark for OT5 remark5 50 characters
Period=0

Should be displayed for

Period=0
Remark for OT1 By In-Charge
remark1-ric1 50 characters Here, Incharge having
1
final authority is
considered as In-charge1

Should be displayed for

Period=0
Remark for OT2 By In-Charge
remark2-ric1 50 characters Here, Incharge having
1
final authority is
considered as In-charge1

Matrix COSEC Web API User Guide 197

Table: Getting Overtime/C-OFF Authorization Records - Response Fields

Field Name Tag Name Valid Values Remarks

Should be displayed for

Period=0
Remark for OT3 By In-Charge
remark3-ric1 50 characters Here, Incharge having
1
final authority is
considered as In-charge1

Should be displayed for

Period=0
Remark for OT4 By In-Charge
remark4-ric1 50 characters Here, Incharge having
1
final authority is
considered as In-charge1

Should be displayed for

Period=0
Remark for OT5 By In-Charge
remark5-ric1 50 characters Here, Incharge having
1
final authority is
considered as In-charge1

Should be displayed for

Period=0
Remark for OT1 By In-Charge
remark1-ric2 50 characters Here, Incharge having
2
final authority is
considered as In-charge2

Should be displayed for

Period=0
Remark for OT2 By In-Charge
remark2-ric2 50 characters Here, Incharge having
2
final authority is
considered as In-charge2

Should be displayed for

Period=0
Remark for OT3 By In-Charge
remark3-ric2 50 characters Here, Incharge having
2
final authority is
considered as In-charge2

Should be displayed for

Period=0
Remark for OT4 By In-Charge
remark4-ric2 50 characters Here, Incharge having
2
final authority is
considered as In-charge2

Should be displayed for

Period=0
Remark for OT5 By In-Charge
remark5-ric2 50 characters Here, Incharge having
2
final authority is
considered as In-charge2

Return blank if
10 Characters unavailable
Application Date adv-application-date
DD/MM/YYYY Should be displayed for
Period=0

Return blank if
5 characters unavailable
Applied OT Hours adv-applied-othours
HH:MM Should be displayed for
Period=0

Return blank if
5 characters unavailable
Approved OT Hours adv-approved-othours
HH:MM Should be displayed for
Period=0

Return blank if
unavailable
Approved By adv-approvedby 15 characters
Should be displayed for
Period=0

198 Matrix COSEC Web API User Guide

Table: Getting Overtime/C-OFF Authorization Records - Response Fields

Field Name Tag Name Valid Values Remarks

1 Character Return blank if

0=Pending unavailable
Status status
1=Approved Should be displayed for
2=Rejected Period=0

Return blank if
unavailable
Remarks remark 30 characters
Should be displayed for
Period=0

Max 15 chars

Allowed Characters
Final RIC ID final-ric-type1 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Final RIC Name final-ric-name-type1
a-z
0-9
-_. ()[]

Final RIC Verdict Date Time- MM/DD/YYYY

final -verdict-date-type1
type1 HH:MM

0: pending
Provides status of
Final RIC Verdict-type1 final-verdict-type1 1: authorized
application.

Max 30 chars
Allowed Characters
A-Z
Final RIC Remark-type1 final-remark-type1
a-z
0-9
_.,()[]:@!#$*+/\

Final RIC Verdict Date Time- MM/DD/YYYY

final-verdict-date-type2
type2 HH:MM

0: pending
Provides status of
Final RIC Verdict-type2 final-verdict-type2 1: authorized
application.

Max 30 chars
Allowed Characters
A-Z
Final RIC Remark-type2 final-remark-type2
a-z
0-9
_.,()[]:@!#$*+/\

Final RIC Verdict Date Time- MM/DD/YYYY

final-verdict-date-type3
type3 HH:MM

0: pending
Provides status of
Final RIC Verdict-type3 final-verdict-type3 1: authorized
application.

Max 30 chars
Allowed Characters
A-Z
Final RIC Remark-type3 final-remark-type3
a-z
0-9
_.,()[]:@!#$*+/\

Matrix COSEC Web API User Guide 199

Table: Getting Overtime/C-OFF Authorization Records - Response Fields

Field Name Tag Name Valid Values Remarks

Final RIC Verdict Date Time- MM/DD/YYYY

final-verdict-date-type4
type4 HH:MM

0: pending
Provides status of
Final RIC Verdict-type4 final-verdict-type4 1: authorized
application.

Max 30 chars
Allowed Characters
A-Z
Final RIC Remark-type4 final-remark-type4
a-z
0-9
_.,()[]:@!#$*+/\

Final RIC Verdict Date Time- MM/DD/YYYY

final-verdict-date-type5
type5 HH:MM

0: pending
Provides status of
Final RIC Verdict-type5 final-verdict-type5 1: authorized
application.

Max 30 chars
Allowed Characters
A-Z
Final RIC Remark-type5 final-remark-type5
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC1 ID nonfinal-ric1-type1 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC1 Name nonfinal-ric1-name-type1
a-z
0-9
-_. ()[]

Non-Final RIC1 Verdict Date MM/DD/YYYY

nonfinal1-verdict-date-type1
Time-type1 HH:MM

0: pending
Non-Final RIC1 Verdict-type1 nonfinal1-verdict-type1
1: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC1 Remark-type1 nonfinal1-remark-type1
a-z
0-9
_.,()[]:@!#$*+/\

Non-Final RIC1 Verdict Date MM/DD/YYYY

nonfinal1-verdict-date-type2
Time-type2 HH:MM

0: pending
Non-Final RIC1 Verdict-type2 nonfinal1-verdict-type2
1: authorized

200 Matrix COSEC Web API User Guide

Table: Getting Overtime/C-OFF Authorization Records - Response Fields

Field Name Tag Name Valid Values Remarks

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC1 Remark-type2 nonfinal1-remark-type2
a-z
0-9
_.,()[]:@!#$*+/\

Non-Final RIC1 Verdict Date MM/DD/YYYY

nonfinal1-verdict-date-type3
Time-type3 HH:MM

0: pending
Non-Final RIC1 Verdict-type3 nonfinal1-verdict-type3
1: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC1 Remark-type3 nonfinal1-remark-type3
a-z
0-9
_.,()[]:@!#$*+/\

Non-Final RIC1 Verdict Date MM/DD/YYYY

nonfinal1-verdict-date-type4
Time-type4 HH:MM

0: pending
Non-Final RIC1 Verdict-type4 nonfinal1-verdict-type4
1: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC1 Remark-type4 nonfinal1-remark-type4
a-z
0-9
_.,()[]:@!#$*+/\

Non-Final RIC1 Verdict Date MM/DD/YYYY

nonfinal1-verdict-date-type5
Time-type5 HH:MM

0: pending
Non-Final RIC1 Verdict-type5 nonfinal1-verdict-type5
1: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC1 Remark-type5 nonfinal1-remark-type5
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC2 ID nonfinal-ric2-type2 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC2 Name nonfinal-ric2-name-type2
a-z
0-9
-_. ()[]

Non-Final RIC2 Verdict Date MM/DD/YYYY

nonfinal2-verdict-date-type1
Time-type1 HH:MM

0: pending
Non-Final RIC2 Verdict-type1 nonfinal2-verdict-type1
1: authorized

Matrix COSEC Web API User Guide 201

Table: Getting Overtime/C-OFF Authorization Records - Response Fields

Field Name Tag Name Valid Values Remarks

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC2 Remark-type1 nonfinal2-remark-type1
a-z
0-9
_.,()[]:@!#$*+/\

Non-Final RIC2 Verdict Date MM/DD/YYYY

nonfinal2-verdict-date-type2
Time-type2 HH:MM

0: pending
Non-Final RIC2 Verdict-type2 nonfinal2-verdict-type2
1: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC2 Remark-type2 nonfinal2-remark-type2
a-z
0-9
_.,()[]:@!#$*+/\

Non-Final RIC2 Verdict Date MM/DD/YYYY

nonfinal2-verdict-date-type3
Time-type3 HH:MM

0: pending
Non-Final RIC2 Verdict-type3 nonfinal2-verdict-type3
1: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC2 Remark-type3 nonfinal2-remark-type3
a-z
0-9
_.,()[]:@!#$*+/\

Non-Final RIC2 Verdict Date MM/DD/YYYY

nonfinal2-verdict-date-type4
Time-type4 HH:MM

0: pending
Non-Final RIC2 Verdict-type4 nonfinal2-verdict-type4
1: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC2 Remark-type4 nonfinal2-remark-type4
a-z
0-9
_.,()[]:@!#$*+/\

Non-Final RIC2 Verdict Date MM/DD/YYYY

nonfinal2-verdict-date-type5
Time-type5 HH:MM

0: pending
Non-Final RIC2 Verdict-type5 nonfinal2-verdict-type5
1: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC2 Remark-type5 nonfinal2-remark-type5
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC3 ID nonfinal-ric3-type A-Z
a-z
0-9
@_ / : .

202 Matrix COSEC Web API User Guide

Table: Getting Overtime/C-OFF Authorization Records - Response Fields

Field Name Tag Name Valid Values Remarks

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC3 Name nonfinal-ric3-name
a-z
0-9
-_. ()[]

Non-Final RIC3 Verdict Date MM/DD/YYYY

nonfinal3-verdict-date-type1
Time-type1 HH:MM

0: pending
Non-Final RIC3 Verdict-type1 nonfinal3-verdict-type1
1: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC3 Remark-type1 nonfinal3-remark-type1
a-z
0-9
_.,()[]:@!#$*+/\

Non-Final RIC3 Verdict Date MM/DD/YYYY

nonfinal3-verdict-date-type2
Time-type2 HH:MM

0: pending
Non-Final RIC3 Verdict-type2 nonfinal3-verdict-type2
1: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC3 Remark-type2 nonfinal3-remark-type2
a-z
0-9
_.,()[]:@!#$*+/\

Non-Final RIC3 Verdict Date MM/DD/YYYY

nonfinal3-verdict-date-type3
Time-type3 HH:MM

0: pending
Non-Final RIC3 Verdict-type3 nonfinal3-verdict-type3
1: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC3 Remark-type3 nonfinal3-remark-type3
a-z
0-9
_.,()[]:@!#$*+/\

Non-Final RIC3 Verdict Date MM/DD/YYYY

nonfinal3-verdict-date-type4
Time-type4 HH:MM

0: pending
Non-Final RIC3 Verdict-type4 nonfinal3-verdict-type4
1: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC3 Remark-type4 nonfinal3-remark-type4
a-z
0-9
_.,()[]:@!#$*+/\

Non-Final RIC3 Verdict Date MM/DD/YYYY

nonfinal3-verdict-date-type5
Time-type5 HH:MM

0: pending
Non-Final RIC3 Verdict-type5 nonfinal3-verdict-type5
1: authorized

Matrix COSEC Web API User Guide 203

Table: Getting Overtime/C-OFF Authorization Records - Response Fields

Field Name Tag Name Valid Values Remarks

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC3 Remark-type5 nonfinal3-remark-type5
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC4 ID nonfinal-ric4 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC4 Name nonfinal-ric4-name
a-z
0-9
-_. ()[]

Non-Final RIC4 Verdict Date DD/MM/YYYY

nonfinal4-verdict-date-type1
Time-type1 HH:MM

0: pending
Non-Final RIC4 Verdict-type1 nonfinal4-verdict-type1
1: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC4 Remark-type1 nonfinal4-remark-type1
a-z
0-9
_.,()[]:@!#$*+/\

Non-Final RIC4 Verdict Date MM/DD/YYYY

nonfinal4-verdict-date-type2
Time-type2 HH:MM

0: pending
Non-Final RIC4 Verdict-type2 nonfinal4-verdict-type2
1: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC4 Remark-type2 nonfinal4-remark-type2
a-z
0-9
_.,()[]:@!#$*+/\

Non-Final RIC4 Verdict Date MM/DD/YYYY

nonfinal4-verdict-date-type3
Time-type3 HH:MM

0: pending
Non-Final RIC4 Verdict-type3 nonfinal4-verdict-type3
1: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC4 Remark-type3 nonfinal4-remark-type3
a-z
0-9
_.,()[]:@!#$*+/\

Non-Final RIC4 Verdict Date MM/DD/YYYY

nonfinal4-verdict-date-type4
Time-type4 HH:MM

0: pending
Non-Final RIC4 Verdict-type4 nonfinal4 -verdict-type4
1: authorized

204 Matrix COSEC Web API User Guide

Table: Getting Overtime/C-OFF Authorization Records - Response Fields

Field Name Tag Name Valid Values Remarks

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC4 Remark-type4 nonfinal4-remark-type4
a-z
0-9
_.,()[]:@!#$*+/\

Non-Final RIC4 Verdict Date MM/DD/YYYY

nonfinal4-verdict-date-type5
Time-type5 HH:MM

0: pending
Non-Final RIC4 Verdict-type5 nonfinal4-verdict-type5
1: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC4 Remark-type5 nonfinal4-remark--type5
a-z
0-9
_.,()[]:@!#$*+/\

Matrix COSEC Web API User Guide 205

Authorizing Overtime/C-OFF

This API can be used to authorize Overtime/C-OFF hours for a user.

Action

action=set

Syntax

http://<servername>/api.svc/v2/ot-coff-authorization?action=set;<argument>=<value>…

User Rights

Same as Getting Overtime/C-OFF Authorization Records.

Parameters

Table: Authorizing Overtime/C-OFF - Parameters

Argument Valid Values Mandatory Default Value Description

This is the identification number for the

user whose overtime/C-OFF is to be
userid 15 Char. Yes -
authorized. The login user must have
appropriate rights on this user id.

0: Daily To specify the daily or monthly period

Period No 0
1: Monthly for OT-C-OFF authorization records.

Yes
Date ddmmyyyy for daily - The date for authorization.
period

Yes
If Monthly period is selected, then
Month-year mmyyyy for monthly -
specify month-year
period

Authorization 1: OT Then C-OFF

No 1 Applicable only for monthly period
Sequence 2: C-OFF Then OT

authorized-ot1 HHH:MM

authorized-coff1 HHH:MM
The
authorized-ot2 HHH:MM ‘authorized-
ot’ or
authorized-coff2 HHH:MM ‘authorized- Hours authorized as an Overtime type
coff’ must be (OT1-OT5) and
authorized-ot3 HHH:MM
mentioned for Part of the actual OT component (OT1-
-
atleast one of OT5), authorized as C-Off.
authorized-coff3 HHH:MM
the OT
authorized-ot4 HHH:MM components
(OT1-OT5)
authorized-coff4 HHH:MM for
authorization.
authorized-ot5 HHH:MM

authorized-coff5 HHH:MM

206 Matrix COSEC Web API User Guide

Table: Authorizing Overtime/C-OFF - Parameters

Argument Valid Values Mandatory Default Value Description

remark1

remark2
Authorization Remarks for individual
remark3 50 characters No N/A
OT components.
remark4

remark5

Example1

This sample request authorizes the OT for a user.

Sample Request:

http://192.168.104.12/cosec/api.svc/v2/ot-coff-authorization?action=set;userid =3;Period=0;Date
=02072018;authorized-ot1 =001:00

Sample Response:

success: 0510200002 : saved successfully

Matrix COSEC Web API User Guide 207

Processing Monthly Attendance

On COSEC, some attendance parameters for a user are updated only when the monthly attendance data is
manually processed. This monthly attendance process can be executed through API. This API shall be used to
process the monthly attendance for a particular user.

Action

action=command

Syntax

http://<servername>/api.svc/v2/monthly-process?action=command;<argument>=<value>…

User Rights

User Rights

System Account Enabled.

User must have rights on following pages (COSEC Web Application):

Time Attendance> Process > Monthly Attendance

ESS Enabled for all ESS users.

Parameters

Table: Processing Monthly Attendance - Parameters

Argument Valid Values Mandatory Default Value Description

For system user, this can be the user

ID of any user on whom the login user
has appropriate user rights.

For ESS user, the user ID should be

same as login user’s ID.

The process will be executed only if the

15 alphanumeric
Userid Yes - user meets the following condition:
Char. (for user)
User is Active
User is an active T&A user.

In case userid is provided along with id/

id & range, priority should always be
given to userid. Value of id/id & range to
be ignored in that case.

Current month and The month and year for which the
month-year mmyyyy No
year. attendance process is to be run.

208 Matrix COSEC Web API User Guide

Table: Processing Monthly Attendance - Parameters

Argument Valid Values Mandatory Default Value Description

All In this argument only single value

Organization should be allowed.
Branch
Department If argument range's value is specified
Designation as "All", ids of all the users that login
Section User (If argument user has rights over will return.
Range No
Category Range is not specified)
Grade In case user-id /user-id & user-filter are
User provided along with id/id & range,
Custom-group-1 priority should always be given to user-
Custom-group-2 id / user-id & user-filter. Value of id/id &
custom-group-3 range to be ignored in that case.

If argument range is not mentioned and

individual argument ID is specified,
1 to 999999 (for all the then id should be considered of User.
ranges except all &
user) Argument ID can have multiple ids as
Max 15 alphanumeric value with comma separated. For
ID characters (for user) No - example Id=1,2,…..999
A to Z
a to z In case user-id /user-id & user-filter are
0 to 9 provided along with id/id & range,
/_\\.@: priority should always be given to user-
id / user-id & user-filter. Value of id/id &
range to be ignored in that case.

Matrix COSEC Web API User Guide 209

In/Out Reasons

In/Out Reasons are reasons configured on the COSEC Server Application, to be used for submitting Short Leave
or Official IN/OUT entries for approval. Use this API to fetch all In/Out Reasons configured on COSEC.

Action

action=get

Syntax

http://<servername>/api.svc/v2/in-out-reasons?action=get;<argument>=<value>…

User Rights

User Rights

System Account Enabled

ESS Enabled

Response Fields

Table: In/Out Reasons - Response Fields

Field Name Tag Name Valid Values Remarks

Reason ID reason-id 1-99 -

Reason reason 30 alphanumeric characters -

0: In
Type of Reason reason-type -
1: Out

Example

Sample Request:

http://matrixserver/api.svc/v2/in-out-reasons?action=get

Sample Response:

reason-id|reason|reason-type
1|Sickness|1
2|Personal Work|0
3|Meeting with Client|0
4|Meeting with Client - OUT|1
<EOT>

210 Matrix COSEC Web API User Guide

Getting Shift Wise Count

This shall be used to get shift wise counts of users as per their punches or day's status. This will return count of
scheduled, reported, not reported, on leave/tour, etc.

Action

action=get

Syntax

http://<servername>/api.svc/v2/shift-wise-count?action=<get>;<argument>=<value>...

User Rights

User Rights

System Account Enabled.

ESS Enabled only for ESS Reporting In-charge user

Parameters

Table: Getting Shift Wise Count- Parameters

Argument Valid Values Mandatory Default Value Description

attendance-date ddmmyyyy - Current date -

range all - all

organization
branch
department
designation
section
-
category
grade
user
customgroup1ID
customgroup2ID
customgroup3ID

Id Yes if range - Multiple id can be selected, each

1 to 999 (for all the
is other than separated by ", (comma)" e.g.:"1, 3, 7,
ranges except all &
“all” 9…" Or
user)
Select a range of id
15 Char. (for user)
E.g."1-50".

shift-id Alpha-numeric - - Multiple shift-id can be selected, each

separated by ", (comma)"
e.g.:"GS,G1,NS, ES..."

Matrix COSEC Web API User Guide 211

Response Fields

Table: Getting Shift Wise Count- Response Fields

Field Name Tag Name Valid Values Remarks

Shift ID shift-id 2 alphanumeric characters Shows Shift ID

Shift Name shift-name 20 characters Shows Shift Name

Shift Start Time shift-start HH:MM Shift’s Start Time

Shift End Time shift-end HH:MM Shift’s End Time

Assigned Users assigned numeric

On Leave/Tour/COFF leave-tour-coff numeric

On Week Off/Holiday wo-ph numeric

Reported Users reported numeric

Not Reported Users not-reported numeric

Scheduled Users scheduled numeric

Early IN Users early-in numeric

Late IN Users late-in numeric

Early OUT Users early-out numeric

Late OUT Users late-out numeric

Example

Sample Request:

http://matrix-server/api.svc/v2/shift-wise-count?action=get;attendance-date=01012016;range=all;

212 Matrix COSEC Web API User Guide

Getting Site Wise Count

This shall be used to get site wise counts of users as per their events. This will return IN count, OUT count and
who’s IN Count users. The http query to access site data from the COSEC server should resemble the following
syntax:

Action

action= get

Syntax

http://<servername>/api.svc/v2/site-wise-count?action=<get>;<argument>=<value>..]

The Site Wise Count API allows you to perform the following function:

User Rights

User Rights

System Account Enabled

ESS Enabled only for ESS – Reporting In charge user. Only member users should be
considered in this case.

Parameters

Table: Obtaining Data on Existing Sites - Parameters

Argument Valid Values Mandatory Description

If time-range is not mentioned, then consider it

to be “(current date time – 48 hours) to (current
date time)” by default.

If field does not contain hh mm ss values then

ddmmyyyyhhmmss – by default assume:
time-range No
ddmmyyyyhhmmss Start as – 00:00:00 and End as – 23:59:59
Example- if parameter value is: date-range =
11082020-12082020
Then convert it to: 11082020000000 –
12082020235959

all
organization
branch
department
System support mentioned ranges.
designation
If range & Id, both are not mentioned, then
section
Range No consider it to be “all” by default.
category
If range is not passed but Id passed, consider
grade
range=user.
user
customgroup1ID
customgroup2ID
customgroup3ID

Matrix COSEC Web API User Guide 213

Table: Obtaining Data on Existing Sites - Parameters

Argument Valid Values Mandatory Description

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

System should allow user to select multiple site-

site-id Numeric No id, each separated by “, (comma)” e.g.: ”1, 2, 3,
4…”

Response Fields

Table: Obtaining Data on Existing Sites - Response Fields

Field Name Tag Name Valid Values Remarks

Site ID site-id 3 characters numeric Return Site’s ID

Site Name site-name 30 characters Return Site’s Name

IN Count in numeric

OUT Count out numeric

Whos IN Count whos-in numeric

Records should be ordered first by Site ID (Ascending).

Example

http://matrix-server/api.svc/v2/site-wise-count?action=get;time-range=18032016080000-18032016200000;range=all;

site-id site-name in out whos-in

1 Site 1 100 62 38
2 Site 2 150 125 25
3 Site 3 175 135 40

214 Matrix COSEC Web API User Guide

Getting Shift-Site Wise Count

This API is used to get site wise counts of reported users against each shift as per their punches or day's status.

Action

action= get

Syntax

http://<servername>/api.svc/v2/shift-site-wise-count?action=<get>;<argument>=<value>...

User Rights

User Rights

System Account Enabled.

ESS Enabled only for ESS Reporting In-charge user

Parameters

Table: Getting Shift-Site Wise Count- Parameters

Argument Valid Values Mandatory Default Value Description

attendance-date ddmmyyyy - current date -

range all - all

organization
branch
department
designation
section
-
category
grade
user
customgroup1ID
customgroup2ID
customgroup3ID

Id Yes if range is - Multiple id can be selected, each

1 to 999 (for all the
other than separated by ", (comma)" e.g.:"1, 3, 7,
ranges except all &
“all” 9…" Or
user)
Select a range of id
15 Char. (for user)
E.g."1-50".

shift-id Alpha-numeric Yes - -

2 characters

Response Fields

Table: Getting Shift-Site Wise Count- Response Fields

Field Name Tag Name Valid Values Remarks

Site ID site-id 3 numeric characters Shows Site ID

Site Name site-name 30 characters Shows Site Name

Reported Users reported numeric

Matrix COSEC Web API User Guide 215

Getting Site Wise User Detail

This API is used to get site wise users details as per their IN OUT events. This will return user’s date-time detail of
IN, OUT for sites.The http query to access site data from the COSEC server should resemble the following syntax:

Action

action= get

Syntax

http://<servername>/api.svc/v2/site-wise-user-details?action=<get>;<argument>=<value>..]

User Rights

User Rights

System Account Enabled

ESS
Enabled only for ESS – Reporting In charge user. Only member users
should be considered in this case.

Parameters

Table: Getting Site Wise User Details - Parameters

Argument Valid Values Mandatory Description

If time-range is not mentioned, then consider it

to be “(current date time – 48 hours) to (current
date time)” by default.

If field does not contain hh mm ss values then

ddmmyyyyhhmmss –
time-range No by default assume:
ddmmyyyyhhmmss
Start as – 00:00:00 and End as – 23:59:59
Example- if parameter value is: date-range =
11082020-12082020
Then convert it to: 11082020000000 –
12082020235959

All
organization
branch
department
System support mentioned ranges.
designation
If range & Id, both are not mentioned, then
section
Range No consider it to be “all” by default.
category
If range is not passed but Id passed, consider
grade
range=user.
user
customgroup1ID
customgroup2ID
customgroup3ID

216 Matrix COSEC Web API User Guide

Table: Getting Site Wise User Details - Parameters

Argument Valid Values Mandatory Description

1-999999
(for all the ranges except all
& user)
15 alphanumeric Char.(for
Each range (except all) shall have specific id.
user)
System should allow user to select multiple id,
A to Z
each separated by “, (comma)” e.g.:”1, 3, 7,
a to z
Id Yes 9…”
0 to 9
Or
/_\\.@:
Select a range of id
E.g.”1-50”.
Note: This is the min to max
range. In case of a system
with only 1-50 id defined then
valid range shall be 1-50.

System should allow user to select multiple

site-id Numeric No site-id, each separated by “, (comma)” e.g.: ”1,
2, 3, 4…”

Response Fields

Table: Getting Site Wise User Details - Response Fields

Field Name Tag Name Valid Values Remarks

Site ID site-id 3 characters numeric Return Site’s ID

Site Name site-name 30 characters Return Site’s Name

User ID user-id 15 characters Return User’s ID

User Name user-name 45 characters Return User’s Name

Return Date Time

IN Events in-events numeric
(ddmmyyyyhhmmss)

Return Date Time

OUT Events out-events numeric
(ddmmyyyyhhmmss)

Records should be ordered first by Site ID (Ascending).

Multiple In /Out events should be comma separated.
Multiple entry of same user should be return in case events are found in multiple site. (E.g; If event of User
1 is found in Site 1 and Site 2, then two entries if User 1 will be returned.

Example

http://matrix-server/api.svc/v2/site-wise-user-details?action=get;time-range=11082020080000-
11082020180000;range=all;

site-id site-name user-id user-name in-events out-events

11082020080000,
11082020180000,
1 Site 001 001 Shalini 11082020090000,110
11082020160000
82020015000
2 Site 001 002 Kartikaya 11082020080500
3 Site 001 003 Kwisha 11082020103000 11082020153000
4 Site 002 003 Kwisha 11082020104000 11082020154000
5 Site 002 003 Kwisha 11082020140000

Matrix COSEC Web API User Guide 217

Getting Overtime Application

This shall be used to get the user’s overtime application data for the specific date period, and to submit new
overtime applications.

Action

action= get

Syntax

http://<servername>/api.svc/v2/overtime-application?action=<get/set/update/delete>;<argument>=<value>...]

User Rights

User Rights

Enabled if User has rights on the following Page:

System Account
Time and Attendance > Utilities > Overtime Application

Enabled if User has rights on the following Page:

ESS
ESS >Time Attendance > Overtime Application

Parameters

Table: Getting Overtime Application Data - Parameters

Argument Valid Values Mandatory Description

0= individual
user-filter No -
1= group

For ESS user:

If user-filter=0, the userid should be login user’s
ID or of any user belonging to the group for
which login user is reporting in-charge.

If user-filter=1, the userid should be same as

login user’s ID. If the login user is not a
reporting group in-charge, return error message
as per mentioned below.

15 alphanumeric Char. (for For a System Account user:

user) If user-filter=0, the userid can be any user’s id.
A to Z If the System account user has rights on that
userid Yes
a to z user, return the records. Otherwise, return
0 to 9 message as per mentioned below.
/_\\.@:
If user-filter=1, the userid can be any user’s
ID.If the System account user does not have
rights on that user, return message as per
mentioned below.
If the system user has sufficient rights, check
the mentioned userid. If it is reporting group in-
charge’s id, return the records of his group
members. If the user is not a reporting group
in-charge, return error message as per
mentioned below.

218 Matrix COSEC Web API User Guide

Table: Getting Overtime Application Data - Parameters

Argument Valid Values Mandatory Description

ddmmyyyy-ddmmyyyy
Valid Values:
date-range dd (Date): 01-31 No -
mm (Month): 01-12
yyyy (Year)

0: all
1: pending
application-status No -
2: approved
3: rejected

Response Fields

Table: Getting Overtime Application Data - Response Fields

Field Name Tag Name Valid Values Remarks

Allowed Characters : 15
alphanumeric Char.
A to Z
User ID user-id 15 characters
a to z
0 to 9
/_\\.@:

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

Short Name short-name max 15 alphanumeric characters

Same as form-number.
TID (form no.) tid 10 digits Auto Generated on saving
leave application.

Date & Time on which

application gets applied.
mm(Month): 01-12
dd(Date): 01-31
Applied Date and Time application-date mm/dd/yyyy HH:MM:SS
yyyy(Year): 4 digits
HH(Hour): 00-23
MM(Minute): 00-59
SS(Seconds): 00-59

Date for which OT

application applied.
OT Date OT-date mm/dd/yyyy mm(Month): 01-12
dd(Date): 01-31
yyyy(Year): 4 digits

Overtime Duration for

which OT application
Applied OT Hours applied-hours HH:MM applied.
HH(Hour): 00-23
MM(Minute): 00-59

Overtime Duration for

which OT application
Approved OT Hours approved-hours HH:MM approved.
HH(Hour): 00-23
MM(Minute): 00-59

Matrix COSEC Web API User Guide 219

Table: Getting Overtime Application Data - Response Fields

Field Name Tag Name Valid Values Remarks

Allowed Characters
A-Z
Address address Max 30 chars. a-z
0-9
_.,()[]:@!#$*+/\

Contact Info contact 20 numeric characters

1: pending
Provides status of
Application Status application-status 2: approved
application.
3: rejected

If not available, return

blank.
mm(Month): 01-12
Application Verdict Date verdict-date mm/dd/yyyy HH:MM dd(Date): 01-31
yyyy(Year): 4 digits
HH(Hour): 00-23
MM(Minute): 00-59

Allowed Characters
A-Z
Application Reason application –reason 50 characters a-z
0-9
_.,()[]:@!#$*+/\

Max 30 chars
Allowed Characters
Not mandatory. If not
A-Z
Application Approval Remark application-remark supplied, this field remains
a-z
blank.
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Final RIC ID final-ric A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Final RIC Name final-ric-name
a-z
0-9
-_. ()[]

1: pending
Provides status of
Final RIC Verdict final-ric-verdict 2: approved
application.
3: rejected

Max 15 chars

Allowed Characters
Non-Final RIC ID nonfinal-ric A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC Name nonfinal-ric-name
a-z
0-9
-_. ()[]

220 Matrix COSEC Web API User Guide

Table: Getting Overtime Application Data - Response Fields

Field Name Tag Name Valid Values Remarks

Non-Final RIC Verdict Date MM/DD/YYYY

nonfinal-ric-verdict-date
Time HH:MM

1: pending
Non-Final RIC Verdict nonfinal-ric-verdict 2: approved
3: rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC Remark nonfinal-ric-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC2 ID nonfinal-ric2 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC2 Name nonfinal-ric2-name
a-z
0-9
-_. ()[]

Non-Final RIC2 Verdict Date MM/DD/YYYY

nonfinal-ric2-verdict-date
Time HH:MM

1: pending
Non-Final RIC2 Verdict nonfinal-ric2-verdict 2: approved
3: rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC2 Remark nonfinal-ric2-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC3 ID nonfinal-ric3 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC3 Name nonfinal-ric3-name
a-z
0-9
-_. ()[]

Non-Final RIC3 Verdict Date MM/DD/YYYY

nonfinal-ric3-verdict-date
Time HH:MM

1: pending
Non-Final RIC3 Verdict nonfinal-ric3-verdict 2: approved
3: rejected

Matrix COSEC Web API User Guide 221

Table: Getting Overtime Application Data - Response Fields

Field Name Tag Name Valid Values Remarks

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC3 Remark nonfinal-ric3-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC4 ID nonfinal-ric4 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC4 Name nonfinal-ric4-name
a-z
0-9
-_. ()[]

Non-Final RIC4 Verdict Date MM/DD/YYYY

nonfinal-ric4-verdict-date
Time HH:MM

1: pending
Non-Final RIC4 Verdict nonfinal-ric4-verdict 2: approved
3: rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC4 Remark nonfinal-ric4-remark
a-z
0-9
_.,()[]:@!#$*+/\

222 Matrix COSEC Web API User Guide

Setting Overtime Application

This shall be used to set the user’s overtime application data for the specific date period.

Action

action= set

Parameters

Table: Setting Overtime Application Data - Parameters

Multi-
Language Default
Argument Valid Values Description
Character Value
set

15 alphanumeric Char. (for

user)
A to Z
userid NA NA -
a to z
0 to 9
/_\\.@:

8 characters

Format: ddmmyyyy
dd(Date): 01-31
OT-date mm(Month): 01-12 NA NA Mandatory field.
yyyy: Year

Valid values are current date

& future date only

4 characters

OT-hours Format: hhmm NA NA Mandatory field.

hh(Hour): 00-23
mm(Minute): 01-59

50 characters

Allowed Characters:
reason A-Z NA Overtime Not Mandatory.
a-z
0-9
_.,()[]:@!#$*+/\

30 characters
Allowed Characters:

Address A-Z NA Blank Not Mandatory.

a-z
0-9
_.,()[]:@!#$*+/\

20 Digits
Valid Values:
contact NA Blank Not Mandatory.
0–9
-+()

Matrix COSEC Web API User Guide 223

Updating Overtime Application

This shall be used to update user’s overtime application data for the specific date period.

Action

action= update

Parameters

Table: Updating Overtime Application Data - Parameters

Argument Valid Values Description

tid max 10 numeric characters Mandatory field.

15 alphanumeric Char.
A to Z
userid a to z Mandatory field.
0 to 9
/_\\.@:

8 characters

Format: ddmmyyyy
dd(Date): 01-31
OT-date mm(Month): 01-12 Not a mandatory field.
yyyy: Year

Valid values are current date & future date

only

4 characters

OT-hours Format: hhmm Not a mandatory field.

hh(Hour): 00-23
mm(Minute): 01-59

Max 50 characters

Allowed Characters:
reason A-Z Not a mandatory field.
a-z
0-9
_.,()[]:@!#$*+/\

30 characters
Allowed Characters:

Address A-Z Not a mandatory field.

a-z
0-9
_.,()[]:@!#$*+/\

contact Max 20 numeric chars. Not a mandatory field.

224 Matrix COSEC Web API User Guide

Deleting Overtime Application

This shall be used to delete the user’s overtime application data for the specific date period.

Action

action= delete

Parameters

Table: Deleting Overtime Application Data - Parameters

Argument Valid Values Description

tid max 10 numeric characters Mandatory field.

15 alphanumeric Char.
A to Z
userid a to z Mandatory field.
0 to 9
/_\\.@:

Matrix COSEC Web API User Guide 225

Overtime Approval

This shall be used to set the approval for user’s overtime application.

Action

action= set

Parameters

Table: Overtime Approval- Parameters

Multi-
Language
Argument Valid Values Default Value Description
Character
set

tid max 10 numeric characters No NA Mandatory field.

1: approve
approved - - Mandatory field.
2: reject

4 characters

OT-hours Format: hhmm NA NA Mandatory field.

hh(Hour): 00-23
mm(Minute): 01-59

--If approved: Approved

Overtime
--If rejected: Rejected
30 characters
Overtime
Or
Allowed Characters:
as per already
remark A-Z NA -
configured value (No
a-z
change: this case will
0-9
happen when final RIC
_.,()[]:@!#$*+/\
has already given
verdict & SA is going to
change it)

226 Matrix COSEC Web API User Guide

CHAPTER 8 Leave Management

This chapter lists all APIs related to leave management. Applying and Retrieving leave configurations and leave
balance data from the COSEC server and send, modify, as well as approve leave applications.

The login user requires Time and Attendance module license for these APIs.

In this section, you will find the following APIs:

Get APIs
• Getting Leave Balance Details

• Getting Leave Group Details

• Getting Leave Details

• Getting Leave Application Details

Set APIs
• Setting Leave Balance

• Applying for a Leave

Update API
• Updating an Applied Leave

Delete API
• Deleting a Pending Application

Set API
• Approving/Rejecting Leaves

Get APIs
• Getting C-OFF Balance Details

• Getting C-OFF Details

Matrix COSEC Web API User Guide 227

Getting Leave Balance Details

This API can be used to fetch leave balance data for one or more users for a specified time period.

Action

action=get

Syntax

http://<servername>/api.svc/v2/leave-balance?action=get;<argument>=<value>...

User Rights

User Rights

System Account Enabled.

User must have rights on following pages (COSEC Web Application):

Leave Management > View > Leave Balance

ESS Enabled.

User must have rights on following ESS pages:

ESS > Leave Management > Leave Balance

Parameters

Table: Getting Leave Balance Details - Parameters

Argument Valid Values Mandatory Default Value Description

To specify the user identification

number. Multiple IDs can be selected,
Max. 15 characters
separated by a ‘comma’.
allowed
E.g. “userid=1,2,3,4,5,...”
A-Z
userid Yes -
a-z
In case userid is provided along with id/
0-9
id & range, priority should always be
/_\\.@:
given to userid. Value of id/id & range to
be ignored in that case.

To specify the month and year for

Current Month and
month-year mmyyyy No which leave balance data is to be
Year
fetched.

All leaves (except Tour To specify the leave code for any pre-
leave-code Two characters No and C-OFF type configured leaves on the COSEC
leaves) Server.

228 Matrix COSEC Web API User Guide

Table: Getting Leave Balance Details - Parameters

Argument Valid Values Mandatory Default Value Description

All
In this argument only single value
Organization
should be allowed
Branch
Department
If argument range's value is specified
Designation
as "All", ids of all the users that login
Section User (If argument
Range No user has rights over will return.
Category Range is not specified)
Grade
In case user-id /user-id & user-filter are
User
provided along with id/id & range,
Custom-group-1
priority should always be given to user-
Custom-group-2
id /user-id & user-filter. Value of id/id &
custom-group-3
range to be ignored in that case.

If argument range is not mentioned and

individual argument ID is specified,
1 to 999999 (for all the then User id should be considered.
ranges except all &
user) Argument ID can have multiple ids as
Max 15 alphanumeric value separated with comma.
ID characters (for user) No - For example Id=1,2,…..999
A to Z
a to z In case user-id /user-id & user-filter are
0 to 9 provided along with id/id & range,
/_\\.@: priority should always be given to user-
id /user-id & user-filter. Value of id/id &
range to be ignored in that case.

Response fields

Table: Getting Leave Balance Details - Response Fields

Field Name Tag Name Valid Values Remarks

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

Allowed characters:
A-Z
User Name user-name 40 characters a-z
0-9
-_.()[]

max. 15 alphanumeric The short-name assigned

Short Name short-name
characters to the specified user

The leave code for the

Leave Code leave-code Two alphanumeric characters leave whose balance is
fetched

Allowed characters:
A-Z
Leave Name leave-name 30 alphanumeric characters a-z
0-9
-_.()[]

The month and year for

Month-Year period mmyyyy which leave balance data
is fetched.

Matrix COSEC Web API User Guide 229

Table: Getting Leave Balance Details - Response Fields

Field Name Tag Name Valid Values Remarks

The opening leave

Opening Balance opening-balance 1-999 (multiples of 0.5) balance for the specified
month (in days)

The closing leave

Closing Balance closing-balance 1-999 (multiples of 0.5) balance for the specified
month (in days)

The credited leaves for

Credit/Manual Credit credit 1-999 (multiples of 0.5)
the specified month

The debited leaves for

Debit/Manual Debit debit 1-999 (multiples of 0.5)
the specified month

The encashed leaves for

Encashed encashed 1-999 (multiples of 0.5)
the specified month

The availed leaves for the

Availed availed 1-999 (multiples of 0.5)
specified month

The overflown leaves for

Overflow overflow 1-999 (multiples of 0.5)
the specified month

0: Paid
1: Unpaid
The type of leave for
2: Lay Off
Leave Type leave-type which balance was
3: Restricted Holiday
requested.
4: Compensatory Off
5: Tour

Example1

This sample request obtains the Leave balance for a user. It shows the leave priority as well.

Sample Request:

http://192.168.104.12/cosec/api.svc/v2/leave-group?action=get;userid=1

Sample Response:

user-id|user-name|short-name|group-id|group-name|leave-code|leave-name|leave-type|minimum-
allowed|maximum-allowed|medical-certificate-required|balance-check-enabled|half-day-required|full-day-
required|priority
1|Chirag|Chirag|1|Leave Group-1|CL|Casual Leave|1|0.0|99.0|0|0|||3
1|Chirag|Chirag|1|Leave Group-1|PL|Paid Leave|0|1.0|99.0|0|1|||2
1|Chirag|Chirag|1|Leave Group-1|SL|Sick Leave|0|0.0|99.0|0|1|||1
<EOT>

230 Matrix COSEC Web API User Guide

Getting Leave Group Details

Specify a user ID to request details of the leave group assigned to this user on the COSEC server.

Action

action=get

Syntax

http://<servername>/api.svc/v2/leave-group?action=get;<argument>=<value>...

User Rights

User Rights

System Account Enabled.

User must have rights on following pages (COSEC Web Application):

Leave Management > Leave Group

ESS Enabled.

Parameters

Table: Getting Leave Group Details - Parameters

Argument Valid Values Mandatory Default Value Description

userid 15 alphanumeric Yes - To specify the user identification

Char. (for user) number. Multiple IDs can be selected,
A to Z separated by a ‘comma’.
a to z E.g. “userid=1,2,3,4,5,...”
0 to 9
/_\\.@: In case userid is provided along with id/
id & range, priority should always be
given to userid. Value of id/id & range to
be ignored in that case.

All In this argument only single value

Organization should be allowed.
Branch
Department If argument range's value is specified
Designation as "All", ids of all the users that login
Section User (If argument user has rights over will return.
Range No
Category Range is not specified)
Grade In case user-id /user-id & user-filter are
User provided along with id/id & range,
Custom-group-1 priority should always be given to user-
Custom-group-2 id / user-id & user-filter. Value of id/id &
custom-group-3 range to be ignored in that case.

Matrix COSEC Web API User Guide 231

Table: Getting Leave Group Details - Parameters

Argument Valid Values Mandatory Default Value Description

If argument range is not mentioned and

individual argument ID is specified,
1 to 999999 (for all the
then User id should be considered.
ranges except all &
user)
Argument ID can have multiple ids as
value with comma separated.
Max 15 alphanumeric
ID No - For example Id=1,2,…..999
characters (for user)
A to Z
In case user-id /user-id & user-filter are
a to z
provided along with id/id & range,
0 to 9
priority should always be given to user-
/_\\.@:
id / user-id & user-filter. Value of id/id &
range to be ignored in that case.

Response Fields

Table: Getting Leave Group Details - Response Fields

Field Name Tag Name Valid Values Remarks

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

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

max. 15 alphanumeric The short-name assigned

Short Name short-name
characters to the specified user

Leave Group ID group-id 1 to 99 -

Allowed characters:
A-Z
upto 30 alphanumeric a-z
Leave Group Name group-name
characters 0-9
-_.()[]

Specifies the leave code

Leave Code leave-code Two alphanumeric characters
for the leave

upto 30 alphanumeric
Leave Name leave-name Specifies the leave name
characters

0: Paid
1: Unpaid
2: Lay Off
The type of leave for
3: Restricted Holiday
Leave Type leave-type which balance was
4: Compensatory Off
requested.
5: Tour
6:Hourly Paid
7:Hourly Unpaid

The minimum allowed

Minimum Allowed at a Time minimum-allowed 1 to 999 (multiples of 0.5) leaves that can be taken
at a time

232 Matrix COSEC Web API User Guide

Table: Getting Leave Group Details - Response Fields

Field Name Tag Name Valid Values Remarks

The maximum allowed

Maximum Allowed at a Time maximum-allowed 1 to 999 (multiples of 0.5) leaves that can be taken
at a time

Specifies whether
Medical Certificae is
0=disabled required for the leave.
Medical Certficate Required medical-certificate-required 1=ensure availability Parameter should be 0
2=upload document for leave types:
Restricted Holiday, Lay
off, Tour

Parameter should be 0
for leave types: Paid,
0=disabled Unpaid, Restricted
Tour Document Requirement tour-doc-required 1=ensure availability Holiday, Compensatory
2=upload document Off, Hourly Paid Leave,
Hourly Unpaid Leave,
Lay off.

Specifies whether
0 = disabled
Balance Check Enabled balance-check-enabled balance check is enabled
1 = enabled
for the leave

Specifies the minimum

Minimum C-OFF for Half Day available C-OFF hours
half-day-required blank/HH:MM
Off required to be eligible for
half-day leave.

Specifies the minimum

Minimum C-OFF for Full Day available C-OFF hours
full-day-required blank/HH:MM
Off required to be eligible for
full-day leave.

It displays the priority of

Priority priority 1-99 leaves available in the
leave Group.

Defines the minimum

hours & minutes, if a user
applies the hourly type
leaves. Only applicable
Minimum Allowed Duration minimum-hourly-duration HH:MM format
for Hourly Leave Types
For other leave types,
parameter value will be
blank

Defines the maximum

hours & minutes for each
application, if a user
applies the hourly type
Max Allowed Duration Per
maximum-hourly-duration-app HH:MM format leaves. Only applicable
Application
for Hourly Leave Types
For other leave types,
parameter value will be
blank

Defines the maximum

hours & minutes, if a user
applies the hourly type
leaves. Only applicable
Max Allowed Duration Per Day maximum-hourly-duration-day HH:MM format
for Hourly Leave Types
For other leave types,
parameter value will be
blank

Matrix COSEC Web API User Guide 233

Table: Getting Leave Group Details - Response Fields

Field Name Tag Name Valid Values Remarks

Parameter should be 0
Min Leave For Certification 0.5-99(for cer-dur-unit=0) for leave types:
min-dur-certificatecompulsion
Compulsion 1-59999(for cer-dur-unit=1) Restricted Holiday, Lay
off, Tour.

Parameter should be 0
for leave types: Paid,
Unpaid, Restricted
Min tour Days For Document 0.5-99(for cer-dur-unit=0)
min-day-tourcompulsion Holiday, Compensatory
Compulsion 1-59999(for cer-dur-unit=1)
Off, Hourly Paid Leave,
Hourly Unpaid Leave,
Lay off.

For Unit=0 Days should

be considered
For Unit=1 Mins should
0=Days (1-99) be considered.
Certification Duration Unit cert-dur-unit
1=Mins (1-59,999) Parameter should be 0
for leave types:
Restricted Holiday, Lay
off, Tour.

Parameter should be 0
for leave types: Paid,
Unpaid, Restricted
0=Days (1-99)
Document Duration Unit doc-dur-unit Holiday, Compensatory
1=Mins (1-59,999)
Off, Hourly Paid Leave,
Hourly Unpaid Leave,
Lay off.

234 Matrix COSEC Web API User Guide

Getting Leave Details

Specify the two-character code (CL, PL, SL etc.) for a pre-defined leave, to retrieve its details from the COSEC
database.

Action

action=get

Syntax

http://<servername>/api.svc/v2/leave-details?action=get;<argument>=<value>...

User Rights

User Rights

System Account Enabled.

ESS Enabled

Parameters

Table: Getting Leave Details - Parameters

Argument Valid Values Mandatory Default Value Description

To identify the leave for which details

are to be requested.
Two alphanumeric
leave-code Yes -
characters
Multiple values can be selected by
separating each value with a ‘comma’.

Response Fields

Table: Getting Leave Details - Response Fields

Field Name Tag Name Valid Values Remarks

Specifies the leave code

Leave Code leave-code Two alphanumeric characters
for the leave

Specifies the leave

name.

upto 30 alphanumeric Allowed characters:

Leave Name leave-name
characters A-Z
a-z
0-9
-_.()[]

0: Paid
1: Unpaid
2: Lay Off
The type of leave for
3: Restricted Holiday
Leave Type leave-type which balance was
4: Compensatory Off
requested.
5: Tour
6:Hourly Paid
7: Hourly Unpaid

Matrix COSEC Web API User Guide 235

Table: Getting Leave Details - Response Fields

Field Name Tag Name Valid Values Remarks

The minimum allowed

Minimum Allowed at a Time minimum-allowed 1 to 999 (multiples of 0.5) leaves that can be taken
at a time

The maximum allowed

Maximum Allowed at a Time maximum-allowed 1 to 999 (multiples of 0.5) leaves that can be taken
at a time

Specifies whether
Medical Certificate is
0 = disabled
required for the leave.
1 = ensure availability
Medical Certificate Required medical-certificate-required Parameter should be 0
2 = upload document
for leave types:
Restricted Holiday, Lay
off, Tour.

Parameter should be 0
for leave types: Paid,
0=disabled Unpaid, Restricted
Tour Document Required tour-doc-required 1=ensure availability Holiday, Compensatory
2=upload document Off, Hourly Paid Leave,
Hourly Unpaid Leave,
Lay off.

Specifies whether
0 = disabled
Balance Check Enabled balance-check-enabled balance check is enabled
1 = enabled
for the leave

Defines the minimum

hours & minutes, if a user
applies the hourly type
leaves. Only applicable
Minimum Allowed Duration minimum-hourly-duration HH:MM format
for Hourly Leave Types
For other leave types,
parameter value will be
blank

Defines the maximum

hours & minutes for each
application, if a user
applies the hourly type
Max Allowed Duration Per
maximum-hourly-duration-app HH:MM format leaves. Only applicable
Application
for Hourly Leave Types
For other leave types,
parameter value will be
blank

Defines the maximum

hours & minutes, if a user
applies the hourly type
leaves. Only applicable
Max Allowed Duration Per Day maximum-hourly-duration-day HH:MM format
for Hourly Leave Types
For other leave types,
parameter value will be
blank

Parameter should be 0
Min Leave For Certification 0.5-99(for cer-dur-unit=0) for leave types:
min-dur-certificatecompulsion
Compulsion 1-59999(for cer-dur-unit=1) Restricted Holiday, Lay
off, Tour.

236 Matrix COSEC Web API User Guide

Table: Getting Leave Details - Response Fields

Field Name Tag Name Valid Values Remarks

Parameter should be 0
for leave types: Paid,
Unpaid, Restricted
Min tour Days For Document 0.5-99(for cer-dur-unit=0)
min-day-tourcompulsion Holiday, Compensatory
Compulsion 1-59999(for cer-dur-unit=1)
Off, Hourly Paid Leave,
Hourly Unpaid Leave,
Lay off.

For Unit=0 Days should

be considered
For Unit=1 Mins should
0=Days (1-99) be considered.
Certification Duration Unit cert-dur-unit
1=Mins (1-59,999) Parameter should be 0
for leave types:
Restricted Holiday, Lay
off, Tour.

For Unit=0 Days should

be considered
For Unit=1 Mins should
be considered.
Parameter should be 0
0=Days (1-99)
Document Duration Unit doc-dur-unit for leave types: Paid,
1=Mins (1-59,999)
Unpaid, Restricted
Holiday, Compensatory
Off, Hourly Paid Leave,
Hourly Unpaid Leave,
Lay off.

Example

The following request gets details for Sick Leave (SL) as configured on COSEC.

Sample Request:

http://matrixserver/api.svc/v2/leave-details?action=get;leave-code=SL

Sample Response:

leave-code|leave-name|leave-type|minimum-allowed|maximum-allowed|medical-certificate-required|balance-check-enabled
SL|SICK LEAVE|0|0.0|99.0|0|1
<EOT>

Matrix COSEC Web API User Guide 237

Getting Leave Application Details

Specify leave/tour application parameters such as leave type, user details, application status etc. to filter details of
all relevant applications in the response.

Action

action=get

Syntax

http://<servername>/api.svc/v2/leave-application?action=get;<argument>=<value>...

User Rights

User Rights

System Account Enabled.

User must have rights on following pages (COSEC Web Application):

Leave Management > Application/Approval > Leave Application

Leave Management > Application/Approval > Tour Application
Leave Management > Application/Approval > C-OFF Application

ESS Enabled.

User must have rights on following ESS pages:

ESS > Leave Management > Leave Application

ESS > Leave Management > Tour Application
ESS > Leave Management > C-OFF Application

Parameters

Table: Getting Leave Application Details - Parameters

Argument Valid Values Mandatory Default Value Description

If user-filter=0, a single user's

records will be returned.

If user-filter=1, records for all the

group members will be returned.

Note : user-filter=1, is applicable

if login user is a reporting in-
charge or system account user.
0: individual
user-filter No 0 (individual)
1: group When argument Range & Id or Id
is mentioned and argument user-
id is not provided, default value
user-filter=0 should not be
considered.

Argument user-filter should only

be applied when argument user-id
is provided, else it should be
ignored.

238 Matrix COSEC Web API User Guide

Table: Getting Leave Application Details - Parameters

Argument Valid Values Mandatory Default Value Description

This is the user identification

number.

For ESS user:

If user-filter=0, the userid should
be login user’s ID or of any user
belonging to the group for which
login user is reporting in-charge.
If user-filter=1, the userid should
be same as login user’s ID. The
login user must be a reporting in-
15 alphanumeric Char. (for charge.
user)
A to Z For a System Account user:
userid a to z Yes - If user-filter=0, the userid can be
0 to 9 any user’s id. (If the System
/_\\.@: Account user has rights on that
user)
If user-filter=1, the userid can be
any user’s ID (If the System
Account user has rights on that
user and the user is a reporting in-
charge).

In case userid & user-filter are

provided along with id/id & range,
priority should always be given to
userid & user-filter. Value of id/id &
range to be ignored in that case.

0: all
1: leave To specify whether the application
leave-type No 0 (all)
2: tour type is leave, tour or C-OFF
3: C-OFF

To specify the range of application

all dates for which
dates for which data is to be
date-range ddmmyyyy-ddmmyyyy No application records
fetched.
exist.

0: all
1: pending To filter applications by their
application-status No all
2: approved approval status.
3: rejected

In this argument only single value

All should be allowed.
Organization
Branch If argument range's value is
Department specified as "All", ids of all the
Designation users that login user has rights
User (If argument
Section over will return.
Range No Range is not
Category
specified)
Grade In case user-id /user-id & user-
User filter are provided along with id/id
Custom-group-1 & range, priority should always be
Custom-group-2 given to user-id / user-id & user-
custom-group-3 filter. Value of id/id & range to be
ignored in that case.

Matrix COSEC Web API User Guide 239

Table: Getting Leave Application Details - Parameters

Argument Valid Values Mandatory Default Value Description

If argument range is not

mentioned and individual
argument ID is specified, then id
should be considered of User.
1 to 999999 (for all the ranges
except all & user) Argument ID can have multiple
Max 15 alphanumeric ids as value separated with
characters (for user) comma.
ID No -
A to Z For example Id=1,2,…..999
a to z
0 to 9 In case user-id /user-id & user-
/_\\.@: filter are provided along with id/id
& range, priority should always be
given to user-id / user-id & user-
filter. Value of id/id & range to be
ignored in that case.

Response Fields

Table: Getting Leave Application Details - Response Fields

Field Name Tag Name Valid Values Remarks

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

Allowed characters:
A-Z
User Name user-name 40 characters a-z
0-9
-_.()[]

max. 15 alphanumeric The short-name assigned

Short Name short-name
characters to a user

The leave code assigned

Leave Code leave-code Two alphanumeric characters
to a leave

Leave Name leave-name 30 alphanumeric characters The name of the leave

1: leave
Leave Type leave-type 2: tour The type of application.
3: C-OFF

Same as form-number.
TID (form no.) tid 10 digits Auto generated on saving
leave application.

mm/dd/yyyy
Applied Date and Time applied-date The date of application
HH:MM:SS

1: leave pending
2: cancellation pending
The approval status of
Application State application-state 3: modification pending
application
4: approved
5: rejected

1: Both
The half day
2: First Half Only
Consideration In Terms Of half-consideration consideration for leave
3: Second Half Only
application
4: Hourly

Start Date start-date mm/dd/yyyy The leave start date

240 Matrix COSEC Web API User Guide

Table: Getting Leave Application Details - Response Fields

Field Name Tag Name Valid Values Remarks

1: full day
2: first half The status of leave on
Day status on Start Date start-day
3: second half the starting day.
4: Hourly

End Date end-date mm/dd/yyyy The leave end date

1: full day
The status of leave on
Day status on End Date end-day 2: first half
the ending date.
3: second half

Applied Days applied-days 1 to 999 (multiples of 0.5) Number of applied days

Posted Days posted-days 1 to 999 (multiples of 0.5) Number of posted days

Allowed characters:
A-Z
Address address Max. 30 characters a-z
0-9
_.,()[]:@!#$*+/\

This is the contact

Contact Info contact upto 20 numeric characters information in a leave
application

0: no This is the availability of

Medical Certificate medical-certi
1: yes medical certificate

0= unchecked Display status of Tour

Tour Document tour-doc
1= checked Document checkbox.

0: pending
This is the approval
Application Status application-status 1: approved
status of the application
2: rejected

mm/dd/yyyy
Application Verdict Date verdict-date blank if date not available
HH:MM:SS

Allowed characters:
A-Z
Application Reason application-reason upto 50 characters a-z
0-9
_.,()[]:@!#$*+/\

Not mandatory. Blank if

not available.

Allowed characters:
Application Approval Remark application-remark Max. 30 characters
A-Z
a-z
0-9
_.,()[]:@!#$*+/\

mm/dd/yyyy
Cancellation Application Date cancellation-applied-date blank if date not available
HH:MM:SS

This is the cancellation

0: pending
status of the application.
Cancellation Status cancellation-status 1: approved
Blank if status not
2: rejected
available

mm/dd/yyyy
Cancellation Verdict Date cancellation-verdict-date blank if date not available
HH:MM:SS

Matrix COSEC Web API User Guide 241

Table: Getting Leave Application Details - Response Fields

Field Name Tag Name Valid Values Remarks

Allowed characters:
A-Z
Cancellation Reason cancellation-reason upto 50 characters a-z
0-9
_.,()[]:@!#$*+/\

Not mandatory. Blank if

not available. Allowed
characters:
Cancellation Approval Remark cancellation-remark Max. 30 characters A-Z
a-z
0-9
_.,()[]:@!#$*+/\

mm/dd/yyyy
Modification Application Date modification-applied-date blank if date not available
HH:MM:SS

1: Both
Modification Half Day 2: First Half Only The modification of half
modified-half-consideration
Consideration 3: Second Half Only day leave application
4:Hourly

The modified leave

Modified Start Date modified-start-date mm/dd/yyyy
starting date

1: full day The status of modified

Modified Day status on Start
modified-start-day 2: first half leave on the starting
Date
3: second half date.

The modified leave

Modified End Date modified-end-date mm/dd/yyyy
ending date

Modified Day status on End modified-end-day 1: full day The status of modified
Date 2: first half leave on the ending date.

Number of modified
Modified Applied Days modified-applied-days 1 to 999 (multiples of 0.5)
applied days

Number of modified
Modified Posted Days modified-posted-days 1 to 999 (multiples of 0.5)
posted days

This is the modification

0: pending
status of the application.
Modification Status modification-status 1: approved
Blank if status not
2: rejected
available

mm/dd/yyyy
Modification Verdict Date modification-verdict-date blank if date not available
HH:MM:SS

Allowed characters:
A-Z
Modification Reason modification-reason upto 50 characters a-z
0-9
_.,()[]:@!#$*+/\

Blank when leave-type is

Applied C-OFF Hours applied-coff Blank/HH:MM
leave or tour.

Allowed characters:
A-Z
a-z
Modification Approval Remark modification-remark Max. 30 characters 0-9
_.,()[]:@!#$*+/\

242 Matrix COSEC Web API User Guide

Table: Getting Leave Application Details - Response Fields

Field Name Tag Name Valid Values Remarks

6 alpha-numeric
characters.
Location Code location-code -
Blank if not available

Allowed Characters
50 characters
A-Z
Location Name
location-name a-z
Blank if not available
0-9
-_. ()[]

11 characters (max.)
GPS Latitude gps-latitude -90.0000 to +90.0000
Blank if not available

11 characters (max.)
GPS Longitude gps-longitude -180.0000 to +180.0000
Blank if not available

-90.0000 to +90.0000 11 characters (max.)

GSM Latitude gsm-latitude
Blank if not available

11 characters (max.)
GSM Longitude gsm-longitude -180.0000 to +180.0000
Blank if not available

17 characters (each byte

separated by colon)
MAC Address mac-address
Blank if not available

Returns the BLE Code

assigned to a specific
BLE Code ble-code 0-9999
location
Blank if not available

Allowed Characters 10 alphanumeric

A-Z characters (max.)
BLE Name ble-name
a-z If not available, return
0-9 blank

1 - 999
Site ID site-id 1 - 999
Blank if not available

Max 30 alphanumeric
Site Name Site-name Max 30 alphanumeric character characters
Blank if not available

If not available, return

blank.

Should show the

Attendance Date in the
Attendance Date attendance-date mm/dd/yyyy Leave application when
applied application is for
the leaves with Leave
Types = "Hourly Paid
Leave" or "Hourly Unpaid
Leave".

Matrix COSEC Web API User Guide 243

Table: Getting Leave Application Details - Response Fields

Field Name Tag Name Valid Values Remarks

If not available, return

blank.

Should show the Applied

hours in the Leave
Applied Duration applied-hours HH:MM Format
application when applied
application is for the
leaves with Leave Types
= “Hourly Paid Leave” or
“Hourly Unpaid Leave”.

If not available, return

blank.

Should show the posted

hours in the Leave
Posted Duration posted-hours HH:MM Format
application when applied
application is for the
leaves with Leave Types
= “Hourly Paid Leave” or
“Hourly Unpaid Leave”.

If not available, return

blank.

Should display the Start

time configured with the
Start Time hourly-start-time HH:MM From Date control in the
Leave application page
for the leave with Leave
Type = “Hourly Paid
Leave” or “Hourly Unpaid
Leave”.

Should display the end

time configured with the
To Date control in the
Leave application page
End Time hourly-end-time HH:MM
for the leaves with Leave
Types = “Hourly Paid
Leave” or “Hourly Unpaid
Leave”.

If not available, return

blank.

Should show the

Attendance Date in the
Modification Leave
Modified Attendance Date modified-attendance-date mm/dd/yyyy
application when applied
modification application is
for the leaves with Leave
Types = “Hourly Paid
Leave” or “Hourly Unpaid
Leave”.

244 Matrix COSEC Web API User Guide

Table: Getting Leave Application Details - Response Fields

Field Name Tag Name Valid Values Remarks

If not available, return

blank.

Should show the Applied

hours in the Modification
Modified Applied Duration modified-applied-hours HH:MM Format Leave application when
applied modification
application is for the
leaves with Leave Types
= “Hourly Paid Leave” or
“Hourly Unpaid Leave”.

If not available, return

blank.

Should show the posted

hours in the Modification
Posted Duration modified-posted-hours HH:MM Format Leave application when
applied application is for
the leaves with Leave
Types = “Hourly Paid
Leave” or “Hourly Unpaid
Leave”.

If not available, return

blank.

Should display the Start

time configured with the
Modified Start Time modified-hourly-start-time HH:MM From Date control in the
Leave application page
for the Modification
leaves with Leave Type =
“Hourly Paid Leave” or
“Hourly Unpaid Leave”.

If not available, return

blank.

Should display the End

time configured with the
Modified End Time modified-hourly-end-time HH:MM From Date control in the
Leave application page
for the Modification
leaves with Leave Type =
“Hourly Paid Leave” or
“Hourly Unpaid Leave”.

Indicates whether
0= Not available
Medical Certificate Available med-cert-available medical certificate is
1= Available
available or not.

Display Status of
0=unchecked
Modified Medical Certificate modified-medical-certi Modified Medical
1=checked
Certificate checkbox.

Indicates whether
Modified Medical Certificate 0= Not available
modified- Med-cert-available medical certificate is
Available 1= Available
available or not.

0= Not Available Indicates whether tour

Tour Document Available tour-doc-available 1= Available document is available or
not.

Matrix COSEC Web API User Guide 245

Table: Getting Leave Application Details - Response Fields

Field Name Tag Name Valid Values Remarks

0=unchecked Display Status of

Modified Tour Document modified-tour-doc 1=checked Modified Tour Document
checkbox.

0= Not Available Indicates whether

Modified Tour Document
modified-tour-doc-available 1= Available modified tour document
Available
is available or not

Allowed Characters
A-Z
Modified Address modified-address a-z Max 30 chars.
0-9
_.,()[]:@!#$*+/\

Modified Contact Number modified-contact 20 numeric characters -

Max 15 chars

Allowed Characters
Final RIC ID final-ric A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Final RIC Name final-ric-name a-z
0-9
-_. ()[]

DD/MM/YYYY
Final RIC Verdict Date Time final-ric-verdict-date HH:MM

1: pending
Provides status of
Final RIC Verdict final-ric-verdict 2: approved
application.
3: rejected

Max 30 chars
Allowed Characters
A-Z
Final RIC Remark final-ric-remark a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
A-Z
Non-Final RIC ID nonfinal-ric
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC Name nonfinal-ric-name
a-z
0-9
-_. ()[]

246 Matrix COSEC Web API User Guide

Table: Getting Leave Application Details - Response Fields

Field Name Tag Name Valid Values Remarks

MM/DD/YYYY
Non-Final RIC Verdict Date
nonfinal-ric-verdict-date HH:MM
Time

1: pending
Non-Final RIC Verdict nonfinal-ric-verdict 2: approved
3: rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC Remark nonfinal-ric-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
A-Z
Non-Final RIC2 ID nonfinal-ric2
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC2 Name nonfinal-ric2-name
a-z
0-9
-_. ()[]

MM/DD/YYYY
Non-Final RIC2 Verdict Date
nonfinal-ric2-verdict-date HH:MM
Time

1: pending
Non-Final RIC2 Verdict nonfinal-ric2-verdict 2: approved
3: rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC2 Remark nonfinal-ric2-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
A-Z
Non-Final RIC3 ID nonfinal-ric3
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC3 Name nonfinal-ric3-name
a-z
0-9
-_. ()[]

MM/DD/YYYY
Non-Final RIC3 Verdict Date
nonfinal-ric3-verdict-date HH:MM
Time

Matrix COSEC Web API User Guide 247

Table: Getting Leave Application Details - Response Fields

Field Name Tag Name Valid Values Remarks

1: pending
Non-Final RIC3 Verdict nonfinal-ric3-verdict 2: approved
3: rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC3 Remark nonfinal-ric3-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
A-Z
Non-Final RIC4 ID nonfinal-ric4
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC4 Name nonfinal-ric4-name
a-z
0-9
-_. ()[]

MM/DD/YYYY
Non-Final RIC4 Verdict Date
nonfinal-ric4-verdict-date HH:MM
Time

1: pending
Non-Final RIC4 Verdict nonfinal-ric4-verdict 2: approved
3: rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC4 Remark nonfinal-ric4-remark
a-z
0-9
_.,()[]:@!#$*+/\

248 Matrix COSEC Web API User Guide

Setting Leave Balance

Use the action=set parameter to set leave balance via this API.

Action

action=set

User Rights

Same as “Getting Leave Balance Details” on page 228.

Parameters

Table: Setting Leave Balance Leave - Parameters

Argument Valid Values Mandatory Default Value Description

This is the user identification

user id Max. 15 characters Yes - number. Login user must have
appropriate rights on this user ID.

entry-type 0: Credit
1: Debit
2: Encashment Yes 0 -
3: Reuse
4: Discard

credit-mode 0: Fixed No 0 -
1: Using Accrual Policy

encashment-type 0: Leave Encashment No 0 -

1: Overflow Encashment

encashment-mode 0: Defined No 0 -
1: Available

1. entry-type = 0 (i.e. credit)

and credit-mode = 0 (i.e.
Fixed)
2. entry-type = 1 (i.e. debit)
3. entry-type = 2 (i.e.
encashment),
encashment-type = 0 (i.e.
Leave Encashment) and
days 3 Numeric No - encashment-mode = 0
(.e. Defined)
4. entry-type = 2 (i.e.
encashment),
encashment-type = 1 (i.e.
Overflow Encashment)
5. entry-type = 3 (i.e. reuse)
6. entry-type = 4 (i.e.
discard)

Matrix COSEC Web API User Guide 249

Table: Setting Leave Balance Leave - Parameters

Argument Valid Values Mandatory Default Value Description

entry-type = 2 (i.e. encashment),

leave-code = leave-type C-OFF
(internally system needs to
derive), encashment-type = 0 (i.e.
Leave Encashment), encashment-
mode = 0 (i.e. Defined)
Format to define the c-offhrs
should include the date and hours
ddmmyyyyhhmm
(Comma Seperated values both field. Below is the valid
allowed for multiple date-existing format for the field.
c-off hours No -
functionality but format for each Format: ddmmyyyyhhmm
C-offhrs should be as
ddmmyyyyhhmm) dd: Date (Valid values: 01-31)
mm: Month (Valid values: 01-12)
yyyy: Year
hh: Hour (Valid Values: 00-23)
mm: Minute (Valid Values: 00-59)
User can define multiple c-offhrs
values with comma separation

Mandatory field for

Entry-type = 0 (i.e.
credit) and credit-mode
accrual policy 2 Numeric No - = 1 (i.e. Accrual-Policy)
Two character code for any one of
the pre-configured (in COSEC
Server) accrual policy code types
should be mentioned.

Two character code for any one of

the pre-configured (in COSEC
leave-code 2 Char Yes -
Server) leave types should be
mentioned.

The field is not applicable for

1.C-OFF Encashment (i.e.
Entry-type = 2 (i.e.
Encashment), Entry-
Mode = 0 (i.e. Leave
Encashment), Leave-
period 0: Month No 0 Code = Leave type as
1: Year
C-OFF (internally
system needs to
derive))
2.Entry-type = 4 (i.e.
Discard)

250 Matrix COSEC Web API User Guide

Table: Setting Leave Balance Leave - Parameters

Argument Valid Values Mandatory Default Value Description

2 Numeric If not supplied, this field has a

Allowed values: 1- 12 default value.
The field is not applicable for
1. C-OFF Encashment (.e.
Entry-type = 2 (i.e.
Encashment), Entry-
Mode 0 (i.e. = Leave
Encashment), Leave-
month No Current month Code = Leave type as
C-OFF (system needs
to derive internally))
2. Entry-type = 4 (i.e.
Discard)
Argument is not required when
period = 1 (i.e. year), if argument
and value passed then ignore
argument for the case.

If not supplied, this field has a

default value.
The field is not applicable for
1. C-OFF Encashment (.e.
Entry-type = 2 (i.e.
Encashment), Entry-
year 4 Numeric No Current year Mode = 0 (i.e. Leave
Encashment), Leave-
Code = Leave type as
C-OFF (system needs
to derive internally))
2. Entry-type = 4 (i.e.
Discard)

0: Disable Argument is applicable for entry-

pro-rata 1: Enable No 0 type = 0 (i.e. credit) and credit-
mode=0 (i.e. fixed) only.

Max 30 Char The field is not applicable for

Allowed Characters
1. Entry-type = 0 (i.e.
A-Z
credit)
a-z
0-9 2. Entry-type = 1 (i.e.
_.,()[]:@!#$*+/\ debit)
3. Entry-type = 2 (i.e.
(Encashment),
remark No Blank Encashment-type = 0
(i.e. Leave
Encashment) and
leave-code = Leaves
apart from leave-type
‘compensatory off’
(system needs to derive
internally)

Matrix COSEC Web API User Guide 251

Applying for a Leave

Use the action=set parameter to submit a new leave application via this API.

Action

action=set

Syntax

http://<servername>/api.svc/v2/leave-application?action=set;<argument>=<value>...

User Rights

Same as “Getting Leave Application Details” on page 238.

If the login user is System Account user, a new application will always get automatically approved on
submission.

Parameters

Table: Applying for a Leave - Parameters

Argument Valid Values Mandatory Default Value Description

15 alphanumeric Char. (for user)

A to Z This is the user identification
userid a to z Yes - number. Login user must have
appropriate rights on this user ID.
0 to 9
/_\\.@:

both, if not
1: both supplied. If supplied
2: first Half Only and other than The half day consideration of
half-consideration No
3: second half only ‘both’ option, ignore leave application
4: hourly arguments: ‘start
day’ and ‘end- day’

This is the starting date of the

start-date ddmmyyyy Yes -
leave

The status of leave on the starting

date.
1: full day
start-day 2: first half No 1 (full day)
For start-day=first half, request is
3: second half
allowed only when start-date is
same as end-date.

ddmmyyyy (must be greater than

end-date No - This is the ending day of the leave
start-date)

252 Matrix COSEC Web API User Guide

Table: Applying for a Leave - Parameters

Argument Valid Values Mandatory Default Value Description

The status of leave on the ending

date.

If start-date and end-date are

1: full day
same, the value of end-day would
end-day 2: first half No 1 (full day)
be same as start-day.
3: second half
For end-day=second half, request
is allowed only when start-date is
same as end-date.

The code for any pre-configured

leave in the COSEC system.
leave-code Two alphanumeric characters Yes - e.g.
For leave: CL, PL, ML, CO etc.
For Tour: TR

The reason for taking leave.

Allowed characters:
If not supplied this
reason Max. 50 characters No A-Z
field remains blank
a-z
0-9
_.,()[]:@!#$*+/\

Contact address of the applicant.

Allowed characters:
If not supplied this
address Max. 30 characters No A-Z
field remains blank
a-z
0-9
_.,()[]:@!#$*+/\

If not supplied this

contact Max. 20 numeric characters No field remains blank Contact Number of the applicant

Must be attached for leave-types

which require mandatory medical
0: Not attached
Medical-certi No 0 (Not Attached) certificate submission. Else
1: Attached
system will not allow leave
application.

Note- If Tour Document required

is None, then by default it should
0= Unchecked be unchecked. If Tour Document
tour-doc - -
1= Checked required is Ensure Availability/
Upload document, in both cases it
should be checked.

Applicable for System Account

User only.
authorization- 0: not required
No 0 (Not required) If authorization required = 1, then
required 1: required
the application will be considered
as applied by an ESS User
(UserID mentioned in API.)

return-transaction- 0 = Not Required No 0 -

id 1 = Required

HH:MM Mandatory Field if mentioned

Leave has Leave Type = "Hourly
hourly-start-time Yes
00:00 – 23-59 Paid Leave" or "Hourly Unpaid
Leave".

Matrix COSEC Web API User Guide 253

Table: Applying for a Leave - Parameters

Argument Valid Values Mandatory Default Value Description

HH:MM Mandatory Field if mentioned

Leave has Leave Type = "Hourly
hourly-end-time Yes
00:00 – 23-59 Paid Leave" or "Hourly Unpaid
Leave".

Mandatory Field if half-

attendance-date ddmmyyyy Yes
consideration = hourly

Example

Following are some sample cases for this API:

Sample Request:

To apply for leave application for a user from system account login mentioning the requirement of authorization for
the leave:

http://192.168.104.12/cosec/api.svc/v2/leave-application?action=set;userid=1;start-date=08022018;end-
date=08022018;leave-code=PL;authorization-required=1

Sample Response:

success: 0330203002 : Leave Approval is pending

254 Matrix COSEC Web API User Guide

Updating an Applied Leave

This API can be used to edit a leave application or to modify/cancel an already approved leave application.

Action

action=update

Syntax

http://<servername>/api.svc/v2/leave-application?action=update;<argument>=<value>...

User Rights

Same as “Getting Leave Application Details” on page 238.

Parameters

Table: Updating an Applied Leave - Parameters

Argument Valid Values Mandatory Default Value Description

max 10 numeric
Tid Yes - This is the Transaction ID.
characters

15 alphanumeric
Char. (for user)
A to Z An application will be identified, based
userid Yes -
a to z on TID and User ID.

0 to 9
/_\\.@:

On editing an application, its applied

date will also get updated.

For System User, only request-type=0

is applicable. A System user can edit
any application.
0 : edit
1: apply for
ESS users can edit only pending
request-type modification Yes -
applications.
2: apply for
cancellation
Only an approved application can be
submitted for cancellation.

Only an approved or rejected

application can be submitted for
modification.

both, if not supplied.

If supplied and other Applicable only when
1: both
than ‘both’ option, request-type=0 or
half-consideration 2: first half only No
ignore arguments: request-type=1.
3: second half only
‘start day’ and ‘end-
day’

The edited or modified start date to be

specified.
Start-date ddmmyyyy No Existing value
Applicable only when request-type=0 or
request-type=1.

Matrix COSEC Web API User Guide 255

Table: Updating an Applied Leave - Parameters

Argument Valid Values Mandatory Default Value Description

Applicable only when

request-type=0 or
1: full day request-type=1.
start-day 2: first half No 1 (full day)
3: second half For start-day=first half, request is
allowed only when start-date is same
as end-date.

End-date cannot be less than start-

end-date ddmmyyyy No Existing value
date.

Applicable only when request-type=0 or

request-type=1.

If start-date and end-date are same,

1: full day
then value of end-day will be same as
end-day 2: first half No 1 (full day)
start-day.
3: second half
For end-day=second half, request is
allowed only when start-date is same
as end-date.

To edit the leave type applied for.

Applicable only when
request-type=0
Two alphanumeric
leave-code No Existing Value
characters.
Two character code for any one of the
pre-configured (in COSEC Server)
leave types should be mentioned.

Reason for updating leave application.

Applicable only when request-type=0

Allowed Characters
reason Max 50 chars. No Blank, if not supplied.
A-Z
a-z
0-9
_.,()[]:@!#$*+/\

Address of applicant.
Applicable only when
request-type=0

address Max 30 chars. No Blank, if not supplied. Allowed Characters

A-Z
a-z
0-9
_.,()[]:@!#$*+/\

Contact number of applicant.

Blank, if not supplied. Applicable only when
contact Max 20 numeric chars. No
request-type=0

Yes (only if
the particular
leave type
requires
Medical certificate status. Applicable
0: not attached mandatory
Medical-certi 0 (not attached) only when
1: attached medical
request-type=0
certificate
submission.
For e.g.
A Sick Leave)

256 Matrix COSEC Web API User Guide

Table: Updating an Applied Leave - Parameters

Argument Valid Values Mandatory Default Value Description

Applicable only when request-type=0 &

1

0= Unchecked Note- If Tour Document required is

tour-doc
1= Checked None, then by default it should be
unchecked. If Tour Document required
is Ensure Availability/Upload
document, in both cases it should be
checked.

The reason for cancellation request.

Cancellation-reason Max 50 chars. No Blank, if not supplied.
Applicable only when request-type=2

Applicable only when

modification-reason Max 50 chars. No Blank, if not supplied.
request-type=1

To revoke the approval request.

1 : revoke the approval
revoke No - Applicable only when
request
request-type=1 or,
request-type=2

HH:MM Mandatory Field if mentioned Leave

hourly-start-time Yes has Leave Type = "Hourly Paid Leave"
00:00 – 23-59 or "Hourly Unpaid Leave".

HH:MM Mandatory Field if mentioned Leave

hourly-end-time Yes has Leave Type = "Hourly Paid Leave"
00:00 – 23-59 or "Hourly Unpaid Leave".

Mandatory Field if half-consideration =

attendance-date ddmmyyyy Yes
hourly

This argument indicates, whether while

modifying leave, medical certificate has
been re-uploaded or not.

If user is not re-uploading medical

certificate then consider previously
uploaded medical certificate only,
Update-medi- 0: No
No 0 parameters value should be 0/
certificate 1: Yes
parameter will not be passed.

If while modifying leave, user is

uploading document, then parameter
should be passed with value ‘1’. This
indicates, user has uploaded new
document while modifying leave.

This argument indicates, whether while

modifying tour, tour document has
been re-uploaded or not.

If user is not re-uploading tour

document then consider previously
0: No uploaded tour document only,
Update-tour-doc No 0 parameters value should be 0/
1: Yes
parameter will not be passed.

If while modifying tour, user is

uploading document, then parameter
should be passed with value ‘1’. This
indicates, user has uploaded new
document while modifying tour.

Matrix COSEC Web API User Guide 257

Deleting a Pending Application

This API can be used to delete an existing leave application from the COSEC database.

Action

action=delete

Syntax

http://<servername>/api.svc/v2/leave-application?action=delete;<argument>=<value>...

User Rights

Same as “Getting Leave Application Details” on page 238.

Parameters

Table: Deleting a Pending Application - Parameters

Argument Valid Values Mandatory Default Value Description

max 10 numeric
tid Yes - This is the transaction ID.
characters

15 alphanumeric
Char. (for user) An application will be identified, based
A to Z on TID and User ID.
userid Yes -
a to z Login user must have appropriate
0 to 9 rights on this User ID.
/_\\.@:

258 Matrix COSEC Web API User Guide

Approving/Rejecting Leaves

This API can be used to approve or reject leave applications pending for approval. All leave applications submitted
by a System Account user will be pre-approved. Leave applications submitted by an ESS user can be approved
both by System Account users with approval rights as well as the respective reporting group in-charges.

Action

action=set

Syntax

http://<servername>/api.svc/v2/leave-approval?action=set;<argument>=<value>...

User Rights

User Rights

Enabled.

User must have rights on following pages (COSEC Web Application):

System Account
Leave Management > Application/Approval > Leave Approval
Leave Management > Application/Approval > Tour Approval
Leave Management > Application/Approval > C-Off Approval

Enabled if User is Reporting Group In-charge and has permissions defined in:

COSEC Web > Users > Reporting Group > In-Charge Permissions

ESS For any of the following :

• Leave Approval
• Tour Approval
• C-Off Approval

Parameters

Table: Approving/Rejecting Leaves - Parameters

Argument Valid Values Mandatory Default Value Description

This is the transaction ID for the leave

application.

Max. 10 numeric For “Approve All” approval option, or to

tid Yes -
characters Approve/Reject multiple leave
applications, multiple IDs can be
selected, each separated by a
‘comma’.

To approve or reject an application.

1: approve
approved Yes - Approving/rejecting multiple
2: reject
applications is also allowed.

Max 30 chars
Allowed Characters
A-Z To add a remark for the approval or
remark No Blank, if not supplied
a-z rejection.
0-9
_.,()[]:@!#$*+/\

Matrix COSEC Web API User Guide 259

Getting C-OFF Balance Details

This can be used to retrieve a user’s available balance for Compensatory-Off (C-OFF) type of leaves and the
validity period for this balance as per the applied C-OFF policy on COSEC.

Action

action=get

Syntax

http://<servername>/api.svc/v2/coff-balance?action=get;<argument>=<value>...

User Rights

User Rights

Enabled.

System Account User must have rights on following pages (COSEC Web Application):

Leave Management > View > Leave Balance

Enabled.

ESS User must have rights on following ESS pages:

ESS > Leave Management > Leave Balance

Parameters

Table: Getting C-OFF Balance Details - Parameters

Argument Valid Values Mandatory Default Value Description

15 Char.
This is the user identification number.
Allowed Characters
Multiple values can be selected, each
A-Z
userid Yes - separated by a ‘comma’
a-z
e.g.:”1, 3, 7, 9…”
0-9
/_\\.@:

Response Fields

Table: Getting C-OFF Balance Details - Response Fields

Field Name Tag Name Valid Values Remarks

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

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

260 Matrix COSEC Web API User Guide

Table: Getting C-OFF Balance Details - Response Fields

Field Name Tag Name Valid Values Remarks

The C-Off Validity period

Validity Period period mm/dd/yyyy - mm/dd/yyyy for the specific user as per
the applied policy.

Return total available

Total Available Hours total-coff-hours HH:MM C-Off hours for the user in
the above validity period.

Matrix COSEC Web API User Guide 261

Getting C-OFF Details

This shall be used to get the user’s C-OFF balance data for the specific date period. Details like opening, closing,
credit, debit, availed, encashed, overflow leaves will be returned in the response.

Action

action=get

Syntax

http://<servername>/api.svc/v2/coff-details?action=get;<argument>=<value>...

User Rights

User Rights

System Account Enabled

ESS Enabled

Parameters

Table: Getting C-OFF Details - Parameters

Argument Valid Values Mandatory Default Value Description

The user identification number.

For ESS user, It can be the logged in

user’s ID. Or the ID of users assigned
15 alphanumeric
under his reporting group.
Char. (for user)
A to Z
Userid Yes - For System Account user, it can be
a to z
user ID of any user he has rights on.
0 to 9
/_\\.@:
In case userid is provided along with id/
id & range, priority should always be
given to userid. Value of id/id & range to
be ignored in that case.

All In this argument only single value

Organization should be allowed.
Branch
Department If argument range's value is specified
Designation as "All", ids of all the users that login
Section User (If argument user has rights over will return.
Range No
Category Range is not specified)
Grade In case user-id /user-id & user-filter are
User provided along with id/id & range,
Custom-group-1 priority should always be given to user-
Custom-group-2 id / user-id & user-filter. Value of id/id &
custom-group-3 range to be ignored in that case.

262 Matrix COSEC Web API User Guide

Table: Getting C-OFF Details - Parameters

Argument Valid Values Mandatory Default Value Description

If argument range is not mentioned and

individual argument ID is specified,
1 to 999999 (for all the then User id should be considered.
ranges except all &
user) Argument ID can have multiple ids as
Max 15 alphanumeric value with comma separated. For
ID characters (for user) No example Id=1,2,…..999.
A to Z
a to z In case user-id /user-id & user-filter are
0 to 9 provided along with id/id & range,
/_\\.@: priority should always be given to user-
id / user-id & user-filter. Value of id/id &
range to be ignored in that case.

Response Fields

Table: Getting C-OFF Details - Response Fields

Field Name Tag Name Valid Values Remarks

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

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

Short Name short-name max 15 alphanumeric characters -

Date coff-date mm/dd/yyyy C-OFF attendance date .

C-OFF authorized Hours

Authorized authorized-coff blank/HH:MM
on that date.

Manually credited C-OFF

Credit/ Manual Credit credit blank/HH:MM
hours on that date.

Manually debited C-OFF

Debit/Manual Debit debit blank/HH:MM
hours on that date.

Encashed C-OFF hours on

Encashed encashed blank/HH:MM
that date.

Availed C-OFF hours on

Availed availed blank/HH:MM
that date.

Available C-OFF hours on

Available available-hours blank/HH:MM
that date.

Matrix COSEC Web API User Guide 263

264 Matrix COSEC Web API User Guide
CHAPTER 9 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 265

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

http://<servername>/api.svc/v2/accessroutemaster?action=get;<argument>=<value>...

User Rights

User Rights

System Account Enabled

ESS Disabled

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.

This is the route number for an access

route 1 to 255 No all
route.

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

panelno 1 to 65535 -
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

1 : enabled
Sequenced Route Sequencedroute -
0 : disabled

Count of configured
Group Members GroupMembers 0 - 75
members

266 Matrix COSEC Web API User Guide

 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 - 255 -

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

0 - 75 (Panel/Panel Lite) Count of configured

Group Members GroupMembers
0 - 255 (Panel200) members

Restrictions restrictions 1 : Hard

0 : Soft

Applicable for Panel Lite

V2 only

Check On Last Exit Level last-exit-level-check 0 : disabled

Parameter should be blank
1 : enabled
for sequence =0 (i.e.,
Sequenced Route flag is
disabled)

Applicable for Panel Lite

V2 only

Last Exit Level Restriction last-exit-level-restriction 1 : Hard

Parameter should be blank
0 : Soft
for sequence =0 (i.e.,
Sequenced Route flag is
disabled)

Example

To get the Access Route master details.

Sample Request:

http://192.168.104.12/cosec/api.svc/v2/accessroutemaster?action=get;type=panel;route=1;panelno=4

Sample Response:

AccessRouteNumber|AccessRouteName|Active|Sequence|PanelName|ResetOnLowestLevel|GroupMembers
1|RnD Route|1|1|Panel200-Device-4|1|2
<EOT>

Matrix COSEC Web API User Guide 267

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

http://<servername>/api.svc/v2/accessroutedetails?action=get;<argument>=<value>...

User Rights

Same as “Obtaining List of Access Routes” on page 266

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.

This is the route number for an access

route 1 to 255 No all
route.

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

panelno 1 to 65535 -
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 - 65535 -

DID DID 1 - 255 -

Panel Door, Direct Door, Direct

Door v2, NGT Direct Door,
Door Type Door Type Wireless Door, Compact Door, -
PVR Door, ARC DC 200, Door
V4

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-255 -

268 Matrix COSEC Web API User Guide

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

Field Name Tag Name Valid Values Remarks

1 - 75 (Panel/Panel Lite)
Member Number Member Number Member Number
1 - 255 (Panel200)

Door Number Door Number 1 - 255 Door Number

Door Name Door Name 30 alphanumeric characters Door Name

Level Level 1 - 32 Level

Applicable for Panel Lite

V2 only
0 : disabled
Entry Enable entry-enable Parameter should be blank
1 : enabled
for sequence =0 (i.e.,
Sequenced Route flag is
disabled

In seconds.

Applicable for Panel Lite

V2 only
Entry Route Timer entry-route-timer 1-65535
Parameter should be blank
for sequence =0 (i.e.,
Sequenced Route flag is
disabled)

Applicable for Panel Lite

V2 only

Entry Level Restriction entry-level-restriction 1 : Hard

Parameter should be blank
0 : Soft
for sequence =0 (i.e.,
Sequenced Route flag is
disabled)

Applicable for Panel Lite

V2 only

Perform Action on Entry entry-action 0 : On User Punch

Parameter should be blank
1 : On Timer Elapsed
for sequence =0 (i.e.,
Sequenced Route flag is
disabled)

Applicable for Panel Lite

V2 only

Exit Enable exit-enable 0 : disabled

Parameter should be blank
1 : enabled
for sequence =0 (i.e.,
Sequenced Route flag is
disabled

Applicable for Panel Lite

V2 only

Exit Route Timer exit-route-timer 1-65535 Parameter should be blank

for sequence =0 (i.e.,
Sequenced Route flag is
disabled

Matrix COSEC Web API User Guide 269

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

Field Name Tag Name Valid Values Remarks

Applicable for Panel Lite

V2 only

Exit Level Restriction exit-level-restriction 1 : Hard

Parameter should be blank
0 : Soft
for sequence =0 (i.e.,
Sequenced Route flag is
disabled

Applicable for Panel Lite

V2 only

Perform Action on Exit exit-action 0 : On User Punch

Parameter should be blank
1 : On Timer Elapsed
for sequence =0 (i.e.,
Sequenced Route flag is
disabled

Example

Sample Request:

http://192.168.104.12/cosec/api.svc/v2/accessroutedetails?action=get;type=panel;route=1;panelno=4

Sample Response:

AccessRouteID|MemberNumber|DoorNumber|DoorName|Level
1|1|6|PVR as Panel door|1
1|2|7|Door V3 as Panel Door|2
<EOT>

270 Matrix COSEC Web API User Guide

CHAPTER 10 Cafeteria Management

The following APIs enable the user to perform actions related to Cafeteria Management -

• Getting Account Details

• Getting Expenditure Summary

• Getting Menu Details

• Getting List of Cafeteria Devices

• Getting Menu Schedules

• Getting Correction Application Details

• Making a Correction Application

• Updating a Correction Application

• Deleting a Correction Application

• Getting Expenditure Details

Matrix COSEC Web API User Guide 271

Getting Account Details

This can be used to fetch a specific user’s Cafeteria account details.

Action

action=get

Syntax

http://<servername>/api.svc/v2/canteen-account-details?action=get;<argument>=<value>...

User Rights

User Rights

System Account Enabled.

Enabled.

ESS The user must have rights on the following ESS pages:

ESS > Cafeteria > Account Details

Parameters

Table: Getting Cafeteria Account Details - Parameters

Argument Valid Values Mandatory Default Value Description

Multiple IDs can be selected, each

15 alphanumeric separated by “, (coma)” e.g.:”1, 3, 7,
Char. (for user) 9…”
A to Z
userid Yes -
a to z In case userid is provided along with id/
0 to 9 id & range, priority should always be
/_\\.@: given to userid . Value of id/id & range
to be ignored in that case.

All In this argument only single value

Organization should be allowed.
Branch
Department If argument range's value is specified
Designation as "All", ids of all the users that login
Section User (If argument user has rights over will return.
Range No
Category Range is not specified)
Grade In case user-id /user-id & user-filter are
User provided along with id/id & range,
Custom-group-1 priority should always be given to user-
Custom-group-2 id / user-id & user-filter. Value of id/id &
custom-group-3 range to be ignored in that case.

272 Matrix COSEC Web API User Guide

Table: Getting Cafeteria Account Details - Parameters

Argument Valid Values Mandatory Default Value Description

If argument range is not mentioned and

individual argument ID is specified,
1 to 999999 (for all the
then User id should be considered.
ranges except all &
user)
Argument ID can have multiple ids as
value separated with comma. For
Max 15 alphanumeric
ID No - example Id=1,2,…..999
characters (for user)
A to Z
In case user-id /user-id & user-filter are
a to z
provided along with id/id & range,
0 to 9
priority should always be given to user-
/_\\.@:
id / user-id & user-filter. Value of id/id &
range to be ignored in that case.

For this API, apply the following credentials in request header to authenticate response for the mentioned
User ID, irrespective of role rights/user rights:

username : MatrixAdmin
password : admin

Response Fields

Table: Getting Cafeteria Account Details - Response Fields

Field Name Tag Name Valid Values Remarks

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

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

max 15 alphanumeric
Short Name short-name -
characters

0 : Prepaid
Account Type account-type As set by admin
1: Postpaid

0: Disabled
Status status -
1: Enabled

0 : none
1: discount level 1
Discount Level discount 2: discount level 2 -
3: discount level 3
4: discount level 4

If the user is blocked for

0 : not blocked Cafeteria application by
User Blocked for E-canteen blocked
1 : blocked the system, return
blocked = 1.

Matrix COSEC Web API User Guide 273

Table: Getting Cafeteria Account Details - Response Fields

Field Name Tag Name Valid Values Remarks

Prepaid Account balance.

Account Balance balance 0.1 – 99999.9 Return blank if balance is
not applicable.

Return blank if recharge

Amount previous-recharge-amount 0.1 – 99999.9
details are not available.

Previous Recharge
Details:
Recharged on previous-recharge-date mm/dd/yyyy
Return blank if recharge
details are not available.

Post Paid Account: Max

usage limit
Max usage limit max-limit 0.1 – 999999.9
Return blank if value is
not available.

Usage Details: Current

Month
Current Month current-usage 0.1 – 999999.9
Return blank if value is
not available.

Carry over due

Carry over due carry-over 0.1 – 999999.9 Return blank if value is
not available.

Allowed usage
Allowed usage allowed-usage 0.1 – 999999.9 Return blank if value is
not available.

Total
Total total-usage 0.1 – 999999.9 Return blank if value is
not available.

Previous Payment
details: Amount
Amount previous-amount 0.1 – 999999.9
Return blank if value is
not available.

Previous Payment
details: Payment on
Payment on previous-payment-date mm/dd/yyyy (Date)
Return blank if value is
not available.

Example

Sample Request:

http://matrixserver/api.svc/v2/canteen-account-details?action=get;userid=1234,100

274 Matrix COSEC Web API User Guide

Getting Expenditure Summary

Use this to fetch the cafeteria expenditure summary for a specific user.

Action

action=get

Syntax

http://<servername>/api.svc/v2/canteen-expenditure-summary?action=get;<argument>=<value>...

User Rights

User Rights

Enabled.

System Account The user must have rights on the following pages (COSEC Web Application):

Cafeteria Management > Transaction Management > Transaction Summary

Enabled.

ESS The user must have rights on the following ESS pages:

ESS > Cafeteria > Expenditure Summary

Parameters

Table: Getting Cafeteria Expenditure Summary - Parameters

Argument Valid Values Mandatory Default Value Description

15 alphanumeric Multiple IDs can be selected, each

Char. (for user) separated by “, (coma)” e.g.:”1, 3, 7,
9…”
A to Z
Userid Yes -
a to z In case userid is provided along with id/
id & range, priority should always be
0 to 9 given to userid. Value of id/id & range to
/_\\.@: be ignored in that case.

Expenditure for current The period for which the expense

date-range ddmmyyyy-ddmmyyyy No
date details need to be fetched.

All In this argument only single value

Organization should be allowed.
Branch
Department If argument range's value is specified
Designation as "All", ids of all the users that login
Section User (If argument user has rights over will return
Range No
Category Range is not specified)
Grade In case user-id /user-id & user-filter are
User provided along with id/id & range,
Custom-group-1 priority should always be given to user-
Custom-group-2 id / user-id & user-filter. Value of id/id &
custom-group-3 range to be ignored in that case.

Matrix COSEC Web API User Guide 275

Table: Getting Cafeteria Expenditure Summary - Parameters

Argument Valid Values Mandatory Default Value Description

If argument range is not mentioned and

1 to 999999 (for all the individual argument ID is specified,
ranges except all & then id should be considered of User.
user)
Max 15 alphanumeric Argument ID can have multiple ids as
ID characters (for user) No - value with comma separated. For
A to Z example Id=1,2,…..999.
a to z
0 to 9 If argument range is not mentioned and
/_\\.@: individual argument ID has specified,
then User id should be considered.

Response Fields

Table: Getting Cafeteria Expenditure Summary - Response Fields

Field Name Tag Name Valid Values Remarks

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

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

max 15 alphanumeric
Short Name short-name -
characters

Expense date date mm/dd/yyyy -

Amount spent on that

Total Amount total-amount 0.0 – 999999.9
particular date based

Total Discount Amount

Total Discount total-discount 0.0 – 999999.9
applicable for the user

Expense =
Amount spent – discount.

Total Expenditure total-expense 0.0 – 999999.9 This is the total payable

amount after deducting
discount from the actual
expenditure

276 Matrix COSEC Web API User Guide

Getting Menu Details

This can be used to fetch the details of a Cafeteria menu as configured on the COSEC server.

Action

action=get

Syntax

http://<servername>/api.svc/v2/canteen-menus?action=get;<argument>=<value>...

User Rights

User Rights

Enabled.

System Account The user must have rights on the following pages (COSEC Web Application):

Cafeteria Management > Menu

Enabled.

ESS The user must have rights on the following ESS pages:

ESS > Cafeteria > Menu

Parameters

Table: Getting Menu Details - Parameters

Argument Valid Values Mandatory Default Value Description

This is the Menu ID.

All menus configured
id 1 to 999 No Multiple IDs can be selected, each
on COSEC.
separated by “, (coma)” e.g.:”1, 3, 7,
9…”

Response Fields

Table: Getting Menu Details - Response Fields

Field Name Tag Name Valid Values Remarks

Menu ID menu-id 1-999 -

15 alpha-numeric characters
Menu Name menu-name -
and space

0 : Inactive
Active active -
1: Active

If contains-default =1, the

item with sequence
0 : No
Contains Default Item default-item number = 1 will be the
1 : Yes
default item for that
menu.

Item ID item-id 1-999 -

Matrix COSEC Web API User Guide 277

Table: Getting Menu Details - Response Fields

Field Name Tag Name Valid Values Remarks

9 alpha-numeric characters and

Item Name item-name -
space

The order of items in the

Menu. Two items cannot
Item Sequence sequence-number 1-99
have same sequence
number.

Price item-price 0 - 6553.5 -

Discount is applicable or
0 : Discount not applicable not.
Apply Discount discount
1: discount applicable Consider discount-level
only if apply-discount=1.

value = discounted price,

Discount Level 1 discount1 0 - 6553.5 i.e. price – discount
amount

value = discounted price,

Discount Level 2 discount2 0 - 6553.5 i.e. price – discount
amount

value = discounted price,

Discount Level 3 discount3 0 - 6553.5 i.e. price – discount
amount

value = discounted price,

Discount Level 4 discount4 0 - 6553.5 i.e. price – discount
amount

Example

Sample Request:

http://matrixserver/api.svc/v2/canteen-menus?action=get;id=1,2,3

Sample Response:

menu-id|menu-name|active|default-item|item-id|item-name|sequence-number|item-price|discount|discount1|discount2|discount3|discount4
1|Lunch HO|1|1|1|Lunch|1|40.00|1|20.00|30.00|0.00|0.00
2|Breakfast|1|1|2|Breakfast|1|10.00|1|5.00|7.50|0.00|0.00
3|Lunch Factory|1|1|3|Lunch Fac|1|38.00|1|28.50|19.00|0.00|0.00
<EOT>

278 Matrix COSEC Web API User Guide

Getting List of Cafeteria Devices

See “Getting a Device List” on page 20.

Matrix COSEC Web API User Guide 279

Getting Menu Schedules

This can be used to fetch the list of menus configured for the specified Cafeteria device.

Action

action=get

Syntax

http://<servername>/api.svc/v2/canteen-menus-schedule?action=get;<argument>=<value>...

User Rights

User Rights

Enabled.

System Account The user must have rights on the following pages (COSEC Web Application):

Cafeteria Management > Menus

Enabled.

ESS The user must have rights on the following ESS pages:

ESS > Cafeteria > Menu

Parameters

Table: Getting Menu Schedules - Parameters

Argument Valid Values Mandatory Default Value Description

This is the device identification number

for the device type. It should be up to 5
numeric digits (MID).

Note: This is applicable only for the

following doors:
Door V2
NGT
Wireless Direct Door
device-id 1 to 65535 Yes - Vega Controller
Door V3
Door FMX
ARC DC200
ARGO
ARGO FACE

Note: An ESS login user must be

assigned on the device for which ID is
specified.

3 = Door V2,
4 = NGT Direct Door,
5 = Wireless Direct
Door
device-type 9 = Vega Controller Yes - This is the type of device.
12 = Door V3
15 = Door FMX
20= ARGO
21= ARGO FACE

280 Matrix COSEC Web API User Guide

Response Fields

Table: Getting Menu Schedules - Response Fields

Field Name Tag Name Valid Values Remarks

Device ID device-id 1 to 65535 MID of the device

Allowed Characters
A-Z
Device Name device-name 30 characters a-z
0-9
-_. ()

Menu ID menu-code 1-999 -

15 alpha-numeric characters
Menu Name menu-name -
and space

0 : Inactive
Active active -
1: Active

1: Sunday
2: Monday Days for which the menu
3: Tuesday is enabled.
Days days 4: Wednesday Return days in comma-
5: Thursday separated format: i.e.
6: Friday days=1,3,5
7:Saturday

Menu availability start

Start-time start-time HH:MM time.
(24-hour format)

Menu availability end

End-time end-time HH:MM time.
(24-hour format)

Example

Sample Request:

http://matrixserver/api.svc/v2/canteen-menus-schedule?action=get;device-id=16;device-type=3

Matrix COSEC Web API User Guide 281

Getting Correction Application Details

A Correction Application is a formal request submitted by a Cafeteria user for manual correction in Cafeteria
transaction records. This may be required in case there are errors in transaction records such as false punches,
incorrect debit or credit etc.

A submitted correction application requires approval from the respective Reporting In-charges or an authorized
COSEC System Account user before the corrections are updated in the COSEC database. This API can be used to
get a list of correction applications submitted by users by specifying user IDs and a date-range.

Action

action=get

Syntax

http://<servername>/api.svc/v2/canteen-correction-application?action=get;<argument>=<value>...

User Rights

User Rights

Enabled.

System Account The user must have rights on the following pages (COSEC Web Application):

Cafeteria Management > Transaction Management > Manual Correction

Enabled.

ESS The user must have rights on the following ESS pages:

ESS > Cafeteria > Transaction Correction

Parameters

Table: Getting Correction Application Details - Parameters

Argument Valid Values Mandatory Default Value Description

System should allow user to select

15 alphanumeric multiple id, each separated by ",
Char. (for user) (comma)" e.g.:"1, 3, 7, 9…"
A to Z
Userid Yes -
a to z In case userid is provided along with id/
0 to 9 id & range, priority should always be
/_\\.@: given to userid. Value of id/id & range to
be ignored in that case.

All applications for The period for which the expense

date-range ddmmyyyy-ddmmyyyy No
current month details need to be fetched.

282 Matrix COSEC Web API User Guide

Table: Getting Correction Application Details - Parameters

Argument Valid Values Mandatory Default Value Description

All In this argument only single value

Organization should be allowed.
Branch
Department If argument range's value is specified
Designation as "All", ids of all the users that login
Section User (If argument user has rights over will return
Range No
Category Range is not specified)
Grade In case user-id /user-id & user-filter are
User provided along with id/id & range,
Custom-group-1 priority should always be given to user-
Custom-group-2 id / user-id & user-filter. Value of id/id &
custom-group-3 range to be ignored in that case.

If argument range is not mentioned and

individual argument ID has specified,
1 to 999999 (for all the
then User id should be considered.
ranges except all &
user)
Argument ID can have multiple ids as
value with comma separated.
Max 15 alphanumeric
ID No - For example Id=1,2,…..999.
characters (for user)
A to Z
In case user-id /user-id & user-filter are
a to z
provided along with id/id & range,
0 to 9
priority should always be given to user-
/_\\.@:
id / user-id & user-filter. Value of id/id &
range to be ignored in that case.

Response Fields

Table: Getting Correction Application Details - Response Fields

Field Name Tag Name Valid Values Remarks

Expense date date mm/dd/yyyy -

Expense time time HH:MM:SS 24-hour format

ID of device on which
POS Device ID device-id 1-65535 transaction occurred
(MID)

3 = Door V2,
4 = NGT Direct Door,
5 = Wireless Direct Door
9 = Vega Controller
Device Type device-type 12 = Door V3 -
15 = Door FMX
19 = Door V4
20 = ARGO
21 = ARGO FACE

Allowed Characters
A-Z
Device Name device-name 30 characters a-z
0-9
-_. ()

Allowed Characters
A-Z
User ID user-id 15 chars. a-z
0-9
/_\\.@:

Matrix COSEC Web API User Guide 283

Table: Getting Correction Application Details - Response Fields

Field Name Tag Name Valid Values Remarks

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

max 15 alphanumeric
Short Name short-name -
characters

Applied Date application-date mm/dd/yyyy -

Item ID item-id 1-999 -

9 alpha-numeric characters and

Item Name item-name -
space

Quantity old-quantity 0-9999 -

Payable old-payable 0.0 – 999999.9 -

New Quantity new-quantity 0-9999 -

New Payable amount new-payable 0.0 – 999999.9 -

Empty in case of pending

Verdict Date-time verdict-date mm/dd/yyyy HH:MM
approval

0: None
1: Pending
Status status -
2: Approved
3: Rejected

Allowed Characters
A-Z
Reason reason 100 characters a-z
0-9
_.,()[]:@!#$*+/\

Allowed Characters
A-Z
Remark remark 50 characters a-z
0-9
_.,()[]:@!#$*+/\

Response will contain records for only those devices on which the login user has rights assigned.

284 Matrix COSEC Web API User Guide

Making a Correction Application

This can be used to submit a new correction application.

Action

action=set

Syntax

http://<servername>/api.svc/v2/canteen-correction-application?action=set;<argument>=<value>...

User Rights

Same as “Getting Correction Application Details” on page 282

Parameters

Table: Making a Correction Application - Parameters

Argument Valid Values Mandatory Default Value Description

The login user must have appropriate

rights on this user to make the
application successfully.
userid 15 characters Yes -
If login user is System Account User,
the application will get auto-approved.

All applications for

date ddmmyyyy Yes The application date
current month

time HHMMSS Yes - 24-hours format

ID of device on which transaction

occurred (MID).
device-id 1-65535 Yes -
Note: Login user must have appropriate
rights on this device.

Valid values are :

3 = Door V2,
4 = NGT Direct Door,
5 = Wireless Direct Door
3,4,5,9,12,15,19, 20, 9 = Vega Controller
device-type Yes -
21 12 = Door V3
15 = Door FMX
19 = Door V4
20 = ARGO
21 = ARGO FACE

item-id 1-999 Yes - This is the item ID.

The new value for the quantity should

be mentioned here. The new quantity
quantity 0-9999 Yes -
should not be greater than or same as
existing quantity.

reason Varchar 100 No N/A The reason for application.

menu-code 1-999 Yes - This is the menu code.

Matrix COSEC Web API User Guide 285

 • The combination of userid, event date-time, device-id, device-type and item-id will uniquely identify
a transaction, and its corresponding application, if any.

• Correction application on a particular event will be allowed only when there is application for that
event.

286 Matrix COSEC Web API User Guide

Updating a Correction Application

Use this to update any existing Correction Application on the COSEC Database.

Action

action=update

Syntax

http://<servername>/api.svc/v2/canteen-correction-application?action=update;<argument>=<value>...

User Rights

Same as “Getting Correction Application Details” on page 282

User rights are disabled for System Account Users for this action.

Parameters

Table: Updating a Correction Application - Parameters

Argument Valid Values Mandatory Default Value Description

The login user must have appropriate

userid 15 characters Yes - rights on this user to update the
application successfully.

date ddmmyyyy Yes - The application date

time HHMMSS Yes - 24-hours format

ID of device on which transaction

device-id 1-65535 Yes -
occurred (MID)

Valid values are :

3 = Door V2,
4 = NGT Direct Door,
5 = Wireless Direct Door
3,4,5,9,12,15,19, 20, 9 = Vega Controller
device-type Yes -
21 12 = Door V3
15 = Door FMX
19 = Door V4
20 = ARGO
21 = ARGO FACE

item-id 1-999 Yes - This is the item ID.

The new value for the quantity should

be mentioned here. The new quantity
quantity 0-9999 No Existing value
should not be greater than or same as
existing quantity.

reason Varchar 100 No N/A The reason for application.

menu-code 1-999 No N\A This is the menu code.

Note: Canteen Correction Application API with action=update will only be applied for transactions that are being generated via device.

Application once approved will not be applicable for updating.

Matrix COSEC Web API User Guide 287

Deleting a Correction Application

Use this to delete existing Correction Applications from the COSEC database.

Action

action=delete

Syntax

http://<servername>/api.svc/v2/canteen-correction-application?action=delete;<argument>=<value>...

User Rights

Same as “Getting Correction Application Details” on page 282

Parameters

Table: Deleting a Correction Application - Parameters

Argument Valid Values Mandatory Default Value Description

The login user must have appropriate

userid 15 characters Yes - rights on this user to delete the
application successfully.

date ddmmyyyy Yes - The application date

time HHMMSS Yes - 24-hours format

ID of device on which transaction

device-id 1-65535 Yes -
occurred (MID)

Valid values are :

3 = Door V2,
4 = NGT Direct Door,
5 = Wireless Direct Door
3,4,5,9,12,15,19, 20, 9 = Vega Controller
device-type Yes -
21 12 = Door V3
15 = Door FMX
19 = Door V4
20 = ARGO
21 = ARGO FACE

item-id 1-999 Yes - This is the item ID.

288 Matrix COSEC Web API User Guide

Getting Expenditure Details

This can be used to get a user’s item-wise cafeteria expenditure details.

Action

action=get

Syntax

http://<servername>/api.svc/v2/canteen-expenditure-details?action=get;<argument>=<value>…

User Rights

User Rights

Enabled.

System Account The user must have rights on the following pages (COSEC Web Application):

Cafeteria Management > Transaction Management > Transaction Summary

Enabled.

ESS The user must have rights on the following ESS pages:

ESS > Cafeteria > Expenditure Summary

Parameters

Table: Getting e-Canteen Expenditure Details - Parameters

Argument Valid Values Mandatory Default Value Description

The login user must have appropriate

15 alphanumeric rights on this user to make the request
Char. (for user) successfully.
A to Z
Userid Yes -
a to z In case userid is provided along with id/
0 to 9 id & range, priority should always be
/_\\.@: given to userid. Value of id/id & range to
be ignored in that case.

Expenditure for the The date for which the expense details
date ddmmyyyy No
current date. need to be fetched.

All In this argument only single value

Organization should be allowed.
Branch
Department If argument range's value is specified
Designation as "All", ids of all the users that login
Section User (If argument user has rights over will return.
Range No
Category Range is not specified)
Grade In case user-id /user-id & user-filter are
User provided along with id/id & range,
Custom-group-1 priority should always be given to user-
Custom-group-2 id / user-id & user-filter. Value of id/id &
custom-group-3 range to be ignored in that case.

Matrix COSEC Web API User Guide 289

Table: Getting e-Canteen Expenditure Details - Parameters

Argument Valid Values Mandatory Default Value Description

If argument range is not mentioned and

individual argument ID is specified,
1 to 999999 (for all the then id should be considered of User.
ranges except all &
user) Argument ID can have multiple ids as
Max 15 alphanumeric value with comma separated. For
ID characters (for user) No - example Id=1,2,…..999
A to Z
a to z In case user-id /user-id & user-filter are
0 to 9 provided along with id/id & range,
/_\\.@: priority should always be given to user-
id / user-id & user-filter. Value of id/id &
range to be ignored in that case.

Response Fields

Table: Getting e-Canteen Expenditure Details - Response Fields

Field Name Tag Name Valid Values Remarks

Allowed Characters
A-Z
User ID user-id 15 chars. a-z
0-9
/_\\.@:

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

max 15 alphanumeric
Short Name short-name -
characters

Expense date date mm/dd/yyyy -

Expense time time HH:MM:SS 24-hour format

ID of device on which
POS Device ID device-id 1-65535 transaction occurred
(MID)

Device Name device-name 40 characters -

3 = Door V2,
4 = NGT Direct Door,
5 = Wireless Direct Door
9 = Vega Controller
Device Type device-type 12 = Door V3 -
15 = Door FMX
19 = Door V4
20 = ARGO
21 = ARGO FACE

Item ID item-id 1-999 -

9 alpha-numeric characters and

Item Name item-name -
space

Price/Item price 0 – 6553.5 Price per Item

Quantity quantity 0-99 -

Discount discount 0 – 6553.5 Discount Amount

290 Matrix COSEC Web API User Guide

Table: Getting e-Canteen Expenditure Details - Response Fields

Field Name Tag Name Valid Values Remarks

Payable =
Payable payable 0.0– 999999.9 (price*quantity) –
(discount*quantity)

0: None
1: Pending
Event Status status -
2: Approved
3: Rejected

Example

Sample Request:

http://matrixserver/api.svc/v2/canteen-expenditure-details?action=get;userid=1234;date=01012014

Matrix COSEC Web API User Guide 291

292 Matrix COSEC Web API User Guide
CHAPTER 11 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 293

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

http://<servername>/api.svc/v2/template-list?action=get;<argument>=<value>...

User Rights

User Rights

System Account Enabled

ESS Enabled if user has ESS rights enabled.

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
5: user-details

View-ID view-id 101 - 999 -

Example

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

294 Matrix COSEC Web API User Guide

Sample Request:

http://matrixserver/api.svc/v2/template-list?action=get;template-type=0

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:

http://matrixserver/api.svc/v2/template-list?action=get;template-type=1

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 295

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

http://<servername>/api.svc/v2/template-details?action=get;<argument>=<value>...

User Rights

Same as “Getting Export Template List” on page 294.

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

296 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

http://<servername>/api.svc/v2/import-template-list?action=get;<argument>=<value>...

User Rights

User Rights

System Account Enabled.

ESS Enabled.

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:

http://matrixserver/api.svc/v2/import-template-list?action=get

Sample Response:

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

Matrix COSEC Web API User Guide 297

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.

1- User master table

2- Event table
3- User_Shift Table

Action

action=get

Syntax

http://<servername>/api.svc/v2/import-template-details?action=get;<argument>=<value>...

User Rights

Same as “Getting Import Template List” on page 297.

Parameters

Table: Getting Import Template Details - Parameters

Argument Valid Values Mandatory Default Value Description

1 to 3

1=user template
schema
id No all This is the template id.
2=event template
schema
3=user_shift 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

298 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

http://<servername>/api.svc/v2/template-data?action=get;<argument>=<value>...

User Rights

Same as “Getting Export Template List” on page 294.

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 Yes
should be : except for
date-range ddmmyyyy – templates of - Note: For User-Defined templates use
ddmmmyyyy user-details the “Template-List” API to get the
For a monthly template view 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 15 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 mentioned
below should not be considered.

Matrix COSEC Web API User Guide 299

Table: Getting Template Data - Parameters

Argument Valid Values Mandatory Default Value Description

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

specified enterprise group, each
designation 1 to 999999
No - separated by a ‘comma’.
section e.g.:”1, 3, 7, 9…”

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

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.

Index indicates the start point of an

event.
numeric(18 digits) 1-
index No - Note: This field is to be considered only
999999999999999999
if supplied template is of Attendance
Events OR Access Control Events
type.

It is the count upto which the data is

required.

count numeric (1 - 999) No - Note: This field is to be considered only

if supplied template is of Attendance
Events OR Access Control Events
type.

0: display name (As

per export template
If parameter is not mentioned the
config) No
return-field-name - response will be as per existing system
1: actual field (As per
(i.e. 0 = display name)
view column)
2: both

ddmmyyyyHHMMSS This parameter is applicable for User

last-run-time No -
Details View only

Custom-group-1 1 to 999999 No - Data for the users belonging to the

specified enterprise group and sub-
No groups (if mentioned) will be displayed.
Custom-group-2 1 to 999999 -

Multiple IDs can be selected for the

specified enterprise group, each
separated by a ‘comma’.
e.g.:”1, 3, 7, 9…”
Custom-group-3 1 to 999999 No -

Note: These parameters should not be

mentioned if userid is mentioned.

300 Matrix COSEC Web API User Guide

Table: Getting Template Data - Parameters

Argument Valid Values Mandatory Default Value Description

Return users as per their active flag

status.

For following Views, if not mentioned,

consider '1' as default.
i.Mx_VEW_APIDailyAttendance
ii.Mx_VEW_APIMonthlyAtdSumry
iii.Mx_VEW_APIUserAccessCtrlEvts
iv.
Mx_VEW_APIUserAttendanceEvents
v.Mx_VEW_DailyAtdTemplate1
0 : inactive vi.Mx_VEW_DailyAttendance
Active
1: active No 1 or 2 vii.Mx_VEW_MonthlyAtdSummary
2:all viii.Mx_VEW_MonthlyJobSummary
ix.Mx_VEW_USerAccessCtrlEvts
x.Mx_VEW_USerAttendanceEvents

For following Views, if not mentioned,

consider '2' as default :
i.Mx_VEW_UserDetails
ii.Mx_VEW_DailyCnteenEvts
iii.Mx_VEW_FirstAndLastAtdEvts
iv.Mx_VEW_MnthlyCnteenEvts

0
0 = Process Date If parameter is not
filter-date-by 1 = Process Date No mentioned the
Updated response will be as per
existing system.

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 15 characters a-z
0-9
/_\\.@:

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

Process Date Updated PROCESSDATE_U mm/dd/yy HH:MM:SS

Fields fields - field-name: value pairs

Matrix COSEC Web API User Guide 301

Table: Getting Template Data - Response Fields

Field Name Tag Name Valid Values Remarks

For Panels :0
1-255 (device-type = 8) For Direct Doors :1
Door ID for Punch1 DID1
0-99 (All Others) For Panel Doors :As
configured

Master Controller ID for 5 numeric digits

MID1 Device mid
Punch1 1-65535

This specifies the device

type, as set in cosec.

0 =Panel,
1 =Direct Door,
2 =Panel Lite
3 =Direct Door V2,
4 =NGT Direct Door,
5 =Wireless Direct Door
6 =Compact Direct Door
7 =PVR Direct Door
Device Type for Punch1 DTYPE1 2 numeric digits
8 =Panel-lite V2
9 =Vega Controller
11 =Arc Controller
12 =Door V3
15 =Door FMX
16 =Path V2
18 =MODE
19 =Door V4
17 =ARC DC 200
20 =ARGO
21 =ARGO FACE

For Panels :0
1-255 (device-type = 8) For Direct Doors :1
Door ID for Punch2 DID2
0-99 (All Others) For Panel Doors :As
configured

Master Controller ID for 5 numeric digits

MID2 Device mid
Punch2 1-65535

This specifies the device

type, as set in cosec.

0 =Panel,
1 =Direct Door,
2 =Panel Lite
3 =Direct Door V2,
4 =NGT Direct Door,
5 =Wireless Direct Door
6 =Compact Direct Door
7 =PVR Direct Door
Device Type for Punch2 DTYPE2 2 numeric digits
8 =Panel-lite V2
9 =Vega Controller
11 =Arc Controller
12 =Door V3
15 =Door FMX
16 =Path V2
18 =MODE
19 =Door V4
17 =ARC DC 200
20 =ARGO
21 =ARGO FACE

For Panels :0
1-255 (device-type = 8) For Direct Doors :1
Door ID for Punch3 DID3
0-99 (All Others) For Panel Doors :As
configured

302 Matrix COSEC Web API User Guide

Table: Getting Template Data - Response Fields

Field Name Tag Name Valid Values Remarks

Master Controller ID for 5 numeric digits

MID3 Device mid
Punch3 1-65535

This specifies the device

type, as set in cosec.

0 =Panel,
1 =Direct Door,
2 =Panel Lite
3 =Direct Door V2,
4 =NGT Direct Door,
5 =Wireless Direct Door
6 =Compact Direct Door
7 =PVR Direct Door
Device Type for Punch3 DTYPE3 2 numeric digits
8 =Panel-lite V2
9 =Vega Controller
11 =Arc Controller
12 =Door V3
15 =Door FMX
16 =Path V2
18 =MODE
19 =Door V4
17 =ARC DC 200
20 =ARGO
21 =ARGO FACE

For Panels :0
1-255 (device-type = 8) For Direct Doors :1
Door ID for Punch4 DID4
0-99 (All Others) For Panel Doors :As
configured

Master Controller ID for 5 numeric digits

MID4 Device mid
Punch4 1-65535

This specifies the device

type, as set in cosec.

0 =Panel,
1 =Direct Door,
2 =Panel Lite
3 =Direct Door V2,
4 =NGT Direct Door,
5 =Wireless Direct Door
6 =Compact Direct Door
7 =PVR Direct Door
Device Type for Punch4 DTYPE4 2 numeric digits
8 =Panel-lite V2
9 =Vega Controller
11 =Arc Controller
12 =Door V3
15 =Door FMX
16 =Path V2
18 =MODE
19 =Door V4
17 =ARC DC 200
20 =ARGO
21 =ARGO FACE

For Panels :0
1-255 (device-type = 8) For Direct Doors :1
Door ID for Punch5 DID5
0-99 (All Others) For Panel Doors :As
configured

Master Controller ID for 5 numeric digits

MID5 Device mid
Punch5 1-65535

Matrix COSEC Web API User Guide 303

Table: Getting Template Data - Response Fields

Field Name Tag Name Valid Values Remarks

This specifies the device

type, as set in cosec.

0 =Panel,
1 =Direct Door,
2 =Panel Lite
3 =Direct Door V2,
4 =NGT Direct Door,
5 =Wireless Direct Door
6 =Compact Direct Door
7 =PVR Direct Door
Device Type for Punch5 DTYPE5 2 numeric digits
8 =Panel-lite V2
9 =Vega Controller
11 =Arc Controller
12 =Door V3
15 =Door FMX
16 =Path V2
18 =MODE
19 =Door V4
17 =ARC DC 200
20 =ARGO
21 =ARGO FACE

For Panels :0
1-255 (device-type = 8) For Direct Doors :1
Door ID for Punch6 DID6
0-99 (All Others) For Panel Doors :As
configured

Master Controller ID for 5 numeric digits

MID6 Device mid
Punch6 1-65535

This specifies the device

type, as set in cosec.

0 =Panel,
1 =Direct Door,
2 =Panel Lite
3 =Direct Door V2,
4 =NGT Direct Door,
5 =Wireless Direct Door
6 =Compact Direct Door
7 =PVR Direct Door
Device Type for Punch6 DTYPE6 2 numeric digits
8 =Panel-lite V2
9 =Vega Controller
11 =Arc Controller
12 =Door V3
15 =Door FMX
16 =Path V2
18 =MODE
19 =Door V4
17 =ARC DC 200
20 =ARGO
21 =ARGO FACE

For Panels :0
1-255 (device-type = 8) For Direct Doors :1
Door ID for Punch7 DID7
0-99 (All Others) For Panel Doors :As
configured

Master Controller ID for 5 numeric digits

MID7 Device mid
Punch7 1-65535

304 Matrix COSEC Web API User Guide

Table: Getting Template Data - Response Fields

Field Name Tag Name Valid Values Remarks

This specifies the device

type, as set in cosec.

0 =Panel,
1 =Direct Door,
2 =Panel Lite
3 =Direct Door V2,
4 =NGT Direct Door,
5 =Wireless Direct Door
6 =Compact Direct Door
Device Type for Punch7 DTYPE7 2 numeric digits 7 =PVR Direct Door
8 =Panel-lite V2
9 =Vega Controller
11 =Arc Controller
12 =Door V3
15 =Door FMX
16 =Path V2
18 =MODE
19 =Door V4
17 =ARC DC 200
20 =ARGO
21 =ARGO FACE

1-255 (device-type = 8) For Panels :0

0-99 (All Others) For Direct Doors :1
Door ID for Punch8 DID8
For Panel Doors :As
configured

Master Controller ID for 5 numeric digits Device mid

MID8
Punch8 1-65535

This specifies the device

type, as set in cosec.

0 =Panel,
1 =Direct Door,
2 =Panel Lite
3 =Direct Door V2,
4 =NGT Direct Door,
5 =Wireless Direct Door
6 =Compact Direct Door
7 =PVR Direct Door
Device Type for Punch8 DTYPE8
2 numeric digits 8 =Panel-lite V2
9 =Vega Controller
11 =Arc Controller
12 =Door V3
15 =Door FMX
16 =Path V2
18 =MODE
19 =Door V4
17 =ARC DC 200
20 =ARGO
21 =ARGO FACE

1-255 (device-type = 8) For Panels :0

0-99 (All Others) For Direct Doors :1
Door ID for Punch9 DID9
For Panel Doors :As
configured

Master Controller ID for 5 numeric digits Device mid

MID9
Punch9 1-65535

Matrix COSEC Web API User Guide 305

Table: Getting Template Data - Response Fields

Field Name Tag Name Valid Values Remarks

This specifies the device

type, as set in cosec.

0 =Panel,
1 =Direct Door,
2 =Panel Lite
3 =Direct Door V2,
4 =NGT Direct Door,
5 =Wireless Direct Door
6 =Compact Direct Door
2 numeric digits 7 =PVR Direct Door
Device Type for Punch9 DTYPE9
8 =Panel-lite V2
9 =Vega Controller
11 =Arc Controller
12 =Door V3
15 =Door FMX
16 =Path V2
18 =MODE
19 =Door V4
17 =ARC DC 200
20 =ARGO
21 =ARGO FACE

1-255 (device-type = 8) For Panels :0

0-99 (All Others) For Direct Doors :1
Door ID for Punch10 DID10
For Panel Doors :As
configured

Master Controller ID for 5 numeric digits Device mid

MID10
Punch10 1-65535

This specifies the device

type, as set in cosec.

0 =Panel,
1 =Direct Door,
2 =Panel Lite
3 =Direct Door V2,
4 =NGT Direct Door,
5 =Wireless Direct Door
6 =Compact Direct Door
7 =PVR Direct Door
Device Type for Punch10 DTYPE10
2 numeric digits 8 =Panel-lite V2
9 =Vega Controller
11 =Arc Controller
12 =Door V3
15 =Door FMX
16 =Path V2
18 =MODE
19 =Door V4
17 =ARC DC 200
20 =ARGO
21 =ARGO FACE

1-255 (device-type = 8) For Panels :0

0-99 (All Others) For Direct Doors :1
Door ID for Punch11 DID11
For Panel Doors :As
configured

Master Controller ID for 5 numeric digits Device mid

MID11
Punch11 1-65535

306 Matrix COSEC Web API User Guide

Table: Getting Template Data - Response Fields

Field Name Tag Name Valid Values Remarks

This specifies the device

type, as set in cosec.

0 =Panel,
1 =Direct Door,
2 =Panel Lite
3 =Direct Door V2,
4 =NGT Direct Door,
5 =Wireless Direct Door
6 =Compact Direct Door
2 numeric digits 7 =PVR Direct Door
Device Type for Punch11 DTYPE11
8 =Panel-lite V2
9 =Vega Controller
11 =Arc Controller
12 =Door V3
15 =Door FMX
16 =Path V2
18 =MODE
19 =Door V4
17 =ARC DC 200
20 =ARGO
21 =ARGO FACE

1-255 (device-type = 8) For Panels :0

0-99 (All Others) For Direct Doors :1
Door ID for Punch12 DID12
For Panel Doors :As
configured

Master Controller ID for 5 numeric digits Device mid

MID12
Punch12 1-65535

This specifies the device

type, as set in cosec.

0 =Panel,
1 =Direct Door,
2 =Panel Lite
3 =Direct Door V2,
4 =NGT Direct Door,
5 =Wireless Direct Door
6 =Compact Direct Door
2 numeric digits 7 =PVR Direct Door
Device Type for Punch12 DTYPE12
8 =Panel-lite V2
9 =Vega Controller
11 =Arc Controller
12 =Door V3
15 =Door FMX
16 =Path V2
18 =MODE
19 =Door V4
17 =ARC DC 200
20 =ARGO
21 =ARGO FACE

Example

Sample Request:

http://matrixserver/api.svc/v2/template-data?action=get;id=1;date-range=11022013-12022013

Matrix COSEC Web API User Guide 307

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 08:28:00|11/02/2013 12:06:00|23|0|0|0|534
1|10|RAJENDRA GOSWAMI|10|RAJENDRA GOSWAMI|11/02/2013|11/02/2013 08:25:00|11/02/2013 12:50:00|23|0|0|0|492
1|1001|ANKITKUMAR SOHLIYA|1001|ANKITKUMAR SOHLIYA|11/02/2013|11/02/2013 09:29:00|11/02/2013 19:08:00|GS|0|0|0|529
1|1002|MEGHA H SHUKLA|1002|MEGHA H SHUKLA|11/02/2013|11/02/2013 14:08:00|11/02/2013 19:35:00|GS|0|0|0|327
1|1003|UMESH M TALANPURI|1003|UMESH M TALANPURI|11/02/2013|11/02/2013 09:20:00|11/02/2013 18:54:00|GS|0|0|0|524
1|1004|DARSHAK B PATEL|1004|DARSHAK B PATEL|11/02/2013|11/02/2013 09:07:00|11/02/2013 19:06:00|GS|0|0|0|549
1|1007|DHAVAL I PATEL|1007|DHAVAL I PATEL|11/02/2013|11/02/2013 09:25:00|11/02/2013 20:27:00|GS|0|0|0|612
1|1008|MAYANK K KORAT|1008|MAYANK K KORAT|11/02/2013|11/02/2013 09:01:00|11/02/2013 20:26:00|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 09:17:00|11/02/2013 19:23:00|GS|0|0|0|556
1|1011|PARIKA S PANDEY|1011|PARIKA S PANDEY|11/02/2013|11/02/2013 09:18:00|11/02/2013 18:58:00|GS|0|0|0|530
1|1012|PARIKSHIT DAS|1012|PARIKSHIT DAS|11/02/2013|11/02/2013 09:25:00|11/02/2013 20:24:00|GS|0|0|0|609
1|1015|SUMEDHA A GAWARIKAR|1015|SUMEDHA A GAWARIKAR|11/02/2013|11/02/2013 09:21:00|11/02/2013 19:32:00|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 08:25:00|12/02/2013 09:48:00|23|0|0|0|476
1|10|RAJENDRA GOSWAMI|10|RAJENDRA GOSWAMI|12/02/2013|12/02/2013 08:23:00|12/02/2013 12:55:00|23|0|0|0|495
1|1001|ANKITKUMAR SOHLIYA|1001|ANKITKUMAR SOHLIYA|12/02/2013|12/02/2013 09:24:00|12/02/2013 19:22:00|GS|0|0|0|548
1|1002|MEGHA H SHUKLA|1002|MEGHA H SHUKLA|12/02/2013|12/02/2013 09:27:00|12/02/2013 19:40:00|GS|0|0|0|563
1|1003|UMESH M TALANPURI|1003|UMESH M TALANPURI|12/02/2013|12/02/2013 09:15:00|12/02/2013 18:55:00|GS|0|0|0|530
1|1004|DARSHAK B PATEL|1004|DARSHAK B PATEL|12/02/2013|12/02/2013 09:24:00|12/02/2013 19:27:00|GS|0|0|0|553
1|1007|DHAVAL I PATEL|1007|DHAVAL I PATEL|12/02/2013|12/02/2013 09:23:00|12/02/2013 20:14:00|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 09:35:00|12/02/2013 19:46:00|GS|0|0|0|561
1|1011|PARIKA S PANDEY|1011|PARIKA S PANDEY|12/02/2013|12/02/2013 09:03:00|12/02/2013 18:51:00|GS|0|0|0|538
1|1012|PARIKSHIT DAS|1012|PARIKSHIT DAS|12/02/2013|12/02/2013 09:30:00|12/02/2013 19:11:00|GS|0|0|0|531
1|1015|SUMEDHA A GAWARIKAR|1015|SUMEDHA A GAWARIKAR|12/02/2013|12/02/2013 09:10:00|12/02/2013 19:04:00|GS|0|0|0|544
1|1016|BALAJI A|1016|BALAJI A|12/02/2013|||GN|0|0|0|0
<EOT>

308 Matrix COSEC Web API User Guide

CHAPTER 12 Data Transfer

The Data Transfer API enables the COSEC system to send a user’s image/finger print template/palm template/
medical certificate 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 or delete it.

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 (For finger-template-format = 0, 1) - 768 bytes
• FP Template (For finger-template-format=2) - 6 KB
• Palm template - 3 KB
• Medical Certificate - 500 KB
• Company Logo - 250 KB
• I-Card Authority Signature - 50 KB
• Visitor photo - 100 KB
• Visitor ID Proof - 100 KB
• Vehicle Photo - 100 KB
• Material Photo - 100 KB
• Enrolled Face - 50KB
• Driving license - 100 KB
• Passport no - 100 KB
• PAN - 100 KB
• Aadhar no - 100 KB
• PF no - 100 KB
• UAN - 100 KB
• ESI No - 100 KB
• Voter ID - 100 KB
• Visa No - 100 KB
• Field1 - 100 KB
• Field2 - 100 KB
• Field3 - 100 KB
• Field4 - 100 KB
• Service Tax No - 100 KB
• ESIC No - 100 KB
• License No - 100 KB
• Visitor Pass - 100 KB
• Group- FR - 15 MB
• Tour Document - 500 KB
• Modify Tour Document - 500 KB
• Capture Photo - 100 KB

Matrix COSEC Web API User Guide 309

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

Syntax

http://<servername>/api.svc/v2/datatransfer?action=<value>;<argument>=<value>...

User Rights

User Rights

System Account Enabled

Enabled.

For ESS Users, action= get/set/delete should be allowed only when type of data is ‘image’
or ‘medical certificate’ or icard authority signature(only get is allowed)
ESS
If ESS Login user attempts to fetch Face, return corresponding enrolled faces
If ESS Login user attempts to fetch or set FP/Palm template/, return invalid request
message.
If ESS Login user attempts to set Company logo/i-card issuing authority, return invalid
request message.

Visitor Enabled for All Registered Visitors with 'isVerified' flag = 1

COSEC supports the following data transfer APIs:

• Retrieving User Data

• Sending User Data

• Deleting User Data

310 Matrix COSEC Web API User Guide

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

http://<servername>/api.svc/v2/datatransfer?action=get;<argument>=<value>...

Parameters

Table: Retrieving User Data - Parameters

Argument Valid Values Mandatory Default Value Description

0 = Host User / SA
user-type User/ESS User/
No 0 Specifies the type of user.
Worker
1 = Visitor

Yes for type=

0/1/2/3/11/12/
13/14/15/16/
15 alphanumeric
17/18/19/20/
Char. (for user)
21/22/23/24/ The user identification number of the
A to Z
userid 25/26/27/28/ - user whose data is to be requested.
a to z
2931/32/33/
0 to 9
34/35/36/37/
/_\\.@:
38/39/40/41/
42/43/44/45/
46/49

Yes for type=

visitor-id 0-9 7/8/60/61/62/ - Specifies the ID of visitor.
63/64

0-9 Yes for type=

9/10/50/51/
appointment-no - -
12 Digits (Each 52/53/54/55/
Appointment No) 56/57/58/59

Matrix COSEC Web API User Guide 311

Table: Retrieving User Data - Parameters

Argument Valid Values Mandatory Default Value Description

0: image
1: finger print template
2: palm template
3: medical certificate
4: company logo
5: icard authority
signature
7: visitor photo
8: visitor id proof
9: vehicle photo
10: material photo
11:enrolled face
12: driving-license
13: passport-no
14: pan
15: aadhar-no
16: pf-no
17: uan
18: esi-no
19: voter-id
20: visa-no
21: field1
22: field2
23: field3
The type of data being requested must
24: field4
be specified.
25: service-tax-no
26: esic-no
27: contractor-license- Type=25/ 26/ 27/28/29/31/32/33/34/35/
no 36/37/38/39/40 is applicable only for
28: contractor-pf-no Contractor
29: contractor-pan-no
30: visitor-pass Type =
31: con-field1 12,13,14,15,16,17,18,19,20,21,22,23,2
32: con-field2 4,30,31,32,33,34,35,36,37,38,39,
type 33: con-field3 Yes - 40,41,42,43,44,45,46,47,50,51,52,53,5
34: con-field4 4,55,56,57,58,59,60,61,62,63,64 is
35: con-field5 valid for SA user.
36: con-field6
37: con-field7 If “Upload” provision is disabled for type
38: con-field8 =21,22,23,24,31,32,33,34,35,36,37,38,
39: con-field9 39, 40,41,42,43,44,45,46,
40: con-field10 50,51,52,53,54,55,56,57,58,59,60,61,6
41: field5
2,63,64,65 and user tries to GET
42: field6
uploaded file, if any file is present, then
43: field7
that uploaded file must be displayed.
44: field8
45: field9
46: field10
49: modify-medical
certificate
50: Visit Field1
51: Visit Field2
52: Visit Field3
53: Visit Field4
54: Visit Field5
55: Visit Field6
56: Visit Field7
57: Visit Field8
58: Visit Field9
59: Visit Field10
60: Visitor Field1
61: Visitor Field2
62: Visitor Field3
63: Visitor Field4
64: Visitor Field5
65: capture-photo
66: tour-document
67: modify-tour-doc

312 Matrix COSEC Web API User Guide

Table: Retrieving User Data - Parameters

Argument Valid Values Mandatory Default Value Description

0 : Suprema
Proprietary
Finger-template- 1: Suprema ISO
Yes for type=
format 2: Lumidigm ISO
1
3: Lumidigm
Proprietary

0-9 : if it is a palm
template.

0-9 : if it is a finger print

template.

0 - 1: if it is a visitor ID The position of the template that should

proof (ID Proof 1 & ID be returned.
Proof 2) By default the template
location No stored at location=0 Valid only for type =1 (FP templates),
0-5: if it is a vehicle will be sent. type =2 (Palm templates), type =7
photo (Photos: 1 to 6) (Visitor ID Proof), type = 8 (Vehicle
Photo) & type = 9 (Material Photo).
0-5: if it is a material
photo (Photos: 1 to 6)

0-39: if it is an enrolled
face

Yes if type=3, TID is mandatory if type=3, type=49,

max 10 numeric type=49, type=66, type=67. For others it will be
TID -
characters type=66, ignored.
type=67

Yes for Type

passTID 1-9999
= 30

faceupdatedtime will contain, the time

when enrolled faces of corresponding
faceupdatedtime ddmmyyyyHH:MM:SS No
userid was last fetched by the client
application.

eid is mandatory if type=65 and if

parameters Type, MID, Flash Count,
Roll Over Count, Event Sequence
eid 15 numeric characters Number are not mentioned.

For type!= 65, ignore eid.

dtype 2 numeric digits For type!= 65, ignore dtype.

mid 5 numeric digits For type!= 65, ignore mid.

flash_count 5 numeric digits For type!= 65, ignore flash_count

roll_over_count 5 numeric digits For type!= 65, ignore roll_over_count.

For type!= 65, ignore

event_sequence_no 7 numeric digits
event_sequence_no.

0= Old Format Applicable only when type=11.

get_updated_face 0= Old Format
1= New Format Should be ignored when type!=11

Matrix COSEC Web API User Guide 313

Table: Retrieving User Data - Parameters

Argument Valid Values Mandatory Default Value Description

Parameter is not applicable for Visitor

0= normal finger
For type = 1 and Finger-template-
(default)
duress 2 format = 0,1 should indicate whether it
1= duress finger
is the finger enrolled as Duress Finger
2= Any
or not.

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

• This API cannot be tested on a browser.

314 Matrix COSEC Web API User Guide

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

http://<servername>/api.svc/v2/datatransfer?action=set;<argument>=<value>...

Parameters

Table: Sending User Data - Parameters

Argument Valid Values Mandatory Default Value Description

0 = Host User / SA User / ESS

user-type User / Worker No 0 -
1 = Visitor

15 alphanumeric Char. (for

The user identification number of the
user)
user whose data is to be sent.
A to Z
userid Yes - User ID is mandatory only for type = 0/
a to z
1/2/3/12/13/14/15/16/17/18/19/20/21/
0 to 9
22/23/24/25/26/27/28/29.
/_\\.@:

Yes (Only for

visitor-id 0 to 9 type=7/8/60/ - -
61/62/63/64)

Yes (Only for

type=9/10/50/
0-9
51/52/53/54/
appointment-no 55/56/57/58/ - -
12 Digits (Each Appointment
59)
No)

Matrix COSEC Web API User Guide 315

Table: Sending User Data - Parameters

Argument Valid Values Mandatory Default Value Description

0: image
1: finger print template
2: palm template
3: medical certificate
4: company logo
5: icard authority signature
7: visitor photo
8: visitor id proof
9: vehicle photo
10: material photo
11:enrolled face
12: driving-license
13: passport-no
14: pan
15: aadhar-no
16: pf-no
17: uan
18: esi-no
19: voter-id
20: visa-no
The type of data being sent must be
21: field1
specified.
22: field2
23: field3
24: field4 Type =
25: service-tax-no 12,13,14,15,16,17,18,19,20,21,22,23,2
26: esic-no 4,41,42,43,44,45,46 is valid for ESS
27: contractor-license-no user/worker.
28: contractor-pf-no
29: contractor-pan-no Type=25/ 26/ 27/28/29 is applicable
30: visitor-pass only for Contractor
31: con-field1
32: con-field2 For successful image/pdf upload
33: con-field3 display message- File saved
type Yes -
34: con-field4 successfully
35: con-field5 For failure of upload of image/pdf
36: con-field6 display message- File not saved
37: con-field7
For any exception- Invalid File should
be displayed
38: con-field8
39: con-field9
Messages for image/pdf upload
40: con-field10
file deleted successfully.
41: field5
file not deleted.
42: field6
file not exist.
43: field7
Vehicle File is not available
44: field8 Material File is not available
45: field9
46: field10
48: grp-fr-pht
49: modify-medical certificate
50: Field1
51: Field2
52: Field3
53: Field4
54: Field5
55: Field6
56: Field7
57: Field8
58: Field9
59: Field10
60: Field1
61: Field2
62: Field3
63: Field4
64: Field5
65: Captured Photo
66: tour-document
67: modify-tour-doc

316 Matrix COSEC Web API User Guide

Table: Sending User Data - Parameters

Argument Valid Values Mandatory Default Value Description

0 : Suprema Proprietary
Finger-template- Yes (Only for
1: Suprema ISO
format type=1) Value should be ignored if type != 48
2: Lumidigm ISO
3: Lumidigm Proprietary

0-9 : if it is a palm template.

0-9 : if it is a finger print The position of the template / Visitor ID

template. Proof / Material Photo / Vehicle Photo/
Enrolled Face that should be set.
0 - 1: if it is a visitor ID proof (ID By default, the
Proof 1 & ID Proof 2) template will be Valid only for FP and Palm templates.
location No stored at the first
0-5: if it is a vehicle photo available (empty) Note: Location value entered will be
(Photos: 1 to 6) location for the ignored for both normal and duress
user. finger. The finger will be set at the next
0-5: if it is a material photo empty location if location value is
(Photos: 1 to 6) passed

0-29: if it is a enrolled face

Option to overwrite the template, if a

template already exists at the
mentioned position for the user.

If type=3, Always overwrite existing

medical certificate with new one.
0 : no
overwrite No 0 (no)
1 : yes Overwrite should be applicable for type
=
1,2,3,4,11,12,13,14,15,16,17,18,19,20,
21,22,23,24,25,26,27,28,29,31,32,33,3
4,35,36,37,38,39,40,41,42,43,44,45,46
,49,50,51,52,53,54,55,56,57,58,59,60,
61,62,63,64,65

Applicable only for type=0: image,

data-format 1 No 3: medical certificate, 49: Modify

Medical-certificate, 66: tour-document,
67: modify-tour-doc.

Yes if type=3,
TID is mandatory if type=3, type= 49,
type=49,
TID max 10 numeric characters type=66, type=67. For others it will be
type=66,
ignored.
type=67

Yes (when type= For type other than 48, should be

temporary-id max 10 numeric character Yes
48) ignored.

eid is mandatory if type=65. For type! =

eid 15 numeric characters
65 ignore eid.

Field value (file-type=1) should be sent

whenever any pdf file is uploaded.

0: image Field value (file-type=0) should be sent

filetype
1:pdf whenever any image file is uploaded.

If no value passed, by default consider

file-type=0

Parameter not applicable for visitor

0= normal finger (default) For type = 1 and Finger-template-
duress 1= duress finger 2 No format = 0,1 should indicate whether it
2= Any is the finger enrolled as Duress Finger
or not.

Matrix COSEC Web API User Guide 317

 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.

Supported data size limits for type= 48 is 15MB. Return image-id in response on successful API execution
if Type=48.

Below given table defines error codes for Enrolled faces SET and UPDATE request’s error codes and messages:

Validation Error Code SET/UPDATE Message

If user’s face is not detected 0280203008/0280303008 Face Not Detected

If user’s face is detected but with angel

0280203008/0280303008 Straight Face Not Detected
verification failing
0280203008/0280303008
If user’s face is detected with mask Face Not Visible
0280203005/0280303005
Size limit exceeded for the selected Image Maximum Allowed File Size is 15MB
Maximum {number} images are allowed
Space is not available 0280203005/0280303005
to be uploaded.
If Identification Service is not defined
0280203008/0280303008 Identification Service not defined
(blank) in Cosec Admin login
0280203008/0280303008
If Identification Service is not reachable Identification Service not reachable
0280203008/0280303008
If conflict is found User Conflict
When user tries to enroll on already enroll
0280203006/0280203006 Face already exists for this location
location with Overwrite =0

318 Matrix COSEC Web API User Guide

Deleting User Data

This API can be used by a third party application to delete a user’s image from the COSEC database.

Action

action=delete

Syntax

http://<servername>/api.svc/v2/datatransfer?action=delete;<argument>=<value>...

Parameters

Table: Deleting User Data - Parameters

Argument Valid Values Mandatory Default Value Description

user-type 0 = Host User / SA User

No 0 -
1 = Visitor

Matrix COSEC Web API User Guide 319

Table: Deleting User Data - Parameters

Argument Valid Values Mandatory Default Value Description

0: image
1: finger print template
2: palm template
3: medical certificate
4: company logo
5: icard authority signature
7: visitor photo
8: visitor id proof
9: vehicle photo
10: material photo
11:enrolled face
12: driving-license
13: passport-no
14: pan
15: aadhar-no
16: pf-no
17: uan
18: esi-no
19: voter-id
20: visa-no
21: field1
22: field2
23: field3
24: field4
25: service-tax-no
26: esic-no
27: contractor-license-no
28: contractor-pf-no
29: contractor-pan-no Type =
30: visitor-pass 12,13,14,15,16,17,18,19,20,21,22,23,2
31: con-field1 4,41,42,43,44,45,46 is valid for ESS
32: con-field2 user/worker.
Type 33: con-field3 Yes -
34: con-field4 Type=25/ 26/ 27/28/29 is applicable
35: con-field5 only for Contractor.
36: con-field6
37: con-field7
For SA login and Type=25/ 26/ 27/28/
29/ 31/32/33/34/35/36/37/38/39/40
38: con-field8
39: con-field9
40: con-field10
41: field5
42: field6
43: field7
44: field8
45: field9
46: field10
48: grp-fr-pht
49: modify-medical certificate
50: Field1
51: Field2
52: Field3
53: Field4
54: Field5
55: Field6
56: Field7
57: Field8
58: Field9
59: Field10
60: Field1
61: Field2
62: Field3
63: Field4
64: Field5
65: Captured Photo
66: tour-document
67: modify-tour-doc

320 Matrix COSEC Web API User Guide

Table: Deleting User Data - Parameters

Argument Valid Values Mandatory Default Value Description

0 - 9: if it is a palm template

0 - 9: if it is a finger print
template

0 - 1: if it is a visitor ID proof Valid only for type type =8 (Visitor ID

(ID Proof 1 & ID Proof 2) Proof), type = 9 (Vehicle Photo) & type
Location By default the template
= 10 (Material Photo)
No stored at location=0
0 - 5: if it is a vehicle photo The number of ID proof / Vehicle Photo
will be sent.
(Photos: 1 to 6) / Material Photo should be returned.

0 - 5: if it is a material photo
(Photos: 1 to 6)

0-39: if it is enrolled faces

15 alphanumeric Char. (for

user) Yes (when
A to Z type = 0,49 The user identification number of the
userid -
a to z and user- user whose image is to be deleted.
0 to 9 type=0)
/_\\.@:

Visitor ID is mandatory only when type

Yes (when = 7/8/50/51/52/53/54/55/56/57/58/59
type = 7/8 and user-type=1.
visitor-id 0-9 -
and user-
type=1) For type other than 7/8, should be
ignored.

Yes (when For type other than

0-9
type = 9,10,60,61,62,63,64, should be
appointment
9,10,60,61,62 ignored.
-no 12 Digits (Each Appointment
,63,64) For other types, appointment-no should
No)
be ignored.

TID is mandatory if type=3, 49, 66 or

TID max 10 numeric characters
67. For others it will be ignored.

Yes (when For type other than 48, should be

Image-id max 10 numeric characters
type= 48) ignored.

Yes (when For type other than 48, should be

temporary-id max 10 numeric characters
type= 48) ignored.

eid is mandatory if type=65. For type! =

eid 15 numeric characters
65 ignore eid.

Delete Command will be Applicable only to type = 0 (Image), 3 (Medical Certificate),7(visitor photo),
8(visitor id proof), 9(Vehicle Photo) & 10(Material Photo)./ 11 (Enrolled Face) / 12= driving-license/13=
passport-no/ 14=pan / 15=aadhar-no/ 16=pf-no / 17=uan / 18=esi-no /19=voter-id / 20=visa-no /21= field1 /
22= field2 / 23=field3 / 24=field4 /25= service-tax-no / 26=esic-no / 27=contractor-license-no/28=contrctor-
pf-no/29=contractor-pan-no/ 30: vistor-pass / 31: con-field1 / 32: con-field2 / 33: con-field3 / 34: con-field4 /
35: con-field5 / 36: con-field6 / 37: con-field7 / 38: con-field8 / 39: con-field9 / 40: con-field40 / 41: field5 /
42: field6 / 43: field7 / 44: field8 / 45: field9 / 46: field10/48:grp-fr-pht/49:Modify Medical-certificate.

Matrix COSEC Web API User Guide 321

322 Matrix COSEC Web API User Guide
CHAPTER 13 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

• Obtaining Visitor Events

Events arriving via Events API of COSEC v1 APIs, will not undergo Event authorization process. This feature is
applicable only for COSEC v2 APIs.

Matrix COSEC Web API User Guide 323

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

http://<servername>/api.svc/v2/events?action=set;<argument>=<value>...

User Rights

User Rights

System Account Enabled.

Enabled only if the following option is enabled in User Configuration (COSEC

Web Application):
ESS
Users > User Configuration > ESS tab > Settings sub-tab > Punch Marking Via
API

Parameters

Table: Adding an Event - Parameters

Argument Valid Values Mandatory Default Value Description

dd/mm/yyyy This is the date and time when the

event-datetime Yes -
HH:MM:SS format event actually happened.

This is the user id for the event. This

userid Varchar(15) 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 - 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. 100 characters - 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 - 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) - 1 (allowed)
value for the event.
1=allowed (event 101)

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

324 Matrix COSEC Web API User Guide

Table: Adding an Event - Parameters

Argument Valid Values Mandatory Default Value Description

This specifies the device ID (DID) as

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

This specifies the device type, as set in

COSEC.

0 = Panel
1 = Door V1
2 = Panel Lite
3 = Door V2
4 = NGT Direct Door
5 = Wireless Direct Door
6 = Path Controller
7 = PVR Direct Door
8 = Panel200
dtype Numeric (1,0) - 0
9 = Vega Controller
11 = ARC Controller
12 = Door V3
15 = Door FMX
18 = MODE
19 = Door V4
17 = ARC DC 200
20 = ARGO
21 = ARGO FACE

Enum-13 is reserved for COSEC

SAMAY Door V3.

Valid values 0,1

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

None = 0,
PIN = 1,
Card = 2,
Card_PIN = 3,
FingerPrint = 4,
Finger_PIN = 5,
Finger_Card = 6,
Finger_Card_PIN = 7,
This will specify the credentials used
credentials Palm = 8, - 0
for the event.
Palm_PIN = 9,
Palm_Card = 10,
Palm_Card_PIN = 11,
Palm_Group = 24
Face=64
PIN_Face =65
Card_Face=66
FINGER_Face=68

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

Matrix COSEC Web API User Guide 325

Table: Adding an Event - Parameters

Argument Valid Values Mandatory Default Value Description

When location is calculated via GPS.

This parameter will contain : latitude
Format : +XXX.XXXXXX or –
gps_latitude 11 characters No -
XXX.XXXXXX
Valid Values : -90.000000 to
+90.000000

When location is calculated via GPS.

This parameter will contain : longitude
Format : +XXX.XXXXXX or –
gps_longitude 11 characters No -
XXX.XXXXXX
Valid Values : -180.000000 to
+180.000000

When location is calculated via GSM.

This parameter will contain : latitude
Format : +XXX.XXXXXXor –
gsm_latitude 11 characters No -
XXX.XXXXXX
Valid Values : -90.000000 to
+90.000000

When location is calculated via GSM.

This parameter will contain : longitude
Format : +XXX.XXXXXX or –
gsm_longitude 11 characters No -
XXX.XXXXXX
Valid Values : -180.000000 to
+180.000000

When location is calculated via Wi-Fi.

This parameter will contain : MAC
Address of source
mac_address 17 characters No -
Each byte should be separated by
colon.
Format : XX:XX:XX:XX:XX:XX

To be sent by third party applications to

0 : Offline
online_status No 1 (Online) differentiate in online and offline
1 : Online
events.

50 characters

0-9
comment A-Z - - -
a-z
!@$*()_-+[]\:,./
and space

0 = Job
Assignment
Type =
"Fixed" or
"None"
1-4294967292 = Job Reference ID
1-
corresponding to respective Job Codes
4294967294
10 characters = Job
4294967293 = Job Reference ID
Reference ID
JobID 0, - selected = Continue Job
correspondin
4294967295 g to
4294967294 = Job Reference ID
respective
selected = Default Job
Job Codes
4294967295
= Job
Reference ID
selected =
None

326 Matrix COSEC Web API User Guide

Table: Adding an Event - Parameters

Argument Valid Values Mandatory Default Value Description

ble_code 0 to 9999 No - -

Max. 10 alphanumeric
characters
ble_name A-Z No -
a-z
0-9

0: Manual Punch
1: Manual Punch-FR
2: Auto Punch To send events with the mode used for
app-event-mode No -
3: Auto Punch-FR registering punch using APTA
4: Auto Punch - Face
Scan Mode

Max 50 alphanumaric
characters.

A-Z
punch-reason a-z No - Reason for the marked Punch
0-9
_-
<space>
()[].,/\+!@$:#*

Fahrenheit: 90.0 -
temperature 110.0 No - -
Celsius: 32.0 – 43.0

0: Fahrenheit
temperature-unit No - -
1: Celsius

50 chars

A-Z
a-z This field indicates a precise street
formatted_address No -
0-9 address
!*@$()_-+[]:,./
<Space>

50 chars

A-Z
a-z This field indicates a name of route
route No -
0-9 (such as" US 101")
!*@$()_-+[]:,./
<Space>

50 chars

A-Z
administrative_area_l a-z
No - This field indicates area name
evel_2 0-9
!*@$()_-+[]:,./
<Space>

50 chars

A-Z
administrative_area_l
a-z No - This field indicates area address
evel_1
0-9
!*@$()_-+[]:,./
<Space>

Matrix COSEC Web API User Guide 327

Table: Adding an Event - Parameters

Argument Valid Values Mandatory Default Value Description

max 10 numeric This field indicates postal code of the

countrypostal_code No -
characters country

This field is applicable if event_src is 6

i.e. application.
Valid values 0,1
This field specifies that eid is required
0=eid not required
eid-required - 0 in response or not.
1=eid required
If not specified then default value (0)
should be considered.

• If “Time and Attendance” license is not available when this request is called, all the parameters will
be saved in DB, but no process (i.e. Punch posting process, Attendance Calculation process etc.)
will be called.

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

Example1
Following are some sample cases for this API:

Sample Request:

To add an event for FVM user:

http://192.168.104.12/cosec/api.svc/v2/events?action=set;event-datetime=21052018123000;userid=FVM1;in-
out=0;dtype=12;did=1;gps_latitude=+22.2563;gps_longitude=+073.1833;

Sample Response:

success: 0210200001 : successful

328 Matrix COSEC Web API User Guide

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

http://<servername>/api.svc/v2/event-ta?action=get;<argument>=<value>...

User Rights

User Rights

System Account Enabled.

Enabled only if the following option is enabled in User Configuration (COSEC

Web Application):
ESS
Users > User Configuration > ESS > Punch via ESS

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.

Multiple IDs can be selected, each

15 alphanumeric separated by “, (comma)” e.g.:”1, 3, 7,
Char. (for user) 9…”
A to Z
userid No -
a to z In case userid is provided along with id/
0 to 9 id & range, priority should always be
/_\\.@: given to userid. Value of id/id & range to
be ignored in that case.

Matrix COSEC Web API User Guide 329

Table: Obtaining Time and Attendance Events - Parameters

Argument Valid Values Mandatory Default Value Description

If Field does not

contain hh mm ss
Provide this to get events within a
ddmmyyyyhhmmss- values then by default
date-range No particular date range.
ddmmyyyyhhmmss assume:
Start as -00:00:00 and
End as- 23:59:59

If parameter is not mentioned, the

sorting will be based on default
methods.
0: default
1: userid, event date- If orderby=1, then sorting will occur
orderby No -
time first by userid and then by event date-
2: event date-time time.

If orderby=2, records will be sorted as

per event date-time only

0: display name (As

per export template
If “return-field-name” is not mentioned
config)
return-field-name No - the response will be as per existing
1: actual field (As per
system (i.e. 0 = display name)
view column)
2: both

0 : inactive
Active Return users as per their active flag
1: active No 1
status.
2:all

All
In this argument only single value
Organization
should be allowed.
Branch
Department
If argument range's value is specified
Designation
as "All", ids of all the users that login
Section User (if If argument
Range No user has rights over will return.
Category Range is not specified)
Grade
In case userid is provided along with id/
User
id & range, priority should always be
Custom-group-1
given to userid. Value of id/id & range to
Custom-group-2
be ignored in that case.
Custom-group-3

If argument range is not mentioned and

1 to 999999 (for all the individual argument ID has specified,
ranges except all & then id should be considered of User.
user)
ID No
In case userid is provided along with id/
Max 15 alphanumeric id & range, priority should always be
characters (for user) given to userid. Value of id/id & range to
be ignored in that case.

0: Both
0 (when parameter is
event-status 1: allowed No
not provided)
2: denied

Response Fields

Table: Obtaining Time and Attendance Events - Response Fields

Field Name Tag Name Valid Values Remarks

Index number INDEXNO numeric 15 digits -

330 Matrix COSEC Web API User Guide

Table: Obtaining Time and Attendance Events - Response Fields

Field Name Tag Name Valid Values Remarks

User ID USERID 15 characters. -

User Name USERNAME 45 characters -

Short Name short_name max 15 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

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

1-255
(PANEL_DOOR_TYPE=8)
Door Controller ID DOORCONTROLLERID -
1-75(All Others)

Special Function ID SPECIALFUNCTIONID numeric -

Event ID EVENTID numeric -

Matrix COSEC Web API User Guide 331

Table: Obtaining Time and Attendance Events - Response Fields

Field Name Tag Name Valid Values Remarks

0 = Panel,
1 = Door V1,
2 = Panel Lite
3 = Door V2,
4 = NGT Direct Door,
5 = Wireless Direct Door
6 = Compact Direct Door
7 = PVR Direct Door
8 = Panel200 Enum 13 is reserved for
Panel/Door Type PANEL_DOOR_TYPE
9 = Vega Controller COSEC SAMAY Door V3
11 = ARC Controller
12 = Door V3
15 = Door FMX
18 = MODE
17 = ARC DC 200
19 = Door V4
20 = ARGO
21 = ARGO FACE

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

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

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

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

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

When location is
calculated via GSM. This
GSM Longitude gsm_ longitude 11 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

332 Matrix COSEC Web API User Guide

Table: Obtaining Time and Attendance Events - Response Fields

Field Name Tag Name Valid Values Remarks

It shows location code

corresponding to MAC
Location Code Loc_code 6 characters
address or GPS/GSM
latitude-longitude details.

It shows location name

corresponding to MAC
address or GPS/GSM
Location Name Loc_name 50 characters
latitude-longitude details.
Or it will display Location
Name as per Google.

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.

Comment comment 50 characters

0 = Job Assignment Type

= "Fixed" or "None"

1 to 4294967292 = Job
Reference ID
corresponding to
respective Job Codes

10 characters 4294967293 = Job

Reference ID selected =
Job ID JobID 0,
Continue Job
4294967295
4294967294 = Job
Reference ID selected =
Default Job

4294967295 = Job
Reference ID selected =
None

BLE Code ble_code 0-9999

Allowed Characters 10 alphanumeric

A-Z characters (max.)
BLE Name ble-name
a-z If not available, return
0-9 blank

Custom Group 1 ID CustomGroup1ID 1-999999

Custom Group 2 ID CustomGroup2ID 1-999999 This is Enterprise group ID

Custom Group 3 ID CustomGroup3ID 1-999999

Matrix COSEC Web API User Guide 333

Table: Obtaining Time and Attendance Events - Response Fields

Field Name Tag Name Valid Values Remarks

Allowed Characters

A -Z
a-z
0-9
()
[]
_ (underscore)
- (Hyphen)

Full Name full-name max 200 alphanumeric characters . (full Stop)

/
&
, (comma)
@
' (single quote)
[Space]

When Multi Language is

On, Invalid Character set =
Set3

0 : Pending
Authorization Status Event_Auth_status
1 : Authorized

Max 50 alphanumaric characters.

A-Z
a-z When Multi Language is
Reason punch-reason 0-9 On, Invalid Character set =
_- Set 1
<space>
()[].,/+!@$:*

Valid values 0,1

0=no photo
Wphoto wphoto
1=with photo

As stored against the

eid eid Max 15 numeric digits
event in the server DB

DType dtype 2 numeric digits

MID mid 5 numeric digits

Flash Count flash_count 5 numeric digits

Roll Over Count roll_over_count 5 numeric digits

Event Sequence Number event_sequence_no 7 numeric digits

334 Matrix COSEC Web API User Guide

Table: Obtaining Time and Attendance Events - Response Fields

Field Name Tag Name Valid Values Remarks

Max 15 chars

Allowed Characters
Final RIC ID final-ric A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Final RIC Name final-ric-name
a-z
0-9
-_. ()[]

MM/DD/YYYY
Final RIC Verdict Date Time final -ric-verdict-date
HH:MM

1:pending
Final RIC Verdict final-ric-verdict
2:authorized

Max 30 chars
Allowed Characters
A-Z
Final RIC Remark final-ric-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC ID nonfinal-ric A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC Name nonfinal-ric-name
a-z
0-9
-_. ()[]

Non-Final RIC Verdict Date MM/DD/YYYY

nonfinal-ric-verdict-date
Time HH:MM

1: pending
Non-Final RIC Verdict nonfinal-ric-verdict
2: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC Remark nonfinal-ric-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
nonfinal-ric2 A-Z
Non-Final RIC2 ID a-z
0-9
@_ / : .

Matrix COSEC Web API User Guide 335

Table: Obtaining Time and Attendance Events - Response Fields

Field Name Tag Name Valid Values Remarks

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC2 Name nonfinal-ric2-name
a-z
0-9
-_. ()[]

Non-Final RIC2 Verdict Date MM/DD/YYYY

nonfinal-ric2-verdict-date
Time HH:MM

1: pending
Non-Final RIC2 Verdict nonfinal -ric2 -verdict
2: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC2 Remark nonfinal-ric2-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC3 ID nonfinal-ric3 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC3 Name nonfinal-ric3-name
a-z
0-9
-_. ()[]

Non-Final RIC3 Verdict Date MM/DD/YYYY

nonfinal-ric3-verdict-date
Time HH:MM

1: pending
Non-Final RIC3 Verdict nonfinal-ric3-verdict
2: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC3 Remark nonfinal-ric3-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC4 ID nonfinal-ric4 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC4 Name nonfinal-ric4-name
a-z
0-9
-_. ()[]

Non-Final RIC4 Verdict Date MM/DD/YYYY

nonfinal-ric4-verdict-date
Time HH:MM

336 Matrix COSEC Web API User Guide

Table: Obtaining Time and Attendance Events - Response Fields

Field Name Tag Name Valid Values Remarks

1: pending
Non-Final RIC4 Verdict nonfinal-ric4-verdict
2: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC4 Remark nonfinal-ric4-remark
a-z
0-9
_.,()[]:@!#$*+/\

Allowed Characters
A-Z,
Job Code job-code 15 Characters a-z
0-9
.-_()

Allowed Characters
A-Z
Job Name job-name 30 Characters a-z
0-9
-_.()[]

Example

Calling T&A events with default values.

Sample Request:

http://matrixserver/api.svc/v2/event-ta?action=get

Sample Response:

IndexNo|UserID|UserName|EventDateTime|EntryExitType|MasterControllerID|DoorControllerID|SpecialFunctionID|LeaveDT|IDateTime
33|1|sam|01/10/2011 17:31:18|0|1|1|0||10/01/2011 17:31:21
34|1|sam|03/10/2011 09:28:48|0|1|1|0||10/03/2011 09:28:55
35|2|hardik|03/10/2011 09:54:00|0|1|1|0||10/03/2011 09:54:07
36|3|shwetang|03/10/2011 09:54:10|0|1|1|0||10/03/2011 09:54:17
37|9|home|26/07/2012 16:08:17|0|0|0|0||07/26/2012 16:08:17
38|9|home|26/07/2012 16:08:44|0|0|0|0||07/26/2012 16:08:44
39|9|home|26/07/2012 16:08:49|0|0|0|0||07/26/2012 16:08:49
40|9|home|26/07/2012 16:09:09|0|0|0|0||07/26/2012 16:09:09
<EOT>

Matrix COSEC Web API User Guide 337

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

http://<servername>/api.svc/v2/event-ta-date?action=get;<argument>=<value>...

User Rights

Same as “Obtaining Time and Attendance Events” on page 329

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.

Multiple IDs can be selected, each

userid 15 Char. (for user) No - separated by “, (comma)” e.g.:”1, 3, 7,
9…”

0: display name (As

per export template
If “return-field-name” is not mentioned
config)
return-field-name No - the response will be as per existing
1: actual field (As per
system (i.e. 0 = display name)
view column)
2: both

0 : inactive
Active Return users as per their active flag
1: active No 1
status.
2:all

0: Both
0 (when parameter is
event-status 1: allowed No
not provided)
2: denied

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 15 characters. -

338 Matrix COSEC Web API User Guide

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

Field Name Tag Name Valid Values Remarks

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

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

1-255 (PANEL_DOOR_TYPE=8)
Door Controller ID DOORCONTROLLERID -
1-75 (All Others)

Special Function ID SPECIALFUNCTIONID numeric -

Event ID EVENTID numeric -

0 = Panel,
1 = Door V1,
2 = Panel Lite
3 = Door V2,
4 = NGT Direct Door,
5 = Wireless Direct Door
6 = Compact Direct Door
7 = PVR Direct Door
8 = Panel200 Enum 13 is reserved for
Panel/Door Type PANEL_DOOR_TYPE
9 = Vega Controller COSEC SAMAY Door V3
11 = ARC Controller
12 = Door V3
15 = Door FMX
18 = MODE
17 = ARC DC 200
19 = Door V4
20 = ARGO
21 = ARGO FACE

Matrix COSEC Web API User Guide 339

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

Field Name Tag Name Valid Values Remarks

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
3=SMS This will indicate the event
Source event_src 4=PIM source to the cosec
5=Others software.
6=APP
11=Group FR-ESS
12=Group FR-APP

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

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

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

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

When location is
calculated via GSM. This
GSM Longitude gsm_longitude 11 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

It shows location code

corresponding to MAC
Location Code Loc_code 6 characters
address or GPS/GSM
latitude-longitude details.

It shows location name

corresponding to MAC
address or GPS/GSM
Location Name Loc_name 50 characters
latitude-longitude details.
Or it will display Location
Name as per Google.

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.

340 Matrix COSEC Web API User Guide

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

Field Name Tag Name Valid Values Remarks

Comment comment 50 characters

0 = Job Assignment Type

= "Fixed" or "None"
1-4294967294 = Job
10 characters
Reference ID
Job ID JobID 0, corresponding to
respective Job Codes
4294967295
4294967295 = Job
Reference ID selected =
None

BLE Code ble_code 0-9999

Allowed Characters 10 alphanumeric

A-Z characters (max.)
BLE Name ble-name
a-z If not available, return
0-9 blank

Custom Group 1 ID CustomGroup1ID 1-999999

Custom Group 2 ID CustomGroup2ID 1-999999 This is Enterprise group ID

Custom Group 3 ID CustomGroup3ID 1-999999

Allowed Characters

A -Z
a-z
0-9
()
[]
_ (underscore)
- (Hyphen)

Full Name full-name max 200 alphanumeric characters . (full Stop)

/
&
, (comma)
@
' (single quote)
[Space]

When Multi Language is

On, Invalid Character set =
Set3

0 : Pending
Authorization Status Event_Auth_status
1 : Authorized

Matrix COSEC Web API User Guide 341

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

Field Name Tag Name Valid Values Remarks

Max 50 alphanumaric characters.

A-Z
a-z When Multi Language is
Reason punch-reason 0-9 On, Invalid Character set =
_- Set 1
<space>
()[].,/+!@$:*

Valid values 0,1

0=no photo
Wphoto wphoto
1=with photo

As stored against the

eid eid Max 15 numeric digits
event in the server DB

DType dtype 2 numeric digits

MID mid 5 numeric digits

Flash Count flash_count 5 numeric digits

Roll Over Count roll_over_count 5 numeric digits

Event Sequence Number event_sequence_no 7 numeric digits

Allowed Characters
A-Z,
Job Code job-code 15 Characters a-z
0-9
.-_()

Allowed Characters
A-Z
Job Name job-name 30 Characters a-z
0-9
-_.()[]

Example

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

Sample Request:

http://matrixserver/api.svc/v2/event-ta-date?action=get;date-range=01012011000000-02012011235959

Sample Response:

success : <response code> : No records found

342 Matrix COSEC Web API User Guide

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

http://<servername>/api.svc/v2/event-acs?action=get;<argument>=<value>...

User Right

User Rights

System Account Enabled.

ESS Enabled.

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.

Multiple IDs can be selected, each

userid 15 Char. (for user) No - separated by “, (comma)” e.g.:”1, 3, 7,
9…”

If Field does not

contain hh mm ss
ddmmyyyyhhmmss- values then by default Provide this to get events within a
date-range No
ddmmyyyyhhmmss assume: particular date range.
Start as -00:00:00 and
End as- 23:59:59

Matrix COSEC Web API User Guide 343

Table: Obtaining Access Control Events - Parameters

Argument Valid Values Mandatory Default Value Description

If parameter is not mentioned, the

sorting will be based on default
methods.
0: default
1: userid, event date- If orderby=1, then sorting will occur
orderby No -
time first by userid and then by event date-
2: event date-time time.

If orderby=2, records will be sorted as

per event date-time only

0: display name (As

per export template
If “return-field-name” is not mentioned
config)
return-field-name No - the response will be as per existing
1: actual field (As per
system (i.e. 0 = display name)
view column)
2: both

0 : inactive
Active Return users as per their active flag
1: active No 1
status.
2:all

0: Both
0 (when parameter is
event-status 1: allowed No
not provided)
2: denied

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 15 characters. a-z
0-9
/_\\.@:

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

1-255 (PANEL_DOOR_TYPE=8)
Door Controller ID DOORCONTROLLERID -
1-75 (All Others)

Special Function ID SPECIALFUNCTIONID numeric -

Event ID EVENTID numeric -

344 Matrix COSEC Web API User Guide

Table: Obtaining Access Control Events - Response Fields

Field Name Tag Name Valid Values Remarks

0 = Panel,
1 = Door V1,
2 = Panel Lite
3 = Door V2,
4 = NGT Direct Door,
5 = Wireless Direct Door
6 = Compact Direct Door
7 = PVR Direct Door
8 = Panel200 Enum-13 is reserved for
Panel/Door Type PANEL_DOOR_TYPE
9 = Vega Controller COSEC SAMAY Door V3
11 = ARC Controller
12 = Door V3
15 = Door FMX
18 = MODE
17 = ARC DC 200
19 = Door V4
20 = ARGO
21 = ARGO FACE

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 11 characters parameter will contain :
latitude
Example: -77.008312

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

Matrix COSEC Web API User Guide 345

Table: Obtaining Access Control Events - Response Fields

Field Name Tag Name Valid Values Remarks

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

When location is
calculated via GSM. This
GSM Longitude gsm_longitude 11 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

It shows location code

corresponding to MAC
Location Code Loc_code 6 characters
address or GPS/GSM
latitude-longitude details.

It shows location name

corresponding to MAC
address or GPS/GSM
Location Name Loc_name 50 characters
latitude-longitude details.
Or it will display Location
Name as per Google.

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.

Comment comment 50 characters

0 = Job Assignment Type

= "Fixed" or "None"
1-4294967294 = Job
15 characters
Reference ID
Job ID JobID 0, corresponding to
respective Job Codes
4294967295
4294967295 = Job
Reference ID selected =
None

BLE Code ble_code 0-9999

Custom Group 1 ID CustomGroup1ID 1-999999

Custom Group 2 ID CustomGroup2ID 1-999999 This is Enterprise group ID

Custom Group 3 ID CustomGroup3ID 1-999999

346 Matrix COSEC Web API User Guide

Table: Obtaining Access Control Events - Response Fields

Field Name Tag Name Valid Values Remarks

Allowed Characters

A -Z
a-z
0-9
()
[]
_ (underscore)
- (Hyphen)

Full Name full-name max 200 alphanumeric characters . (full Stop)

/
&
, (comma)
@
' (single quote)
[Space]

When Multi Language is

On, Invalid Character set =
Set3

Max 50 alphanumaric characters.’

A-Z
a-z When Multi Language is
Reason punch-reason On, Invalid Character set =
0-9 Set 1
_-
<space>
()[].,/+!@$:*

Valid values 0,1

0=no photo
Wphoto wphoto
1=with photo

As stored against the

eid eid Max 15 numeric digits
event in the server DB

DType dtype 2 numeric digits

Flash Count flash_count 5 numeric digits

Roll Over Count roll_over_count 5 numeric digits

Event Sequence Number event_sequence_no 7 numeric digits

Example

For default values,

Matrix COSEC Web API User Guide 347

Sample Request:

http://matrixserver/api.svc/v2/event-acs?action=get

Sample Response:

IndexNo|UserID|UserName|EventDateTime|EntryExitType|MasterControllerID|DoorControllerID|IDateTime
30904|555013|KRISHNANAND SHIVRATAN PAL|23/02/2013 12:40:08|0|48|1| 30905|555013|KRISHNANAND SHIVRATAN PAL|23/02/
2013 12:40:15|0|48|1|
30906|8515|KARANSINGH DILBAHADUR DHAMI|23/02/2013 12:41:26|0|48|1|
30907|8699|RAJIV RANJAN PRAKASH SINGH|23/02/2013 12:41:35|0|48|1|
30908|8515|KARANSINGH DILBAHADUR DHAMI|23/02/2013 12:42:05|0|48|1|
30909|8515|KARANSINGH DILBAHADUR DHAMI|23/02/2013 12:43:13|0|48|1| 30910|555013|KRISHNANAND SHIVRATAN PAL|23/02/
2013 12:44:48|0|48|1|
30911|8515|KARANSINGH DILBAHADUR DHAMI|23/02/2013 12:44:55|0|48|1|
30912|8699|RAJIV RANJAN PRAKASH SINGH|23/02/2013 12:46:29|0|48|1|
30913|8699|RAJIV RANJAN PRAKASH SINGH|23/02/2013 16:11:46|0|48|1|
30914|555013|KRISHNANAND SHIVRATAN PAL|25/02/2013 10:52:46|0|48|1|

348 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

http://<servername>/api.svc/v2/event-acs-date?action=get;<argument>=<value>...

User Rights

Same as “Obtaining Access Control Events” on page 343

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.

Multiple IDs can be selected, each

userid 15 Char. (for user) No - separated by “, (comma)” e.g.:”1, 3, 7,
9…”

0: display name (As

per export template
If “return-field-name” is not mentioned
config)
return-field-name No - the response will be as per existing
1: actual field (As per
system (i.e. 0 = display name)
view column)
2: both

0 : inactive
Active Return users as per their active flag
1: active No 1
status.
2:all

0: Both
0 (when parameter is
event-status 1: allowed No
not provided)
2: denied

Response Fields

Table: Obtaining Access Control Events by Date - Response Fields

Field Name Tag Name Valid Values Remarks

Index number INDEXNO numeric 15 digits -

Matrix COSEC Web API User Guide 349

Table: Obtaining Access Control Events by Date - Response Fields

Field Name Tag Name Valid Values Remarks

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

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

1-255 (PANEL_DOOR_TYPE=8)
Door Controller ID DOORCONTROLLERID -
1-75 (All Others)

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,
5 = Wireless Direct Door
6 = Compact Direct Door
7 = PVR Direct Door
Enum-13 is reserved for
Panel/Door Type PANEL_DOOR_TYPE 8 = Panel200
COSEC SAMAY Door V3.
9 = Vega Controller
11 = ARC Controller
15 = Door FMX
18 = MODE
17 = ARC DC 200
19 = Door V4
20 = ARGO
21 = ARGO FACE

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

350 Matrix COSEC Web API User Guide

Table: Obtaining Access Control Events by Date - Response Fields

Field Name Tag Name Valid Values Remarks

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 11 characters parameter will contain :
latitude
Example: -77.008212

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

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

When location is
calculated via GSM. This
GSM Longitude gsm_longitude 11 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

It shows location code

corresponding to MAC
Location Code Loc_code 6 characters
address or GPS/GSM
latitude-longitude details.

It shows location name

corresponding to MAC
address or GPS/GSM
Location Name Loc_name 50 characters
latitude-longitude details.
Or it will display Location
Name as per Google.

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.

Comment comment 50 characters -

Matrix COSEC Web API User Guide 351

Table: Obtaining Access Control Events by Date - Response Fields

Field Name Tag Name Valid Values Remarks

0 = Job Assignment Type

= "Fixed" or "None"
1-4294967294 = Job
10 characters Reference ID
Job ID JobID 0, corresponding to
4294967295 respective Job Codes
4294967295 = Job
Reference ID selected =
None

BLE Code ble_code 0-9999 -

Custom Group 1 ID CustomGroup1ID 1-999999

Custom Group 2 ID CustomGroup2ID 1-999999 This is Enterprise group ID

Custom Group 3 ID CustomGroup3ID 1-999999

Allowed Characters

A -Z
a-z
0-9
()
[]
_ (underscore)
- (Hyphen)

Full Name full-name max 200 alphanumeric characters . (full Stop)

/
&
, (comma)
@
' (single quote)
[Space]

When Multi Language is

On, Invalid Character set =
Set3

Max 50 alphanumaric characters.’

A-Z
a-z When Multi Language is
Reason punch-reason On, Invalid Character set =
0-9 Set 1
_-
<space>
()[].,/+!@$:*

Valid values 0,1

0=no photo
Wphoto wphoto
1=with photo

352 Matrix COSEC Web API User Guide

Table: Obtaining Access Control Events by Date - Response Fields

Field Name Tag Name Valid Values Remarks

As stored against the

eid eid Max 15 numeric digits
event in the server DB

DType dtype 2 numeric digits

MID mid 5 numeric digits

Flash Count flash_count 5 numeric digits

Roll Over Count roll_over_count 5 numeric digits

Event Sequence Number event_sequence_no 7 numeric digits

Example

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

Sample Request:

http://matrixserver/api.svc/v2/event-acs-date?action=get;date-range=01012012000000-02012012235959

Sample Response:

IndexNo|UserID|UserName|EventDateTime|EntryExitType|MasterControllerID|DoorControllerID|IDateTime
1890|112|PARESH CHAUHAN|01/01/2012 08:39:29|0|4|1|01/01/2012 08:40:00
1921|443|BHARGAV M PATEL|02/01/2012 09:41:29|0|4|1|01/02/2012 09:41:32
1923|112|PARESH CHAUHAN|02/01/2012 09:42:25|0|4|1|01/02/2012 09:42:27
1924|621|patel vishal H|02/01/2012 09:42:28|0|4|1|01/02/2012 09:42:32
1925|521|PRAVINSINH GANPATSINH CHAUHAN|02/01/2012 09:42:34|0|4|1|01/02/2012 09:42:36
1926|489|KADIR I MANSURI|02/01/2012 09:42:37|0|4|1|01/02/2012 09:42:39
1927|424|VIMAL S TADVI|02/01/2012 09:42:40|0|4|1|01/02/2012 09:42:41
1928|684|JADAV MAYUR G|02/01/2012 09:42:46|0|4|1|01/02/2012 09:42:47
1929|449|CHINTAN A VARU|02/01/2012 09:42:50|0|4|1|01/02/2012 09:42:52
1930|644|Dhramesh Thakkar|02/01/2012 09:43:05|0|4|1|01/02/2012 09:43:07
1931|496|MILAN TRIVEDI|02/01/2012 09:43:11|0|4|1|01/02/2012 09:43:13
1932|515|KAMLESH KANUBHAI PARMAR|02/01/2012 09:43:26|0|4|1|01/02/2012 09:43:29
1933|498|RAVINDRA RAJPUT|02/01/2012 09:43:29|0|4|1|01/02/2012 09:43:33
1934|686|Saikh Sajid Usmanbhai|02/01/2012 09:43:33|0|4|1|01/02/2012 09:43:35
1935|514|BABU MANSUKHBHAI PALASH|02/01/2012 09:43:35|0|4|1|01/02/2012 09:43:38
1936|417|RAJESH P MACHHI|02/01/2012 09:44:07|0|4|1|01/02/2012 09:44:09
1937|434|KISHOR SOLANKI|02/01/2012 09:44:15|0|4|1|01/02/2012 09:44:18
1938|5|AMBALAL PADHIYAR|02/01/2012 09:44:24|0|4|1|01/02/2012 09:44:27
1940|4|DEVENDRA L MACHHI|02/01/2012 09:45:47|0|4|1|01/02/2012 09:45:49

Matrix COSEC Web API User Guide 353

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

http://<servername>/api.svc/v2/event-others?action=get;<argument>=<value>...

User Rights

User Rights

System Account Enabled

ESS Disabled

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-255 -

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

Site ID siteid 1-999 -

354 Matrix COSEC Web API User Guide

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

Field Name Tag Name Valid Values Remarks

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

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

Matrix COSEC Web API User Guide 355

Table: List of Events

Event ID Event Description

165 User Denied – Invalid Route Access

166 User Denied – Invalid Shift Access

201 Door Status changed

202 Dead-man timer changed

203 DND status changed

204 Aux input status changed

205 Aux output status changed

206 Door sense input status

207 Door Controller Communication status

301 Dead-man timer expired Alarm– User IN

302 Duress detection

303 Panic Alarm

304 FP Memory Full – Alarm

305 Door Held open too long

306 Door Abnormal

307 Door force open

308 Door Controller Offline

309 Door Controller -Fault

310 Tamper Alarm

311 Master Controller Mains fail Alarm

312 Master Controller Battery fail

313 Master Alarm – MC Alarm input

314 RTC

315 Event Buffer Full

351 Alarm acknowledged

352 Alarm cleared

353 Alarm Re-issued

401 User Block/Restore

402 Login to ACS

403 Message transaction confirmation to ACMS

404 Guard Tour-status

405 Enrolment

406 Master Alarm sense input status

407 Master Aux Output status

408 Input Output Group Link status

409 Credentials Deleted

356 Matrix COSEC Web API User Guide

Table: List of Events

Event ID Event Description

410 Time Triggered Function

411 Time Stamping Function

412 Guard tag

413 Camera Event for time stamp

451 Configuration Change

452 Roll over of events

453 Master Controller Power ON

454 Configuration Defaulted

455 Soft Override

456 Backup and Update

457 Default System

458 Sensor Calibration

• 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 357

Obtaining Visitor Events

This will be used to fetch the Visitor events for a specified date range.

Action

action = get

Syntax

http://<servername>/api.svc/v2/visitor-event?action=<get>;<argument>=<value>...

User Rights

User Rights

System Account Enabled

(Only when System Account user has view for Visitor Events
Admin Module ' System Accounts ' Roles And Rights Configuration)

ESS Disabled

Parameters

Table: Obtaining Visitor Events - Parameters

Argument Valid Values Description

Mandatory

(Not mandatory when either mobile-no or date-range or

both is provided)
0-9
appointment-no When Appointment number is mentioned, other
12 Digits (Each Appointment No)
parameters- mobile-no, date-range should be ignored.

System should provide all the events of the visitor that are
available in duration of that appointment period.

Not mandatory.
0-9 Provide this parameter to get events corresponding to
mobile-no + - () particular mobile-no.
Max length=20 characters When this parameter is provided, all events corresponding
to this mobile-no till date should be shown

Not mandatory. Provide this parameter to get events within

a particular date-range.
The mentioned dates should be compared against Event
Date Time. Not Insertion Date time.
When this parameter is provided, all events falling between
the date-range mentioned should be shown.
If field does not contain hh mm ss values then by default
assume:
Start as - 00:00:00 and End as - 23:59:59
ddmmyyyyhhmmss-
date-range
ddmmyyyyhhmmss
Example- if parameter value is: date-range = 23012015-
24012015
Then convert it to: 23012015000000 - 24012015235959

If proper value is mentioned, i.e. date-range =

23012015000000 - 23012015130000; then return only
events that fall between the start and end date time
mentioned above e.g. - all events that occurred between
23 Jan 00:00:00 hrs to 23 Jan 13:00:00 hrs.

358 Matrix COSEC Web API User Guide

Table: Obtaining Visitor Events - Parameters

Argument Valid Values Description

The list of valid fields is mentioned

Field-name -
in the response section.

Response

Field Name Tag Name Valid Values Remarks

Appointment Number appointment-no numeric 12 digits

Allowed Characters
A-Z
Visitor Name visitor-name 40 characters a-z
0-9
-_. ()[]

Allowed Characters
Mobile Number mobile-no 20 characters 0-9
+ - ()

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

0: Entry
Entry/Exit Type entryexittype
1: Exit

0: denied
Access Allowed or Denied access_allowed
1: allowed

0=device
6= APP
This will indicate the event
Source event_src 7=station
source to the cosec software.
8=email
10=system

Max 30 alphanumeric
Device Name device_name
characters

Max 30 alphanumeric
Station Name station_name
characters

When location is calculated via

GPS. This parameter will
GPS Latitude gps_latitude 11 characters
contain: latitude
Example: -77.008212

When location is calculated via

GPS. This parameter will
GPS Longitude gps_longitude 11 characters
contain: longitude
Example: 38.889723

When location is calculated via

GSM Latitude gsm_latitude 11 characters GSM. This parameter will
contain: latitude

When location is calculated via

GSM Longitude gsm_longitude 11 characters GSM. This parameter will
contain: longitude

When location is calculated via

Wi-Fi. This parameter will
MAC Address mac_address 17 characters
contain: MAC Address of
source

Master Controller ID mastercontrollerid 1-65535 Device's master id

Matrix COSEC Web API User Guide 359

Field Name Tag Name Valid Values Remarks

1-255 (PANEL_DOOR_TYPE
= 8)
Door Controller ID doorcontrollerid Door id
1-75 (All Others)

0 = Panel,
1 = Direct Door,
2 = Panel Lite
3 = Direct Door V2,
4 = NGT Direct Door,
5 = Wireless Direct Door
6 = Compact Direct Door
7 = PVR Direct Door
8= Panel-lite V2
9= Vega Controller Enum - 13 is reserved for
Panel/Door Type panel_door_type
11 = Arc Controller COSEC SAMAY Door V3.
12 = Door V3
14 = ARC IO 800
15 = Door FMX
16=Path V2
18 = MODE
17 = ARC DC 200
19 = Door V4
20 = ARGO
21 = ARGO FACE

This will display the location

name, fetched from
LocationMst Table from the
Location Name loc_name 50 characters column name LOCName
corresponding to the MAC
Address or the GPS/GSM
latitude-longitude details.

360 Matrix COSEC Web API User Guide

CHAPTER 14 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

http://<servername>/api.svc/v2/device-commands?action=command;<argument>=<value>......

The Login User must have rights on the device to send a valid command.

User Rights

User Rights

System Account Enabled.

ESS Disabled

Matrix COSEC Web API User Guide 361

Parameters

Table: Sending Commands to Device - Parameters

Argument Valid Values Mandatory Default Value Description

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

This is the type of device to which

command is to be sent.

Here,

0 = Panel,
1 = Door V1,
2 = Panel Lite
3 = Door V2,
4 = NGT Direct Door,
0,1,2,3,4,5,6,7,8,9,11,12, 5 = Wireless Direct Door
14,15,18,19,17,20, 21 6 = Path Controller
device-type Yes -
7 = PVR Direct Door
8 = Panel200
9 = Vega Controller
11 = ARC Controller
12 = Door V3
14 = ARC IO 800
15 = Door FMX
18 = MODE
19 = Door V4
17 = ARC DC 200
20 = ARGO
21 = ARGO FACE

Vaild only when command is to be

sent to a Panel Door.

1 to 255 (device-type=8) Note: If this value is not specified

Panel-door-no No -
1 to 75 (All Others) with device type 0 and 2, 8 then the
interpretation is that the command is
intended for the corresponding Panel
or Panel-lite.

362 Matrix COSEC Web API User Guide

Table: Sending Commands to Device - Parameters

Argument Valid Values Mandatory Default Value Description

To specify a command.

For device-type = 14, the applicable

commands are 1,8,11.

For a Panel-door-no of type =8 and if

it is ARC IO 800 - Panel Lite V2 Door,
then applicable command is s are
1,8,11.
1 - set date-time
Delete Faces is applicable only for
2 - normalize door
Device-type =9/15/18/21
3 - lock door
4 - unlock door
Delete Faces will be applicable for
5 - delete FP (clears all
Device-type =16/17
finger prints)
6 - sync credentials
command-type Yes - Delete Faces will be applicable for
7 - clear all alarms
Device-type =8
8 - factory defaults
9 - delete palms
Manual Forgiveness is applicable
10-open door
only for device-type=5/7/8/9/12/15/
11-activate aux output
21
12-delete faces
13 -manual forgiveness
For device-type = 21, the applicable
commands are 1,2,3,4,7,8,10,12,13

For Duress Finger feature,

command-type = 5,6,7 should
respectively delete Duress Finger
same as normal finger, should sync
Duress Finger same as Normal
Finger, Clear Duress alarm due to
Duress Finger same as Duress PIN.

Yes (If
time-interval 1-99 seconds command To specify the time interval.
type=11)

1 - Auxiliary Output Port 1

2 - Auxiliary Output Port 2
3 - Auxiliary Output Port 3
Yes (If
4 - Auxiliary Output Port 4
command
aux-output-port 5 - Auxiliary Output Port 5
type=11 for
6 - Auxiliary Output Port 6
ARC IO800)
7 - Auxiliary Output Port 7
8 - Auxiliary Output Port 8

Applicable only for command-

1-global
Forgiveness No 1-global type=13 and Device-type=5/7/8/9/12/
2-local
15/16/17/19/20/21

Yes (Only If
Access-zone 1-99 Forgiveness - For forgiveness =1, aceess-zone=0
=2)

A-Z Yes (Only If

Userid a-z command-
0-9 type=13)
@ _ : ./ \s

Matrix COSEC Web API User Guide 363

 Applicable device-commands based on device-type:

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

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

c) Direct Door: Applicable Commands: 1 - 5, 7, 8, 10,11 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:

http://matrixserver/api.svc/v2/device-commands?action=command;device-id=1;device-type=0;Panel-door-
no=1;command-type=6;

Sample Response:

success: <response code> : Command received successfully

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

Sample Request:

http://matrixserver/api.svc/v2/device-commands?action=command;device-id=1;device-type=0;Panel-door-
no=1;command-type=7;

Sample Response:

failed: <response code> : No alarms to clear

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

364 Matrix COSEC Web API User Guide

CHAPTER 15 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

http://<servername>/api.svc/v2/device-users?action=get;<argument>=<value>......

User Rights

User Rights

System Account Enabled.

ESS Disabled

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)

Matrix COSEC Web API User Guide 365

Table: User Count on 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,
1 = Door V1,
2 = Panel Lite
3 = Door V2,
4 = NGT Direct Door,
0,1,2,3,4,5,6,7,8,9,11,
5 = Wireless Direct Door
12,15,18,19,17,20, 21
device-type Yes - 6 = Path Controller
7 = PVR Direct Door
8 = Panel200
9 = Vega Controller
11 = ARC Controller
12 = Door V3
15 = Door FMX
18 = MODE
19 = Door V4
17 = ARC DC 200
20 = ARGO
21 = ARGO FACE

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:

http://matrixserver/api.svc/v2/device-users?action=get;device-id=11,;device-type=3

Sample Response:

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

The Login User must have rights on the device for which user count is to be fetched.

366 Matrix COSEC Web API User Guide

CHAPTER 16 Notifications

These APIs can be used to fetch as well as delete the notification messages for various updates related to the login
user such as leave approvals, leave application rejections, missing IN/OUT punches etc. The following functions
can be performed:

• Retrieving Notifications
• Deleting Notifications

Matrix COSEC Web API User Guide 367

Retrieving Notifications

To fetch notification messages for a login user.

Action

action=get

Syntax

http://<servername>/api.svc/v2/notifications?action=get;<argument>=<value>…

User Rights

User Rights

System Account Enabled.

ESS Enabled.

Parameters

Table: Retrieving Notifications - Parameters

Argument Valid Values Mandatory Default Value Description

If login user is an ESS user, it should be

Userid Varchar(15) Yes - the logged in user’s ID.

Response Fields

Table: Retrieving Notifications - Response Fields

Field Name Tag Name Valid Values Remarks

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

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

Allowed Characters
A-Z
Short Name short-name max 15 alphanumeric characters a-z
0-9
-_. ()

The total number of new

Count notification-count - notification available for
that user

Generation Date generation-date mm/dd/yyyy -

Generation Time generation-time HH:MM:SS -

368 Matrix COSEC Web API User Guide

Table: Retrieving Notifications - Response Fields

Field Name Tag Name Valid Values Remarks

1 = Leave Approved,
2 = Leave Rejected,
3 = Tour Approved,
4 = Tour Rejected,
5 = Leave Modification Approved,
6 = Leave Modification Rejected,
7= Leave Cancellation Approved,
8 = Leave Cancellation Rejected,
9 = Attendance Authorized,
10 = Attendance Correction
Approved,
11 = Attendance Correction
Rejected,
12 = COFF Approved,
13 = COFF Rejected,
14 = Missing IN Punch,
Type notification-type -
15 = Missing OUT Punch,
16 = Overtime Authorized,
17 = Tour Cancellation Approved,
18 = Tour Cancellation Rejected,
19 = Tour Modification Approved,
20 = Tour Modification Rejected,
21 = COFF Cancellation
Approved,
22 = COFF Cancellation
Rejected,
23 = Short Leave Approved,
24 = Short Leave Rejected,
25 = Official Leave Approved,
26 = Official Leave Rejected
28= Overtime Approved
29= Overtime Rejected

alphanumeric characters as per Message for that

Message message
COSEC Web configuration. notification type

Example

Sample Request:

http://matrixserver/api.svc/v2/notifications?action=get;userid=1234

Sample Response:

user-id|user-name|short-name|notification-count|generation-date|generation-time|notification-type|message
1234|Harish Patel|Harish P|1|04/23/2014|17:45|10|Attendance Correction application for 07/03/2014 is Approved.
<EOT>

Matrix COSEC Web API User Guide 369

Deleting Notifications

To delete notification messages of the login user.

Action

action=delete

Syntax

http://<servername>/api.svc/v2/notifications?action=delete;<argument>=<value>…

User Rights

User Rights

System Account Enabled.

ESS Enabled.

Parameters

Table: Deleting Notifications - Parameters

Argument Valid Values Mandatory Default Value Description

If login user is an ESS user, it should be

userid Varchar(15) Yes - the logged in user’s ID.

All the notifications generated before

the specified date and time, will be
generation-datetime ddmmyyyyhhmm Yes -
deleted from the COSEC database.

370 Matrix COSEC Web API User Guide

CHAPTER 17 Login User Details

This API enables the third party software to fetch the login user’s basic details.

Action

action=get

Syntax

http://<servername>/api.svc/v2/loginuser?action=get;<argument>=<value>…

User Rights

User Rights

System Account Disabled

ESS Enabled

Response Fields

Table: Getting Login User’s Details - Response Fields

Field Name Tag Name Valid Values Remarks

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

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

Allowed Characters
A-Z
User Short Name short-name max 15 alphanumeric characters a-z
0-9
-_. ()

1 = yes
Reporting In-charge reporting-in-charge -
0 = no

na
Gender gender male -
female

Matrix COSEC Web API User Guide 371

Table: Getting Login User’s Details - Response Fields

Field Name Tag Name Valid Values Remarks

0: disabled
Enabled for ESS enabled -
1: enabled

upto 40 characters.
It will be blank of no IMEI
Allowed Characters: number is registered or if a
IMEI Number imei
registration request was
Alphanumeric rejected by System Admin.
-

imei-authorized=0 if a
registration request is in
pending state.
imei-authorized=1 if a
0: Pending registration request is in
1: Authorized authorized state.
2: Rejected imei-authorized=2 if a
3: Deleted (When IMEI is registration request is in
IMEI Authorized or not imei-authorized
authorized, but system admin rejected state.
removes it manually using the
COSEC Web application and It will be blank if no IMEI
saves it.) number is registered or
there is no request in
pending state or if a
registration request was
rejected by System Admin.

Attendance marking via ESS 1 = enabled

attendance-via-ess -
enabled 0 = disabled

1 = allowed
Allow edit user details edit-user-details -
0 = not allowed

This parameter will be

0 = Calendar Month based on Attendance
Attendance Period attendance-period
1 = Customized Policy assigned to the
login user.

If Start Date : 15th day of

the month
and End Date : 16th of
next month.
then, the response will
XX-XX
contain :
Month Start-End Date month-start-end where valid values for XX = 1 to
month-start-end = 15-16
28
This parameter is
applicable only if
attendance-period=1
If attendance-period=0,
return blank value.

372 Matrix COSEC Web API User Guide

Table: Getting Login User’s Details - Response Fields

Field Name Tag Name Valid Values Remarks

Reference ESS Menu:

Tags for ESS pages ESS Menu - T&A

Basic

events Events

holiday-schedule Holiday Schedule

user-basic-details User Basic Details

visitor-preregistration Visitor Pre-Registration

self-declaration self-declaration

health-records health-record

Time Attendance

daily-attendance Daily Attendance

attendance-summary Attendance Summary

attendance-details 1 = Yes Attendance Details

2 = No
shift-schedule Shift Schedule

short-leave Short Leave/Official In-Out

attendance-correction Attendance Correction

ESS rights : <cosec page
Leave Management
names>
leave-balance Leave Balance

leave-application Leave Application

tour-application Tour Application

coff-application C-Off Application

E-Canteen

account Account Details

menu Menu

expenditure Expenditure

transaction-correction Transaction Correction

FVM

field-visit-schedule Field Visit Schedule

field-visit-status Field Visit Status

field-visit-correction- Field Visit Correction

application Application

Reports

schedule-status-summary- Schedule Status Summary

report Report

Matrix COSEC Web API User Guide 373

Table: Getting Login User’s Details - Response Fields

Field Name Tag Name Valid Values Remarks

Blank if user is not a reporting Reference ESS menu for

in-charge. reporting in-charge

ESS Menu - Reporting In-

Tags for ESS pages
charge

Group Details

group-summary Group Summary

member-daily-attendance Daily Attendance

member-events Member Events

member-attendance Member Attendance

Approval/Authorization

attendance-authorization Attendance Authorization

Short Leave/Official IN-

short-leave-authorization
OUT Authorization

Overtime/C-OFF
overtime-authorization
Authorization
In-charge Permissions : <in- 1 = Yes
charge pages name> leave-approval 2 = No Leave Approval

tour-approval Tour Approval

attendance-correction-
Attendance Correction
authorization

coff-approval C-OFF Approval

Visitor Pre-Registration
visitor-preregistration-approval
Approval

mark-group-attendance Mark Group Attendance

invite-visitor-authorization Group Details

member-field-visit-schedule Field Visit Schedule

member-field-visit-status Field Visit Status

Approval/Authorization

field-visit-correction- Field Visit Correction

authorization Authorization

Format: VXXRXX.XX
Maximum 10 alphanumeric
COSEC Version cosec-version
characters For e.g. V06R01, V06R02,
V05R08.20

0 : Disabled
Punch Marking Via API punch-api -
1 : Enabled

Enabled/Disabled status of
0 : Disabled auto-attendance marking
Auto-Punch Marking auto-attendance
1 : Enabled feature.

0 : Disabled
Manual Punch Marking manual-punch -
1 : Enabled

374 Matrix COSEC Web API User Guide

Table: Getting Login User’s Details - Response Fields

Field Name Tag Name Valid Values Remarks

0 : None
Location Data Mandatory from
location-mandatory 1 : Any Location -
Apps
2 : Configured Locations

0 : Disabled
Door Access Through API door-access-api
1 : Enabled

Maximum 2 alphanumeric
API security Key api-security-key
characters

0 : Disabled
FVM Flag FVM-enable
1 : Enabled

0: None
Job Assignment Type job-assignment-type 1: Fixed
2: Device Based

Restrict Half Day 0 : Disabled

Restrict-half-day 0 or 1
Considerations 1 : Enabled

0: Server Timezone
Timezone for Punch Marking Punch-marking-timezone
1 : Local Timezone

0: Unauthorized Host
Authorized Host User auth-host-user 0 or 1
1: Authorized Host

If Enable FR/Punch
0 : None Marking Via API/Manual
1 : Attendance Punch Marking is disabled
Face Mandatory For Punch face-mandatory
2 : Access Control for a user, face-mandatory
3 : Both tag will be available only
for value 0 : None

Total Number of faces

Enrolled faces enrolled_faces 0-40
enrolled for this user

PIN Authentication For Door 0 : Disabled

pin-authentication
Access 1 : Enabled

0 : disabled enabled only when

Reason for punching from
punch-reason-flg 1 : enabled Location Mandatory For
unassigned location
Punch = 0,1

0: Disable This Component refers

1: Enable whether user is allowed to
apply for advance overtime
or not. Logic to set value
as 0 or 1 has been
provided in server’ SRS.
This parameter’s value is
Advance Overtime Component ot-applicable combination of below
parameters:
1. Auto-Authorization
Overtime
2. Enable Attendance
Calculation
3. OT/C-OFF Eligibility
4. Enable OT/C-OFF
Calculation

Matrix COSEC Web API User Guide 375

Table: Getting Login User’s Details - Response Fields

Field Name Tag Name Valid Values Remarks

0 : Disabled When 0 is obtained, then

1 : Enabled Reverse Geo Coding API
should not be fired to get
location address
Get Location details Get-location-details
When 1 is obtained,
Reverse Geo Coding API
should be fired to get
location address

Google API Key google-api-key 100 characters

0 : Disabled Returns value from User

APTA Face Anti-Spoofing apta-face-anti-spoofing
1 : Enabled Configuration > ESS.

1 : enabled
Capture Photo capture-photo
0 : disabled

• If T&A license is not available, “0” will be returned for the following pages:

ESS Menu – Time Attendance ESS Menu – Reporting In Charge

Time Attendance Group Details

Daily Attendance Group Summary

Attendance Summary Daily Attendance

Attendance Details Member Events

Shift Schedule Member Attendance

Short Leave/Official In-Out Approval/Authorization

Attendance Correction Attendance Authorization

Leave Management Short Leave/Official IN-OUT Authorization

Leave Balance Overtime/C-OFF Authorization

Leave Application Leave Approval

Tour Application Tour Approval

C-Off Application Attendance Correction

C-OFF Approval

Mark Group Attendance

Invite Visitor Authorization

• If e-Canteen license is not available, then “0” will be returned for the following pages:

ESS Menu – Time Attendance

E-Canteen

Account Details

Menu

376 Matrix COSEC Web API User Guide

 ESS Menu – Time Attendance

Expenditure

Transaction Correction

• If Visitor Management license is not available, then “0” will be returned for the following pages:

ESS Menu – Time Attendance ESS Menu – Reporting In Charge

Basic Approval/Authorization

Visitor Pre-Registration Visitor Pre-Registration Approval

• If FVM license is not available, then “0” will be returned for the following pages.

ESS Menu – FVM ESS Menu – Reporting In Charge

FVM Group Details

Field Visit Schedule Field Visit Schedule

Field Visit Status Field Visit Status

Field Visit Correction Application

Reports Approval/Authorization

Schedule Status Summary Report Field Visit Correction Authorization

• For an ESS user, who is not reporting-group in-charge, the following pages will always be marked as “0”.

ESS Menu – Reporting In Charge

Group Details

Group Summary

Daily Attendance

Member Events

Member Attendance

The above pages will be marked as 1, only if the login user is a reporting group in-charge, and T&A license
is available.

For the field Reporting In-charge, the system will allow all the configured new RIC in the Reporting Group
page for fetching the information.

Example

This example demonstrates a sample request fetching details of the login user in XML format, with details of the
ESS application pages on which the user has, or does not have access rights.

Sample Request:

http://matrixserver/api.svc/v2/loginuser?action=get;format=xml

Matrix COSEC Web API User Guide 377

Sample Response:

<DocumentElement>
<LoginUserDetail>
<user-id>2455</user-id>
<user-name>JOBIN SAMUEL</user-name>
<short-name>JOBIN SAMUEL</short-name>
<reporting-in-charge>0</reporting-in-charge>
<gender>male</gender>
<enabled>1</enabled>
<imei>353345052067690</imei>
<imei-authorized>1</imei-authorized>
<attendance-via-ess>0</attendance-via-ess>
<edit-user-details>1</edit-user-details>
<location-mandatory>0</location-mandatory>
<auto-attendance>0</auto-attendance>
<attendance-period>0</attendance-period>
<month-start-end />
<events>1</events>
<holiday-schedule>1</holiday-schedule>
<user-basic-details>1</user-basic-details>
<visitor-preregistration>1</visitor-preregistration>
<daily-attendance>1</daily-attendance>
<attendance-summary>1</attendance-summary>
<attendance-details>1</attendance-details>
<shift-schedule>1</shift-schedule>
<short-leave>1</short-leave>
<attendance-correction>1</attendance-correction>
<leave-balance>1</leave-balance>
<leave-application>1</leave-application>
<tour-application>1</tour-application>
<coff-application>1</coff-application>
<account>1</account>
<menu>1</menu>
<expenditure>1</expenditure>
<transaction-correction>1</transaction-correction>
<group-summary>0</group-summary>
<member-daily-attendance>0</member-daily-attendance>
<member-events>0</member-events>
<member-attendance>0</member-attendance>
<attendance-authorization>0</attendance-authorization>
<short-leave-authorization>0</short-leave-authorization>
<overtime-authorization>0</overtime-authorization>
<leave-approval>0</leave-approval>
<tour-approval>0</tour-approval>
<attendance-correction-authorization>0</attendance-correction-authorization>
<coff-approval>0</coff-approval>
<visitor-preregistration-approval>0</visitor-preregistration-approval>
<cosec-version>V09R01</cosec-version>
</LoginUserDetail>
</DocumentElement>

378 Matrix COSEC Web API User Guide

CHAPTER 18 Password

Changing Password

This API can be used by an ESS user to change the login password.

Action

action=set

Syntax

http://<servername>/api.svc/v2/change-password?action=set;<argument>=<value>…

User Rights

User Rights

System Account Disabled

ESS Enabled

Parameters

Table: Changing Password - Parameters

Argument Valid Values Mandatory Default Value Description

Maximum 15
userid Yes - This is the ESS user’s ID.
characters

When user applies for new password,

he should be asked to enter his
birthdate, and the same should be
birthdate ddmmyyyy Yes - supplied in this parameter. Birthdate
entered by the user will be
authenticated against the birthdate
stored in COSEC database.

upto 40 characters. This will be the IMEI number of the

mobile device on which the ESS
Allowed characters: application is being used. IMEI number
imei Yes -
supplied here will be authenticated
Alphanumeric against the number stored in COSEC
- DB.

Matrix COSEC Web API User Guide 379

Table: Changing Password - Parameters

Argument Valid Values Mandatory Default Value Description

0 means that we need to verify the user

1 means that we do not need to verify
the user

To be considered only when type=1(set

password)
If user verified for password = 0, it
user-verified-for- 0= Not Verified means that Server needs to generate
0
password 1= Verified mobile and email OTP and then send it
to the particular user’s contact details.
Send Success response with message
“OTP generated successfully”.

If user verified for password = 1, it

means that Server need not generate
OTP and should allow the user to set
his password without OTP verification

If encryption=0, password will not be

0 : No Encryption
decrypted by server.
encryption (Plain Text Password) No 0 (no encryption)
If encryption=1, password will be
1: RSA Encryption
decrypted using Public encryption key.

The new password submitted by the

user will be supplied here.
If encryption=1, Password must be
encrypted using the public encryption
Will depend on key.
new-password Yes -
encryption method New-password field should be encoded
string to allow special characters in
URL. The maximum length for value
entered for new password is 200
characters.

0 means the API is being used by the

0= change password user for changing his password.
type No -
1= set password 1 means the API is being used by the
user for setting his password.

For this API, the request header should contain the user’s existing credentials.

For any subsequent API requests, the new password should be submitted.

Password Change Process:

• The request will contain user id parameter
• Validate the API request parameters. It should have user-id, birthdate and IMEI number when type=0 and
user-id and new password when type=1:
• If the birthdate is invalid or not as per specified ddmmyyyy format, return message: “Invalid birthdate.”
• If there is a mismatch in birthdate, return message : “In-correct Birthdate”
• If the IMEI is invalid or not as per specified format, return message: “Invalid IMEI number.”
• If there is a mismatch in IMEI, return message: “Unrecognized Device.”

380 Matrix COSEC Web API User Guide

 • If the birthdate and IMEI number supplied in the request matches with that stored in DB, save the new
password
• The new password mentioned in the request, should be decoded first.
• Then if encryption=1, it should be decrypted using the public encryption key.
• Then it should be hashed and encrypted as per existing policy, and saved in the DB.
• “Success: Password Changed successfully” message will be returned.
• For any subsequent API requests, the new password should be submitted.
• When the “Deny Password Reuse” flag is enabled on the server and the user tries to resuse a previuos
password give error “New password should not be same as last “x” old passwords.”

Generating Password

This API shall be used to set a new password for an ESS user. A new password needs to be set in the following
situation:
• If user forgets his password, and requests server for a new password.
• If a password has not been set by the user.

Action

action=set

Syntax

http://<servername>/api.svc/v2/generate-password?action=set;<argument>=<value>…

User Rights

User Rights

System Account Disabled

ESS Disabled

For this API, the request header should contain following credentials :
username : MatrixAdmin
password : admin

Parameters

Table: Generating Password - Parameters

Argument Valid Values Mandatory Default Value Description

Maximum 15
userid Yes - This is the ESS user’s ID.
characters

When user applies for new password,

he should be asked to enter his
birthdate, and the same should be
birthdate ddmmyyyy Yes - supplied in this parameter. Birthdate
entered by the user will be
authenticated against the birthdate
stored in COSEC database.

Matrix COSEC Web API User Guide 381

Table: Generating Password - Parameters

Argument Valid Values Mandatory Default Value Description

upto 40 characters. This will be the IMEI number of the

mobile device on which the ESS
Allowed characters: application is being used. IMEI number
imei Yes -
supplied here will be authenticated
Alphanumeric against the number stored in COSEC
- DB.

The new password will be a randomly generated 8-digit number.

It will be sent to the user's registered Email ID and/or mobile number through the alert.

382 Matrix COSEC Web API User Guide

CHAPTER 19 Encryption Key

This API enables you to retrieve the RSA encryption public key for password encryption from the COSEC server.

Action

action=get

Syntax

http://<servername>/api.svc/v2/encryption-key?action=get;<argument>=<value>...

User Rights

Not Applicable. No COSEC login credentials are required to use this API. Use:

userid = anonymous-user
password = anonymous.

Response Fields

Table: Getting Password Encryption Key - Response Fields

Field Name Tag Name Valid Values Remarks

Modulus modulus N/A N/A

Exponent exponent N/A N/A

The password encryption key will be case-sensitive.

Matrix COSEC Web API User Guide 383

384 Matrix COSEC Web API User Guide
CHAPTER 20 IMEI Registration

This API can be used to register the IMEI number for any new mobile device on which ESS application needs to be
used.

Action

action=set

Syntax

http://<servername>/api.svc/v2/imei-registration?action=set;<argument>=<value>...

User Rights

User Rights

System Account Disabled.

ESS Enabled.

Parameters

Table: IMEI Number Registration - Parameters

Argument Valid Values Mandatory Default Value Description

userid upto 15 characters Yes - This will be the login user’s ID.

upto 40 characters.
This will be the IMEI number of the
Allowed characters:
imei Yes - mobile device to be registered for
accessing ESS application.
Alphanumeric
-

Matrix COSEC Web API User Guide 385

386 Matrix COSEC Web API User Guide
CHAPTER 21 Location Master

This API can be used to send the Location master details as configured on COSEC server to COSEC mobile
applications. The location master will contain Latitude-Longitude, Wi-Fi and Bluetooth details which can uniquely
identify a location.

Action

action=get

Syntax

http://<servername>/api.svc/v2/location-master?action=get;<argument>=<value>...

User Rights

User Rights

System Account Enabled.

User must have rights on following pages (COSEC Web Application):

Admin > System Configuration > Location Master

ESS Enabled.

When Logged-IN User is System Account User, fetch all configured locations as per request.

"When Logged-IN User is ESS User,

1. If "Location Mandatory for Punch" is selected as 'None' or 'Any Location' against logged in user, fetch all
configured locations as per request.

2.If "Location Mandatory for Punch" is selected as 'None' or 'Any Location' or 'Assigned Locations Only'
against logged in user, return response will contain only those locations which are assigned to user.Also
locations belong to assigned location group(s). When a location belongs to multiple location groups, it will
be returned only once.

Matrix COSEC Web API User Guide 387

Parameters

Table: Location Master - Parameters

Argument Valid Values Mandatory Default Value Description

Time must be in 24 hour format only.

Time-stamp will contain, the time when

location master was fetched by the
client application.

If time-stamp is blank, then response

will contain all the records from location
master.

Is time-stamp < location master update

time-stamp ddmmyyyyHHMM No -
time, it implies that the master has
been updated after the client fetched it.
Hence response will contain all the
locations form location master.

If time-stamp>= location master update

time, then it implies that the client
application has the latest location
master. (i.e. no updates occurred after
the last get request).

15 alphanumeric
Char. (for user)
A to Z Userid is to be passed through this
id No
a to z parameter.
0 to 9
/_\\.@:

Response Fields

Table: Location Master- Response

Field Name Tag Name Valid Values Remarks

6 alpha-numeric characters.

Code code

Allowed Characters
A-Z
Location Name
name a-z 50 characters
0-9
-_. ()[]

Latitude latitude -90.0000 to 90.0000 9 characters (max.)

-180.0000 to
Longitude longitude 9 characters (max.)
180.0000

Range : 10 meters to 10000

Location Radius radius 10 - 10000 metres
meters

17 characters (each byte

MAC Address mac separated by colon)

388 Matrix COSEC Web API User Guide

Table: Location Master- Response

Field Name Tag Name Valid Values Remarks

0 : GPS
1 : Wi-Fi
Type type
2 : BLE-Beacon
3 : BLE-Device

Will return the BLE Code

BLE Code ble-code 0-9999
assigned to a specific location

Allowed Characters
A-Z 10 alphanumeric characters
BLE Name ble-name
a-z (max.)
0-9

A-Z
a-z
Address address 0-9 125 chars
!@#$*()_-+[]\:
, . / and space

0 : Attendance
mode mode 1 : Access Control
2 : Both

MID 0-65535 (Direct Door

Mid MID of the device
or Panel200)

1 to 255 (Panel200 DID of the device if device is a

DID Did
Door) panel door

Should support IP
IP of Panel if device= panel door
address or Domain
IP ip IP of Direct Door if device = direct
Name of Device upto
door
40 characters

5 Characters Should return configured Device

Port port
Range = 1-65535 Port value

0: Entry Returns the type of event

Event_type Event_type
1: Exit configured for specific location

Matrix COSEC Web API User Guide 389

390 Matrix COSEC Web API User Guide
CHAPTER 22 COSEC Server Details

This API can be used to send the COSEC Server Details to COSEC Mobile applications. The Server Details will
contain COSEC-Version and Server-Timestamp parameters.

Action

action=get

Syntax

http://<matrixserver>/api.svc/v2/server-details?action=<get>;<argument>=<value>...

User Rights

User Rights

System Account Enabled.

ESS Enabled.

Response Fields

Table: Getting COSEC Server’s Details - Response Fields

Field Name Tag Name Valid Values Remarks

Cosec Server Version cosec-server-version - -

Server Timestamp server-time dd/mm/yyyy HH:MM:SS -

User Last Modified user-last-modified dd/mm/yyyy HH:MM:SS -

User Last Deleted user-last-deleted dd/mm/yyyy HH:MM:SS -

0: Off
Support Multi-Language Input Support-multi-language-input -
1: On

0: Left To Right
Input Alignment Input-alignment -
1: Right To Left

Matrix COSEC Web API User Guide 391

Table: Getting COSEC Server’s Details - Response Fields

Field Name Tag Name Valid Values Remarks

Return COSEC Web

Server's Time Zone Offset
for the Tenant.
Format:
Server Time Zone server-timezone
±HH:MM
Example: In case of IST
return:
+05:30

0: System Account User Return logged in user's

Logged-in User logged-in-user
1: ESS User type

Return Universal Time

UTC UTC Format: dd/mm/yyyy HH:MM:SS
Coordinates.

Allow E-Pass Generation allow-epass-generation- 0-999 Return the value of this

Before Duration before-duration (Time in Minutes) textbox

Default-Host-User-ID default-host-user-id max 45 alphanumeric characters

Default-Host-User-Name default-host-user-name max 15 characters

Return this as 1 if the

logged in user is a System
0: No Account User with Role
Security Guard security-guard
1: Yes assigned Rights of VMS
Utility.
Otherwise return 0.

0:Unchecked Displays the respective

Official Work IN official-work-in 1:Checked values set in
GSYSPLCMst table.

Displays the respective

0:Unchecked
Official Work OUT official-work-out values set in
1:Checked
GSYSPLCMst table.

Displays the respective

0:Unchecked
Short Leave IN short-leave-in values set in
1:Checked
GSYSPLCMst table

Displays the respective

0:Unchecked
Short Leave OUT short-leave-out values set in
1:Checked
GSYSPLCMst table

Displays the respective

0:Unchecked
Break End break-end values set in
1:Checked
GSYSPLCMst table

Displays the respective

0:Unchecked
Break Start Break-start values set in
1:Checked
GSYSPLCMst table

Displays the respective

Overtime IN 0:Unchecked
overtime-in values set in
1:Checked
GSYSPLCMst table

Displays the respective

0:Unchecked
Overtime OUT overtime-out values set in
1:Checked
GSYSPLCMst table

392 Matrix COSEC Web API User Guide

Table: Getting COSEC Server’s Details - Response Fields

Field Name Tag Name Valid Values Remarks

Displays the respective

0:Unchecked
Regular IN regular-in values set in
1:Checked
GSYSPLCMst table

Displays the respective

0:Unchecked
Regular OUT regular-out values set in
1:Checked
GSYSPLCMst table

APTA Face Anti-Spoofing 0:Advance Returns value from Global

apta-face-anti-spoofing-mode
Mode 1:Moderate Policy > Face Recognition

APTA Face Anti-Spoofing apta-face-anti-spoofing- 1 to 99 , . Returns value from Global

Threshold threshold (5 numeric char max) Policy > Face Recognition

Matrix COSEC Web API User Guide 393

394 Matrix COSEC Web API User Guide
CHAPTER 23 Field Visit Management

The following APIs enable the user to perform actions related to Field Visit Management -

Action=Get
• Getting Field Visit Schedule

• Getting Field Visit Punches

• Getting Field Visit Correction

Action=Set

• Applying for Field Visit Correction

• Authorizing Field Visit Correction Applications

Action=Delete

• Deleting Field Visit Correction Application

Matrix COSEC Web API User Guide 395

Getting Field Visit Schedule

This API can be used to fetch the user's assigned Field Visit Schedule for specified date-range.

Action

action=get

Syntax

http://<matrixserver>/api.svc/v2/field-visit-schedule?action=<get>;<argument>=<value>...

User Rights

User Rights

System Account Enabled.

ESS Enabled.

Parameters

Table: Getting Field Visit Schedule Records- Parameters

Argument Valid Values Mandatory Default Value Description

Userid 15 alphanumeric Yes - System should allow user to select

Char. (for user) multiple id, each separated by ",
A to Z (comma)"
a to z For example "1, 3, 7, 9…".
0 to 9
/_\\.@: In case userid is provided along with id/
id & range, priority should always be
given to userid. Value of id/id & range to
be ignored in that case.

date-range ddmmyyyy-ddmmyyyy - Current date records The period for which field visit schedule
records is to be requested.

All In this argument only single value

Organization should be allowed.
Branch
Department If argument range's value is specified
Designation as "All", ids of all the users that login
Section User (If argument user has rights over will return.
Range No
Category Range is not specified)
Grade In case user-id /user-id & user-filter are
User provided along with id/id & range,
Custom-group-1 priority should always be given to user-
Custom-group-2 id / user-id & user-filter. Value of id/id &
custom-group-3 range to be ignored in that case.

396 Matrix COSEC Web API User Guide

Table: Getting Field Visit Schedule Records- Parameters

Argument Valid Values Mandatory Default Value Description

If argument range is not mentioned and

individual argument ID is specified,
1 to 999999 (for all the then id should be considered of User.
ranges except all &
user) Argument ID can have multiple ids as
Max 15 alphanumeric value with comma separated. For
ID characters (for user) Yes - example Id=1,2,…..999.
A to Z
a to z In case user-id /user-id & user-filter are
0 to 9 provided along with id/id & range,
/_\\.@: priority should always be given to user-
id / user-id & user-filter. Value of id/id &
range to be ignored in that case.

Response Fields

Table: Getting Field Visit Schedule Records - Response Fields

Field Name Tag Name Valid Values Remarks

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

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

Short Name short-name max 15 alphanumeric characters

Schedule date schedule-date mm/dd/yyyy

Start Date Time schedule-start mm/dd/yyyy HH:MM

End Date Time schedule-end mm/dd/yyyy HH:MM

Task ID task-id 6 characters Allowed Characters 0-9

Allowed Characters A-Z

a-z
Task Name task-name 30 characters
0-9
-_. ()[]

Allowed Characters
A-Z
Location Code location-code 6 characters
a-z
0-9

Matrix COSEC Web API User Guide 397

Table: Getting Field Visit Schedule Records - Response Fields

Field Name Tag Name Valid Values Remarks

Allowed Characters
A-Z
Location Name location-name 50 characters a-z
0-9
-_. ()[]

Allowed Characters
Location Group ID location-group-id 6 characters
0-9

Allowed Characters
A-Z
Location Group Name location-group-name 50 characters a-z
0-9
-_. ()[]

Allowed Characters
A-Z
Remark remark 50 characters a-z
0-9
!@#$&*()_-+[]\:,./

Allowed Characters
A-Z
Scheduled By scheduled-by 10 characters a-z
0-9
/_\\.@:

0: Failure
Transaction Status status
1: Success

Example

Sample Request:

http://matrix-server/api.svc/v2/field-visit-schedule?action=get;userid=1234,5678;date-range=01092015-
02092015

398 Matrix COSEC Web API User Guide

Getting Field Visit Punches

This API shall be used to get the FVM user's FVM punches as per specified Process Date range.

Action

action=get

Syntax

http://<matrixserver>/api.svc/v2/field-visit-punch?action=<get>;<argument>=<value>...

User Rights

User Rights

System Account Enabled.

ESS Enabled.

Parameters

Table: Getting FVM Punches- Parameters

Argument Valid Values Mandatory Default Value Description

Userid 15 alphanumeric Yes - To specify the user identification

Char. (for user) number. Multiple IDs can be selected,
A to Z separated by a ‘comma’. E.g.
a to z “Userid=1,3,7,9...”
0 to 9
/_\\.@: In case userid is provided along with id/
id & range, priority should always be
given to userid. Value of id/id & range to
be ignored in that case.

date-range ddmmyyyy-ddmmyyyy - Current date records The period for which field visit schedule
records is to be requested.

All In this argument only single value

Organization should be allowed.
Branch
Department If argument range's value is specified
Designation as "All", ids of all the users that login
Section User (If argument user has rights over will return.
Range No
Category Range is not specified)
Grade In case user-id /user-id & user-filter are
User provided along with id/id & range,
Custom-group-1 priority should always be given to user-
Custom-group-2 id / user-id & user-filter. Value of id/id &
custom-group-3 range to be ignored in that case.

Matrix COSEC Web API User Guide 399

Table: Getting FVM Punches- Parameters

Argument Valid Values Mandatory Default Value Description

If argument range is not mentioned and

individual argument ID is specified,
1 to 999999 (for all the then id should be considered of User.
ranges except all &
user) Argument ID can have multiple ids as
Max 15 alphanumeric value with comma separated.
ID characters (for user) Yes - For example Id=1,2,…..999.
A to Z
a to z In case user-id /user-id & user-filter are
0 to 9 provided along with id/id & range,
/_\\.@: priority should always be given to user-
id / user-id & user-filter. Value of id/id &
range to be ignored in that case.

Response Fields

Table: FVM Punches - Response Fields

Field Name Tag Name Valid Values Remarks

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

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

Short Name short-name max 15 alphanumeric characters

Attendance Date attendance-date mm/dd/yyyy

Punch Time punch-time mm/dd/yyyy HH:MM:SS

0-In
IO Type iotype
1-Out

Special Function ID spfid numeric

Punch Date Index punch-index numeric

Allowed Characters
A-Z
Location Code location-code 6 characters alpha-numeric
a-z
0-9

Allowed Characters
A-Z
Location Name location-name 50 characters a-z
0-9
-_. ()[]

400 Matrix COSEC Web API User Guide

Table: FVM Punches - Response Fields

Field Name Tag Name Valid Values Remarks

When location is
calculated via GPS. This
Location GPS Latitude gps-latitude 11 characters parameter will contain :
latitude
Example: -77.008123

When location is
calculated via GPS. This
Location GPS Longitude gps-longitude 11 characters parameter will contain :
longitude
Example: -38.889712

When location is
calculated via GSM. This
Location GSM Latitude gsm-latitude 11 characters
parameter will contain :
latitude

When location is
calculated via GSM. This
Location GSM Longitude gsm-longitude 11 characters
parameter will contain :
longitude

When location is
calculated via Wi-Fi. This
Location MAC Address mac-address 17 characters
parameter will contain :
MAC Address of Source

Allowed Characters
0-9
A-Z
Comment comment 50 characters
a-z
!@#$*()_-+[]\:,./
and space

Allowed Characters
BLE Code ble-code 4 characters numeric
0-9

Allowed Characters 10 alphanumeric

A-Z characters (max.)
BLE Name ble-name
a-z If not available, return
0-9 blank

Example

Sample Request:

http://matrix-server/api.svc/v2/field-visit-punch?action=get;userid=1234;date-range=01092015-01102015

Matrix COSEC Web API User Guide 401

Getting Field Visit Correction

This can be used to get the FVM user's field application data for the specific date period.

Action

action=get

Syntax

http://<matrixserver>/api.svc/v2/field-visit-correction?action=<get>;<argument>=<value>...

User Rights

User Rights

Enabled.

The user must have rights on the either of the following pages:
System Account
FVM > Utilities > Field Visit Correction
FVM > Utilities > Field Visit Correction Authorization

Enabled.

The user must have rights on the either of the following ESS pages:
ESS
ESS > Approval/Authorization > Field Visit Correction Authorization
ESS > FVM > Field Visit Correction

Parameters

Table: Getting Field Visit Correction Application Details- Parameters

Argument Valid Values Mandatory Default Value Description

user-filter 0: individual - 0 user-filter=0 will fetch single user’s

1: group record and user-filter=1 will fetch all
users’ records.

Note: user-filter=1, is applicable if login

user is a reporting in-charge or system
account user.

When argument Range & Id or Id is

mentioned and argument user-id is not
provided , default value user-filter=0
should not be considered

Argument user-filter should only be

applied when argument user-id is
provided, else it should be ignored.

402 Matrix COSEC Web API User Guide

Table: Getting Field Visit Correction Application Details- Parameters

Argument Valid Values Mandatory Default Value Description

userid 15 alphanumeric Yes - To specify the user identification

Char. (for user) number. Multiple IDs can be selected,
A to Z separated by a ‘comma’. E.g.
a to z “Userid=1,3,7,9...”
0 to 9
/_\\.@: In case userid & user-filter are provided
along with id/id & range, priority should
always be given to userid & user-filter.
Value of id/id & range to be ignored in
that case.

date-range ddmmyyyy-ddmmyyyy - Current date records The period for which correction
applications are to be fetched.

Application-status 0: all - All To view the status of field visit

1: pending correction application.
2: approved
3: rejected

All In this argument only single value

Organization should be allowed.
Branch
Department If argument range's value is specified
Designation as "All", ids of all the users that login
Section User (If argument user has rights over will return.
Range No
Category Range is not specified)
Grade In case user-id /user-id & user-filter are
User provided along with id/id & range,
Custom-group-1 priority should always be given to user-
Custom-group-2 id / user-id & user-filter. Value of id/id &
Custom-group-3 range to be ignored in that case.

If argument range is not mentioned and

individual argument ID is specified,
1 to 999999 (for all the then id should be considered of User.
ranges except all &
user) Argument ID can have multiple ids as
Max 15 alphanumeric value with comma separated. For
ID characters (for user) Yes - example Id=1,2,…..999.
A to Z
a to z In case user-id /user-id & user-filter are
0 to 9 provided along with id/id & range,
/_\\.@: priority should always be given to user-
id / user-id & user-filter. Value of id/id &
range to be ignored in that case.

Response Fields

Table: Getting Field Visit Correction Application Details - Response Fields

Field Name Tag Name Valid Values Remarks

Application Id application-id 10 numeric characters

mm/dd/yyyy
Applied Date and Time applied-date
HH:MM:SS

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

Matrix COSEC Web API User Guide 403

Table: Getting Field Visit Correction Application Details - Response Fields

Field Name Tag Name Valid Values Remarks

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

Short Name short-name max 15 alphanumeric characters

1: pending
Application Status application-status 2: approved
3: rejected

Attendance Date attendance-date mm/dd/yyyy

Punch Index punch-index numeric

mm/dd/yyyy
Previous Punch Time previous-punch-time
HH:MM:SS

0: IN
Previous IO Type previous-iotype
1: OUT

Allowed Characters
A-Z
Previous Location Code previous-location-code 6 characters alpha-numeric
a-z
0-9

Allowed Characters
A-Z
Previous Location Name previous-location-name 50 characters a-z
0-9
-_. ()[]

When location is
calculated via GPS. This
Previous Location GPS
previous-gps-latitude 11 characters parameter will contain :
Latitude
latitude
Example: -77.008123

When location is
calculated via GPS. This
Previous Location GPS
previous-gps-longitude 11 characters parameter will contain :
Longitude
longitude
Example: 38.889712

When location is
Previous Location GSM calculated via GSM. This
previous-gsm-latitude 11 characters
Latitude parameter will contain :
latitude

When location is
Previous Location GSM calculated via GSM. This
previous-gsm-longitude 11 characters
Longitude parameter will contain :
longitude

When location is
Previous Location MAC calculated via Wi-Fi. This
previous-mac-address 17 characters
Address parameter will contain :
MAC Address of Source

404 Matrix COSEC Web API User Guide

Table: Getting Field Visit Correction Application Details - Response Fields

Field Name Tag Name Valid Values Remarks

Allowed Characters
A-Z
a-z
Previous Comment previous-comment 50 characters
0-9
-.,[]():@$!#*+/\_
[space]

mm/dd/yyyy
Changed Punch Time changed-punch-time
HH:MM:SS

0: IN
Changed IO Type changed-iotype
1: OUT

Allowed Characters
A-Z
Changed Location Code changed-location-code 6 characters alpha-numeric
a-z
0-9

Allowed Characters
A-Z
Changed Location Name changed-location-name 50 characters a-z
0-9
-_. ()[]

Allowed Characters
A-Z
a-z
Changed Comment changed-comment 50 characters
0-9
-.,[]():@$!#*+/\_
[space]

Allowed Characters
A-Z
a-z
Application Reason reason 50 characters
0-9
-.,[]():@$!#*+/\_
[space]

mm/dd/yyyy
Application Verdict Date Time verdict-date
HH:MM

Shows User-ID who

Application Verdict By verdict-by 10 characters approved/rejected the
application.

Allowed Characters
A-Z
a-z
Application Approval Remark application-remark Max 50 chars
0-9
-.,[]():@$!#*+/\_
[space]

Allowed Characters
Previous BLE Code previous-ble-code 4 characters numeric
0-9

Allowed Characters 10 alphanumeric

A-Z characters (max.)
Previous BLE Name previous-ble-name
a-z If not available, return
0-9 blank

Matrix COSEC Web API User Guide 405

Table: Getting Field Visit Correction Application Details - Response Fields

Field Name Tag Name Valid Values Remarks

Max 15 chars

Allowed Characters
Final RIC ID final-ric A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Final RIC Name final-ric-name
a-z
0-9
-_. ()[]

1: pending Provides status of

Final RIC Verdict final-ric-verdict
2: authorized application.

Max 15 chars

Allowed Characters
Non-Final RIC ID nonfinal-ric A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC Name nonfinal-ric-name
a-z
0-9
-_. ()[]

Non-Final RIC Verdict Date MM/DD/YYYY

nonfinal -ric-verdict-date
Time HH:MM

1: pending
Non-Final RIC Verdict nonfinal -ric-verdict
2: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC Remark nonfinal-ric-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC2 ID nonfinal-ric2 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC2 Name nonfinal-ric2-name
a-z
0-9
-_. ()[]

Non-Final RIC2 Verdict Date MM/DD/YYYY

nonfinal-ric2-verdict-date
Time HH:MM

1: pending
Non-Final RIC2 Verdict nonfinal-ric2-verdict
2: authorized

406 Matrix COSEC Web API User Guide

Table: Getting Field Visit Correction Application Details - Response Fields

Field Name Tag Name Valid Values Remarks

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC2 Remark nonfinal-ric2-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC3 ID nonfinal-ric3 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC3 Name nonfinal-ric3-name
a-z
0-9
-_. ()[]

Non-Final RIC3 Verdict Date MM/DD/YYYY

nonfinal-ric3-verdict-date
Time HH:MM

1: pending
Non-Final RIC3 Verdict nonfinal-ric3-verdict
2: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC3 Remark nonfinal-ric3-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC4 ID nonfinal-ric4 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC4 Name nonfinal-ric4-name
a-z
0-9
-_. ()[]

Non-Final RIC4 Verdict Date MM/DD/YYYY

nonfinal-ric4-verdict-date
Time HH:MM

1: pending
Non-Final RIC4 Verdict nonfinal-ric4-verdict
2: authorized

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC4 Remark nonfinal-ric4-remark
a-z
0-9
_.,()[]:@!#$*+/\

Matrix COSEC Web API User Guide 407

Example1

Sample Request:

To get pending application details for specified user.

http://192.168.104.12/cosec/api.svc/v2/field-visit-correction?action=get;user-filter=0;userid=FVM1;date-range=21052018-
25052018;Application-status=1

Sample Response:

application-id|applied-date|user-id|user-name|short-name|application-status|attendance-date|punch-index|previous-punch-
time|previous-iotype|previous-location-code|previous-location-name|previous-gps-latitude|previous-gps-longitude|previous-gsm-
latitude|previous-gsm-longitude|previous-mac-address|previous-comment|changed-punch-time|changed-iotype|changed-location-
code|changed-location-name|changed-comment|reason|verdict-date|verdict-by|application-remark|previous-ble-code
1|05/21/2018 14:46:58|FVM1|Jinu|Jinu|1|05/21/2018|1|05/21/2018 12:30:00|0|HO|Head Ofc|+22.2563|+073.1833|||||05/21/2018
12:35:00|0|HO|Head Ofc|Sample delivered|Applied Field Visit Correction||||
<EOT

408 Matrix COSEC Web API User Guide

Applying for Field Visit Correction

This API is to submit new field visit correction applications.

Action

action=set

Syntax

http://<matrixserver>/api.svc/v2/field-visit-correction?action=<set>;<argument>=<value>...

User Rights

User Rights

Enabled.

The user must have rights on the either of the following pages:
System Account
FVM > Utilities > Field Visit Correction
FVM > Utilities > Field Visit Correction Authorization

Enabled.

The user must have rights on the either of the following ESS pages:
ESS
ESS > Approval/Authorization > Field Visit Correction Authorization
ESS > FVM > Field Visit Correction

Parameters

Table: Applying for Field Visit Correction Application- Parameters

Argument Valid Values Mandatory Default Value Description

userid 15 Char Yes - To specify the user identification

number.

attendance-date ddmmyyyy Yes - The date for which correction

application is made.

punch-index numeric No - If supplied consider change to be done

in existing FVM Punch.
If not supplied consider as new FVM
punch to be added.

punch-time ddmmyyyyHHMMSS Yes if punch- - It is the punch time of FVM user.

index is not
specified

iotype 0: IN Yes if punch- All It specifies the input/output type of the

1: OUT index is not FVM punch.
specified and
exit reader is
enabled

Matrix COSEC Web API User Guide 409

Table: Applying for Field Visit Correction Application- Parameters

Argument Valid Values Mandatory Default Value Description

location-code 6 Characters No - Location Code is from configured

A-Z location master.
a-z
0-9

comment 50 Characters No - Comment has to max 50 characters

A-Z long
a-z
0-9
-.,[]():@$!#*+/\
_
[space]

reason 50 Characters No - Reason has to max 50 characters long

A-Z
a-z
0-9
-.,[]():@$!#*+/\
_
[space]

authorization-required 0: not required No 0 (Not required) Applicable for System Account User
1: required only.

If authorization required = 1, then the

application will be considered as
applied by an ESS User (UserID
mentioned in API.)

Example1

Following are some sample cases for this API:

Sample Request:

To apply for Field Visit correction application for a user from system account login mentioning the requirement of
authorization:

http://192.168.104.12/cosec/api.svc/v2/field-visit-correction?action=set;userid=FVM1;attendance-
date=12022018;punch-time=12022018143500;iotype=0;location-code=HO;authorization-required=1

Sample Response:

success: 0710200002 : saved successfully

410 Matrix COSEC Web API User Guide

Authorizing Field Visit Correction Applications

This API will be used by a COSEC reporting-incharge user to approve/reject the field visit correction applications submitted by a
particular user.

Action

action=set

Syntax

http://<matrixserver>/api.svc/v2/field-visit-correction-
authorization?action=<set>;<argument>=<value>...

User Rights

User Rights

Enabled.

System Account The user must have rights on the following page:

FVM > Utilities > Field Visit Correction Authorization

Enabled.

ESS If Login User is a reporting group in-charge and has the permissions on following page:

ESS > Approval/Authorization > Field Visit Correction Authorization

Parameters

Table: Authorizing Field Visit Correction Application- Parameters

Argument Valid Values Mandatory Default Value Description

Userid 15 Char Yes - To specify the user identification

number.

application-id numeric Yes - User Id must belong to the user’s

reporting group. You can get
application ID by using API “Getting
Field Visit Correction”

Verdict 1: Approve Yes - User cannot approve/reject a record

2: Reject which is already approved/rejected.
Closed period data cannot be edited.

Remark Max 50 Char No -

Alphabets
Remark should not be beyond max limit
Numbers
_-()[].,/\ +!@$*
: and <space>

Matrix COSEC Web API User Guide 411

Example1

Sample Request:

To give the verdict for Field visit correction application.

http://192.168.104.12/cosec/api.svc/v2/field-visit-correction-authorization?action=set;
Userid=FVM1;application-id=1;Verdict=1;Remark=Correction Approved;

Sample Response:

success: 0720200002 : saved successfully

The FVM correction application will be shown in Approved/Rejected section after the verdict is given.

412 Matrix COSEC Web API User Guide

Deleting Field Visit Correction Application

This API is to delete the field visit correction applications.

Action

action=delete

Syntax

http://<matrixserver>/api.svc/v2/field-visit-correction?action=<delete>;<argument>=<value>...

Parameters

Table: Deleting Field Visit Correction Application- Parameters

Argument Valid Values Mandatory Default Value Description

application-id numeric Yes - The approved/rejected application

cannot be deleted. Only Pending
application can be deleted.

Matrix COSEC Web API User Guide 413

414 Matrix COSEC Web API User Guide
CHAPTER 24 Job Processing and Costing

The following API enable the user to perform actions related to Job Processing and Costing. This is used to get list
of jobs as per existing Job master, process the job costing of user.

Action= Get
• Getting Jobs list
• Timesheet details
• Get Timesheet Correction Application

Action= Command
• Job Costing Process

Action= Set
• Timesheet Correction Application
• Timesheet Correction Authorization

Matrix COSEC Web API User Guide 415

Getting Jobs list

This API is used to get list of Jobs as per existing Job Master.

Action

action=get

Syntax

http://<matrixserver>/api.svc/v2/job?action=<get/set>;<argument>=<value>...

User Rights

User Rights

System Account Enabled.

ESS User Enabled If User’s Job Assignment type is not None

Parameters

Table: Getting jobs list- Parameters

Argument Valid Values Mandatory Default Value Description

Id 1-4294967295 - All To specify the user identification

number. Multiple IDs can be selected,
separated by a ‘comma’. E.g.
“1,3,7,9...”

status 0: All All -

1: Open
2: In Progress
3: Finished

ess-assignment 0 : All Jobs in the Job No By default if the parameter is not

Master mentioned than the value should be
1 : All Jobs in the User considered as 0 i.e. All Jobs in the Job
Master Master.
2 : Enabled Jobs for
ESS Assignment When value = 0 all the jobs in the
system should be sent in response

When value = 1 all the jobs assigned to

the ESS user whose credentials are fed
while firing the API should be sent in
response

When value = 2 the jobs assigned to

the ESS user(credentials are fed while
firing the API) whose ess assignment
flag is enabled should be sent in
response

If the parameter named Show all Jobs

while Punching is enabled in global
policy then this parameter would be
ignored.

416 Matrix COSEC Web API User Guide

Response Fields

Table: Getting Jobs List - Response Fields

Field Name Tag Name Valid Values Remarks

ID id 1 - 4294967295

Allowed Characters
A-Z,
Job Code job-code 10 characters (max) a-z
0-9
.-_()

Allowed Characters
A-Z
Job Name job-name 30 characters a-z
0-9
-_. ()[]

Allowed Characters
A-Z,
Phase Code phase-code 10 characters (max) a-z
0-9
.-_()

Allowed Characters
A-Z
Phase Name phase-name 30 characters a-z
0-9
-_. ()[]

Allowed Characters
A-Z,
Project Code project-code 10 characters (max) a-z
0-9
.-_()

Allowed Characters
A-Z
Project Name project-name 30 characters a-z
0-9
-_. ()[]

Cost Centre ID cost-centre-id 1-99999

Allowed Characters
A-Z
Cost Centre Name cost-centre-name 30 characters a-z
0-9
-_. ()[]

Job Start Date start-date mm/dd/yyyy

Job End Date end-date mm/dd/yyyy

Estimated Hours estimated-hours 1-99999

0= no
Merge Jobs merge-jobs
1= yes

Matrix COSEC Web API User Guide 417

Table: Getting Jobs List - Response Fields

Field Name Tag Name Valid Values Remarks

0 = no
Allowance allowance
1 = yes

418 Matrix COSEC Web API User Guide

Timesheet details

This API is used to get the user's timesheet data for the specific date period.

Action

action= get

Syntax

http://<matrixserver>/api.svc/v2/timesheet?action=<get>;<argument>=<value>...

User Rights

User Rights

System Account Enabled If User has rights on any of the following Page.
JPC > Utilities> Timesheet Correction
JPC > Utilities> Timesheet Correction Authorization

ESS User Enabled if User has rights on any of the following Page.
ESS > Approval/Authorization > Timesheet Correction Authorization
ESS > Approval/Authorization > Award/Penalty Authorization
ESS > Job Costing > Timesheet Correction Application

Parameters

Table: Timesheet correction authorization- Parameters

Argument Valid Values Mandatory Default Value Description

User-id 15 alphanumeric Yes - To specify the ID of the user.

Char. (for user)
A to Z In case userid is provided along with id/
a to z id & range, priority should always be
0 to 9 given to userid. Value of id/id & range to
/_\\.@: be ignored in that case.

date-range ddmmyyyy-ddmmyyyy No - To specify the period for which the

Timesheet details are to be fetched.

All In this argument only single value

Organization should be allowed.
Branch
Department If argument range's value is specified
Designation as "All", ids of all the users that login
Section User (If argument user has rights over will return.
Range No
Category Range is not specified)
Grade In case user-id /user-id & user-filter are
User provided along with id/id & range,
Custom-group-1 priority should always be given to user-
Custom-group-2 id / user-id & user-filter. Value of id/id &
Custom-group-3 range to be ignored in that case.

Matrix COSEC Web API User Guide 419

Table: Timesheet correction authorization- Parameters

Argument Valid Values Mandatory Default Value Description

1 to 999999 (for all the If argument range is not mentioned and

ranges except all & individual argument ID is specified,
user) then id should be considered of User.

Max 15 alphanumeric Argument ID can have multiple ids as

characters (for user) value with comma separated. For
ID No - example Id=1,2,…..999
A to Z
a to z In case user-id /user-id & user-filter are
provided along with id/id & range,
0 to 9
priority should always be given to user-
/_\\.@: id / user-id & user-filter. Value of id/id &
range to be ignored in that case.

Response Fields

Table: Timesheet correction authorization- Response Fields

Field Name Tag Name Valid Values Remarks

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

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

Date on which timesheet

Attendance Date attendance-date mm/dd/yyyy
record is available

Allowed Characters
A-Z,
Job Code job-code 10 Characters. (max) a-z
0-9
.-_()

Allowed Characters
A-Z,
Phase Code phase-code 10 Characters. (max) a-z
0-9
.-_()

Allowed Characters
A-Z,
Project Code project-code 10 Characters. (max) a-z
0-9
.-_()

Start Date Time start-date-time mm/dd/yyyy HH:MM:SS

End Date Time end-date-Time Mm/dd/yyyy HH:MM:SS

0 - Un-Assigned Hours
1 - Job Hours
Transaction Type transaction-type
2-Out Time
3-Break Hours

Job Hours job-hours HH:MM

Job Count job-count 1-99999

420 Matrix COSEC Web API User Guide

Table: Timesheet correction authorization- Response Fields

Field Name Tag Name Valid Values Remarks

0 - Award
Adjustment Type adjustment-type
1 - Penalty

Adjustment-Hours adjustment-hours HH:MM

Allowed Characters
A-Z
Remark remark 50 characters (max) a-z
0-9
_.,()[]:@!#$*+/\

Transaction ID transaction-id 1-999

OT1 ot1 HH:MM

OT2 ot2 HH:MM

OT3 ot3 HH:MM

OT4 ot4 HH:MM

OT5 ot5 HH:MM

15 characters 0 = Job Assignment Type

= “Fixed” or “None”
0-4294967295
1-4294967294 = Job
Reference ID
Job ID job-id corresponding to
respective Job Codes

4294967295 = Job
Reference ID selected =
None

Allowed Characters
A-Z
Job Name job-name 30 Characters a-z
0-9
-_.()[]

Matrix COSEC Web API User Guide 421

Get Timesheet Correction Application

This API is used to get the user's timesheet correction application details of the user for the specific date period for
Transaction/Attendance Value = Applied.

Action

action= get

Syntax

http://<matrixserver>/api.svc/v2/timesheet-correction-application?action=<get>;<argument>=<value>...

User Rights

User Rights

System Account Enabled If User has rights on any of the following Page.

JPC > Utilities> Timesheet Correction

JPC > Utilities> Timesheet Correction Authorization

ESS User Enabled if User has rights on any of the following Page.

ESS > Approval/Authorization > Timesheet Correction Authorization

ESS > Job Costing > Timesheet Correction Application

Parameters

Table: Timesheet correction application- Parameters

Argument Valid Values Mandatory Default Value Description

date-range ddmmyyyy-ddmmyyyy No - To specify the period for which the

Timesheet correction application
details are to be fetched.

User-filter 0: individual No 0 To get the data based on individual

1: group user or group of user.

When argument Range & Id or Id is

mentioned and argument user-id is not
provided , default value user-filter=0
should not be considered

Argument user-filter should only be

applied when argument user-id is
provided, else it should be ignored.

422 Matrix COSEC Web API User Guide

Table: Timesheet correction application- Parameters

Argument Valid Values Mandatory Default Value Description

Userid 15 alphanumeric Yes - To specify the ID of the user.

Char. (for user)
A to Z The Timesheet Correction Application
a to z data will be fetched only if the user
0 to 9 meets the following condition :
/_\\.@: "User is Active
"User with Attendance Calculation
Enable.
"User with Job Processing & Costing
Enable.

For ESS user :

If user-filter=0, the userid should be
login user's ID or of any user belonging
to the group for which login user is
reporting in-charge.

In case userid & user-filter are provided

along with id/id & range, priority should
always be given to userid & user-filter.
Value of id/id & range to be ignored in
that case.

application-status 0: all No - If application-status is not mentioned,

1: pending “All” will be considered by default.
2: approved
3: rejected

All In this argument only single value

Organization should be allowed.
Branch
Department If argument range's value is specified
Designation as "All", ids of all the users that login
Section User (If argument user has rights over will return.
Range No
Category Range is not specified)
Grade In case user-id /user-id & user-filter are
User provided along with id/id & range,
Custom-group-1 priority should always be given to user-
Custom-group-2 id / user-id & user-filter. Value of id/id &
custom-group-3 range to be ignored in that case.

If argument range is not mentioned and

individual argument ID has specified,
1 to 999999 (for all the then id should be considered of User.
ranges except all &
user) Argument ID can have multiple ids as
Max 15 alphanumeric value with comma separated.
ID characters (for user) No - For example Id=1,2,…..999.
A to Z
a to z In case user-id /user-id & user-filter are
0 to 9 provided along with id/id & range,
/_\\.@: priority should always be given to user-
id / user-id & user-filter. Value of id/id &
range to be ignored in that case.

The Timesheet Correction Application data will be fetched only if the user meets the following condition:
•User is Active
•User with Attendance Calculation Enabled.
•User with Job Processing & Costing Enabled.

Matrix COSEC Web API User Guide 423

Response Fields

Table: Timesheet correction application- Response Fields

Field Name Tag Name Valid Values Remarks

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

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

Application-id application-id 1-99999

mm/dd/yyyy
Application Date Time application-date-time
HH:MM:SS

Attendance Date attendance-date mm/dd/yyyy

First Half Attendance

First Half first-half Status on Attendance
Date.

Second Half Attendance

Second Half second-half Status on Attendance
Date.

Transaction Id transaction-id 1 - 999

Allowed Characters
A-Z,
Project Code project-code 10 Characters. (max) a-z
0-9
.-_()

Allowed Characters
A-Z,
Phase Code phase-code 10 Characters. (max) a-z
0-9
.-_()

Allowed Characters
A-Z,
10 Characters. (max)
Job Code job-code a-z
0-9
.-_()

Start Date Time start-date-time mm/dd/yyyy HH:MM:SS

End Date Time end-date-Time Mm/dd/yyyy HH:MM:SS

0 - Un-Assigned Hours
1 - Job Hours
Transaction Type transaction-type
2- Out Time
3- Break Hours

Job Hours job-hours HH:MM

Job Count job-count 1-99999

0 - Pending
Application Status application-status 1 - Approved
2 - Rejected

424 Matrix COSEC Web API User Guide

Table: Timesheet correction application- Response Fields

Field Name Tag Name Valid Values Remarks

Allowed Characters
A-Z
Reason reason 50 characters (max) a-z
0-9
_.,()[]:@!#$*+/\

Allowed Characters
A-Z
Remark remark 50 characters (max) a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Final RIC ID final-ric A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Final RIC Name final-ric-name
a-z
0-9
-_. ()[]

MM/DD/YYYY
Final RIC Verdict Date Time final-ric-verdict-date
HH:MM

1: pending
Provides status of
Final RIC Verdict final-ric-verdict 2: approved
application.
3: rejected

Max 15 chars

Allowed Characters
Non-Final RIC ID nonfinal-ric A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC Name nonfinal-ric-name
a-z
0-9
-_. ()[]

Non-Final RIC Verdict Date MM/DD/YYYY

nonfinal-ric-verdict-date
Time HH:MM

1: pending
Non-Final RIC Verdict nonfinal-ric-verdict 2: approved
3: rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC Remark nonfinal-ric-remark
a-z
0-9
_.,()[]:@!#$*+/\

Matrix COSEC Web API User Guide 425

Table: Timesheet correction application- Response Fields

Field Name Tag Name Valid Values Remarks

Max 15 chars

Allowed Characters
Non-Final RIC2 ID nonfinal-ric2 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC2 Name nonfinal-ric2-name
a-z
0-9
-_. ()[]

Non-Final RIC2 Verdict Date MM/DD/YYYY

nonfinal-ric2-verdict-date
Time HH:MM

1: pending
Non-Final RIC2 Verdict nonfinal-ric2-verdict 2: approved
3: rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC2 Remark nonfinal-ric2-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC3 ID nonfinal-ric3 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC3 Name nonfinal-ric3-name
a-z
0-9
-_. ()[]

Non-Final RIC3 Verdict Date MM/DD/YYYY

nonfinal-ric3-verdict-date
Time HH:MM

1: pending
Non-Final RIC3 Verdict nonfinal-ric-verdict 2: approved
3: rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC3 Remark nonfinal-ric3-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC4 ID nonfinal-ric4 A-Z
a-z
0-9
@_ / : .

426 Matrix COSEC Web API User Guide

Table: Timesheet correction application- Response Fields

Field Name Tag Name Valid Values Remarks

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC4 Name nonfinal-ric4-name
a-z
0-9
-_. ()[]

Non-Final RIC4 Verdict Date MM/DD/YYYY

nonfinal-ric4-verdict-date
Time HH:MM

1: pending
Non-Final RIC4 Verdict nonfinal-ric4-verdict 2: approved
3: rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC4 Remark nonfinal-ric4-remark
a-z
0-9
_.,()[]:@!#$*+/\

15 characters 0 = Job Assignment Type

= “Fixed” or “None”
0-4294967295
1-4294967294 = Job
Reference ID
Job ID job-id corresponding to
respective Job Codes

4294967295 = Job
Reference ID selected =
None

Allowed Characters
A-Z
Job Name job-name 30 Characters a-z
0-9
-_.()[]

Matrix COSEC Web API User Guide 427

Job Costing Process

This API is used for Processing the Job Costing of the Users.

Action

action=command

Syntax

http://<matrixserver>/api.svc/v2/job-costing-process?action=<command>;<argument>=<value>...

User Rights

User Rights

System Account Enabled If User has rights on the following Page.

JPC > Utilities> Job Costing Process

Parameters

Table: Process job costing- Parameters

Argument Valid Values Mandatory Default Value Description

date-range ddmmyyyy-ddmmyyyy Yes - To specify the period for which job

costing is to be processed

reprocess-events 0 (= No) - - To reprocess job costing for: (from-date

1 (= Yes) - 1) to Current date.

user-selection 0 (=All) - 0 To select the user randomly or based

1 (=Organization) on enterprise group.
2 (=Branch)
3 (=Department)
4 (=Designation)
5 (=Section)
6 (=Category)
7 (=Grade)
8 (=Individual)

id 1 to 999999 Yes - For system user, this can be the user Id

[For all the user- (if user or Enterprise Group Id of any
selection value except selection is Enterprise/User on which admin has
0 (=All) & 8 other than All) appropriate user rights.
(=Individual)]

or

15 Char. [for user,

user-selection 8
(=Individual)]

The process will be executed only if the user meets the following condition:
•User is Active
•User with Attendance Calculation Enable.
•User with Job Processing & Costing Enable.

428 Matrix COSEC Web API User Guide

Timesheet Correction Application

This API is used for submitting the user's timesheet correction application of the user for the specific date period.

Action

action= set

Syntax

http://<matrixserver>/api.svc/v2/timesheet-correction-application?action=<set>;<argument>=<value>...

User Rights

User Rights

System Account Enabled If User has rights on any of the following Page.

JPC > Utilities> Timesheet Correction

JPC > Utilities> Timesheet Correction Authorization

ESS User Enabled if User has rights on any of the following Page.

ESS > Approval/Authorization > Timesheet Correction Authorization

ESS > Job Costing > Timesheet Correction Application

Parameters

Table: Timesheet correction application- Parameters

Argument Valid Values Mandatory Default Value Description

userid 15 Characters Yes - To specify the ID of the user.

attendance-date ddmmyyyy Yes - The date for which application is being

submitted.

transaction-id 1-999 Yes -

correction-type 0 =edit No 0 Correction-type=0, for the corrections

1 =split in start-date-time, end-date-time, job
code, job count.
Correction-type=1, for splitting the
transactions in one or more
transactions.

job-code 15 Characters. (max) No - Job-code = removejobcode should be

passed when user is willing to remove
(=removejobcode) job code from the supplied transaction.

start-date-time ddmmyyyyhhmm No - Applicable only for correction-type=0

(edit).

end-date-time ddmmyyyyhhmm No - Applicable only for correction-type=0

(edit).

split-date-time ddmmyyyyhhmm Yes (for -

Applicable only for correction-type = 1
correction-
(split)
type = 1)

job-count 1-99999 No - -

Matrix COSEC Web API User Guide 429

Table: Timesheet correction application- Parameters

Argument Valid Values Mandatory Default Value Description

adjustment-type 0 - Award No -
-
1 - Penalty

adjustment-hours HH:MM Yes -

(If
00:00 - 23:59 adjustment- -
type is
specified)

remark 50 Char No -
A-Z
a-z
0-9
NA if adjustment-type is not supplied.
!@$&()-_+[]:,./

space

reason 50 Char No -
A-Z
a-z
0-9 Applicable only for Login as ESS User.

space

authorization-required 0: not required No 0 (Not required) Applicable for System Account User
1: required only.

If authorization required = 1, then the

application will be considered as
applied by an ESS User (UserID
mentioned in API.)

The Timesheet Correction Application will be made only if the user meets the following condition:
•User is Active
•User with Attendance Calculation Enabled.
•User with Job Processing & Costing Enabled.

Example1

Following are some sample cases for this API:

Sample Request:

To apply for Timesheet correction application for a user to add the Job Code

http://192.168.104.12/cosec/api.svc/v2/timesheet-correction-
application?action=set;userid=JPC2;attendance-date=12022018;transaction-id=1;job-code=SRS

Sample Response:

success: 0800200001 : successful

430 Matrix COSEC Web API User Guide

Example2

Sample Request:

To apply for Timesheet correction application for a user to split the transaction along with the requirement of
authorization.

http://192.168.104.12/cosec/api.svc/v2/timesheet-correction-
application?action=set;userid=JPC2;attendance-date=12022018;transaction-id=1;job-code=SRS;correction-
type=1;split-date-time=120220181130;authorization-required=1

Sample Response:

success: 0800200001 : successful

The application will go to the reporting incharge or administrator for authorization. Once the application is approved,
the transaction will be split by the time mentioned in API as shown below.

Example3

Sample Request:

To apply for Timesheet correction application for a user to change the start and end time of transaction along with
the requirement of authorization.

http://192.168.104.12/cosec/api.svc/v2/timesheet-correction-
application?action=set;userid=JPC2;attendance-date=12022018;transaction-id=1;job-code=SRS;correction-
type=0; start-date-time=120220180930;end-date-time =120220181115;authorization-required=1

Sample Response:

success: 0800200001 : successful

Matrix COSEC Web API User Guide 431

Timesheet Correction Authorization

This API is used for the authorization of Timesheet Correction Application & Job Splitting Application.

Action

action=set

Syntax

http://<matrixserver>/api.svc/v2/timesheet-correction-authorization?action=<set>;<argument>=<value>...

User Rights

User Rights

System Account Enabled If User has rights on the following Page.

JPC > Utilities> Timesheet Correction Authorization

ESS User Enabled if User has rights on the following Page.

ESS > Approval/Authorization > Timesheet Correction Authorization

Parameters

Table: Timesheet correction authorization- Parameters

Argument Valid Values Mandatory Default Value Description

user-id 15 Characters Yes - To specify the ID of the user for whom

JPC is enabled.

application-id 1-99999 Yes - This is the identification number for the

timesheet correction application. The
login user must have rights on the user
ID associated with this Application ID.

verdict 1: Approve Yes - This is the approval verdict to be

2: Reject applied to an application. A verdict can
be passed only for applications that are
pending for approval.

remark Max 50 chars No - To mention the remark while giving

_-()[].,/\ +!@$* verdict to the application.
: and <space>

Example1

Sample Request:

To approve the Timesheet correction application for a user.

http://192.168.104.12/cosec/api.svc/v2/timesheet-correction-
authorization?action=set;userid=JPC2;application-id=2;verdict=1;

Sample Response:

success: 0780200002: saved successfully

432 Matrix COSEC Web API User Guide

CHAPTER 25 Visitor Management

The following API enable the user to perform actions related to Visitor Management. This is used to get list of
Vehicle types, Visitor types, Visit types as per the Visit components and APIs for Visitor pre-registration and
approval.

Action= Get
• Getting Vehicle Types
• Getting Visitor Types
• Getting Visit Types

Visitor Pre-Registration APIs

Action= Get
• Getting Visitor Pre-registration details

Action= Set
• Visitor Pre-registration Application

Action= Update
• Updating Visitor Pre-registration Application

Action= Delete
• Deleting Visitor Pre-registration application

Additional Visitors Details APIs

Action= Get
• Getting Additional Visitors details

Action= Set
• Adding Additional Visitor details

Action= Update
• Updating Additional Visitor details

Action= Delete
• Deleting Additional Visitor details

Visitor Pre-registration Approval API

Action= Set
• Visitor Pre-registration Approval

Matrix COSEC Web API User Guide 433

Seamless VMS

The ESS user who is not authorized host user will be validated for accessing APIs concerned with
Seamless VMS.

Visitor Registration
Action= Set
Action= Get
• Visitor Registration

Authorized Host user

Action= Get
• Getting Authorized Host User

VMS Setting
Action= Get
• Getting VMS Setting
Action= Set
• Setting VMS Configuration

Host Unavailability Days

Action= Get
• Getting Host Unavailability Days
Action= Set
• Set Host Unavailability Days
Action= Update
• Update Host Unavailability Days
Action= Delete
• Delete Host Unavailability Days

Visitor API
Action= Get
• Getting Visitor Details
Action= Set
• Set Visitor Details
Action= Delete
• Deleting Visitor Details

Visitor Profile API

Action= Get
• Getting Visitor Profile
Action= Set
• Setting Visitor Profile
Action= Delete
• Deleting Visitor Profile

Invite Visitor API

Action= Get
• Getting Invite Visitor Application Details
Action= Set
• Sending the Invite Visitor Link

434 Matrix COSEC Web API User Guide

Visitor Invites Approval API
Action= Set
• Visitor Invites Approval

Security Approval API

Action= Set
• Set Security Approval

Visit State API

Action= Set
• Set Visit State

System Account User

Action= Get
• System Account User

OTP Verification
Action= Command
• OTP Verification

Tenant Identifier API

Action= Set
• Tenant Identifier API

Matrix COSEC Web API User Guide 435

Getting Vehicle Types

This API is used to get the Vehicle types as defined in Visit components of VMS module.

Action

action=get

Syntax

http://<servername>/api.svc/v2/vehicle-type?action=<get>

User Rights

User Rights

System Account Enabled if User has rights on any one of the following Pages.
VMS > Visit Components
VMS > Pre-Registration
VMS > Pre-Registration Approval

ESS User Enabled if User has rights on the following Page.

ESS > Basic > Visitor Pre Registration
ESS > Approval/Authorization > Pre-Registration Approval

Visitor Enabled if Visitor is registered and verified by using assigned token.

Parameters

Table: Getting Vehicle type- Parameters

Argument Valid Values Mandatory Default Value Description

user-type 0 = Host User / No 0

SA User To get the visitor types defined in visit
1 = Visitor components of VMS module.

Response Fields

Table: Getting Vehicle type - Response Fields

Field Name Tag Name Valid Values Remarks

ID id 0 -9 Max 2 digits

Name name 20 Characters

0 = Not Default
Default default
1 = Default is set

Example1

Sample Request:

436 Matrix COSEC Web API User Guide

To fetch vehicle types configured in visit components:

http://192.168.104.12/cosec/api.svc/v2/vehicle-type?action=get;

Sample Response:

id|name|default
1|None|0
2|2-Wheeler|1
3|4-Wheeler|0
4|3-Wheeler|0
<EOT>

Matrix COSEC Web API User Guide 437

Getting Visitor Types

This API is used to get the Visitor types as defined in Visit components of VMS module.

Action

action= get

Syntax

http://<servername>/api.svc/v2/visitor-type?action=<get>

User Rights

User Rights

System Account Enabled if User has rights on any one of the following Pages.
VMS > Visit Components
VMS > Pre-Registration
VMS > Pre-Registration Approval

ESS User Enabled if User has rights on the following Page.

ESS > Basic > Visitor Pre Registration
ESS > Approval/Authorization > Pre-Registration Approval

Visitor Enabled if Visitor is registered and verified by using assigned token.

Parameters

Table: Visitor Type- Parameters

Argument Valid Values Mandatory Default Value Description

user-type 0 = Host User / No 0

SA User To get the visitor types defined in visit
1 = Visitor components of VMS module.

Response Fields

Table: Visitor Type- Response Fields

Field Name Tag Name Valid Values Remarks

ID id 0 -9 Max 2 digits

Name name 200 Characters

Color Code color-code

0 = Not Default
Default default
1 = Default is set

Example1

438 Matrix COSEC Web API User Guide

Sample Request:

To fetch visitor types configured in visit components:

http://192.168.104.12/cosec/api.svc/v2/visitor-type?action=get;

Sample Response:

id|name|color-code|default
1|General Visitor||1
2|Supplier||0
3|Interviewee||0
4|Media Personnel||0
5|Technical Personnel||0
6|Courier Personnel||0
7|Customer||0
8|Partner||0
<EOT>

Matrix COSEC Web API User Guide 439

Getting Visit Types

This API is used to get the Visit types as defined in Visit components of VMS module.

Action

action=get

Syntax

http://<servername>/api.svc/v2/visit-type?action=<get>

User Rights

User Rights

System Account Enabled if User has rights on any one of the following Pages.
VMS > Visit Components
VMS > Pre-Registration
VMS > Pre-Registration Approval

ESS User Enabled if User has rights on the following Page.

ESS > Basic > Visitor Pre Registration
ESS > Approval/Authorization > Pre-Registration Approval

Visitor Enabled if Visitor is registered and verified by using assigned token.

Parameters

Table: Getting Visit Type- Parameters

Argument Valid Values Mandatory Default Value Description

user-type 0 = Host User / No 0 To get the visit types defined in visit

SA User components of VMS module.
1 = Visitor

Response Fields

Table: Getting Visit type - Response Fields

Field Name Tag Name Valid Values Remarks

ID id 0 -9 Max 2 digits

Name name 200 Characters

0 = Not Default
Default default
1 = Default is set

Example1

Sample Request:

440 Matrix COSEC Web API User Guide

To fetch vehicle types configured in visit components:

http://192.168.104.12/cosec/api.svc/v2/visit-type?action=get;

Sample Response:

id|name|default
1|Personal|1
2|Official|0
<EOT>

Matrix COSEC Web API User Guide 441

Getting Visitor Pre-registration details

This API is used to get the visitor pre-registration details for the required date range and specified user filter & user
id.

Action

action=get

Syntax

http://<servername>/api.svc/v2/visitor-pre-registration?action=<get>;<argument>=<value>...

User Rights

User Rights

System Account Enabled if User has rights on any one of the following Pages.
VMS > Pre-Registration
VMS > Pre-Registration Approval
VMS > EPass Approval

ESS User Enabled if User has rights on the following Page.

ESS > Basic > Visitor Pre Registration
ESS > Approval/Authorization > Pre-Registration Approval

Visitor Enabled for All Registered Visitors with “isVerified” flag=1

Parameters

Table: Getting Visitor Pre-registration details- Parameters

Argument Valid Values Mandatory Default Value Description

user-type 0 = Host User / SA No 0

User -
1 = Visitor

date-range ddmmyyyy-ddmmyyyy No - To specify the period for which visitor

pre-registration details are required.
This range is for Visit Dates.

If date range is not specified, then

records between current date to current
date+45 will be fetched.

442 Matrix COSEC Web API User Guide

Table: Getting Visitor Pre-registration details- Parameters

Argument Valid Values Mandatory Default Value Description

user-filter 0: individual No 0 If user-filter=0, a single (host) user's

1: group records will be fetched.
2: All
If user-filter=1, records for all the group
members (host users) will be fetched.

"If user-filter = 2, records for all visitor

pre-registration records will be fetched.

Note: user-filter=1, is applicable if login

user is a reporting in-charge or system
account user.
"user-filter=2, is applicable if logged in
user is system account user.

Note: It is not applicable when Logged

IN User is Visitor.

When argument Range & Id or Id is

mentioned and argument user-id is not
provided default value user-filter=0
should not be considered.

Argument user-filter should only be

applied when argument user-id is
provided, else it should be ignored.

Not Applicable when Logged IN User is

Visitor.

Not Applicable when user-filter = 2.

For ESS user:

If user-filter=0, the user-id must be
login user's ID or of any user belonging
to the group for which login user is
reporting in-charge

If user-filter=1, the user-id must be

same as login user's ID. If it is reporting
15 alphanumeric group in-charge's id, the records of his
Char. (for user) group members will be returned.
A to Z Yes when
user-id a to z user-filter = 0 - For a System Account user:
0 to 9 or 1. If user-filter=0, the user-id can be any
/_\\.@: user's id which is authorized host user.

If user-filter=1, the user-id can be any

user's ID.If it is reporting group in-
charge's id, the records of his group
members are returned.

Note: It is not applicable when Logged

IN User is Visitor.

In case user-id & user-filter are

provided along with id/id & range,
priority should always be given to user-
id & user-filter. Value of id/id & range to
be ignored in that case.

visitor-id
Not Applicable when Logged IN User is
0-9 No -
Visitor.

Matrix COSEC Web API User Guide 443

Table: Getting Visitor Pre-registration details- Parameters

Argument Valid Values Mandatory Default Value Description

0: all
status 1: pending If status is not specified, then "All" is
No 0
2: approved considered by default.
3: rejected

filter For Host No All Applicable to Host User, Visitor &

0 (= All) Security.
1 (= Pending)
2 (= Accepted) Not Applicable for RIC Users.
3 (= Cancelled By You)
4 (=Cancelled By For a Security / System Account user:
Visitor)
5 (= Rescheduled By 0 = All- All the visits should be
You) displayed when filter is passed 0. It is
6 (= Rescheduled By the default value when parameter is not
Visitor) passed.
7 (= Completed)
8 (= Sent By Me) 1 = Accepted - Visits which are
accepted by security or whose visit
For Visitor state is 0,1,2,3 should be displayed
0 (= All) when filter is passed 1.
1 (= Pending)
2 (= Accepted) 2 = Completed - Visits whose visit state
3 (= Cancelled By You) is 4,5 should be displayed when filter is
4 (=Cancelled By passed 2.
Host)
5 (= Rescheduled By 3 = Self-created - Visits which are
You) created by SA himself should be
6 (= Rescheduled By displayed when filter is passed 3.
Host)
7 (= Completed)

For Security / System

Account User
0 (=All)
1 (= Accepted)
2 (= Completed)
3 (= Self- Created)

appointment-no 0-9 No - Specify the appointment number

12 Digits (Each whose pre-registration details are
Appointment No) required.

You can pass multiple appointment-no,

each separated by ", (comma)" e.g.:"
240118000001,240118000002,
240118000003"

All In this argument only single value

Organization should be allowed.
Branch
Department If argument range's value is specified
Designation as "All", ids of all the users that login
Section User (If argument user has rights over will return.
Range No
Category Range is not specified)
Grade In case user-id /user-id & user-filter are
User provided along with id/id & range,
Custom-group-1 priority should always be given to user-
Custom-group-2 id / user-id & user-filter. Value of id/id &
custom-group-3 range to be ignored in that case.

444 Matrix COSEC Web API User Guide

Table: Getting Visitor Pre-registration details- Parameters

Argument Valid Values Mandatory Default Value Description

If argument range is not mentioned and

individual argument ID is specified,
1 to 999999 (for all the then id should be considered of User.
ranges except all &
user) Argument ID can have multiple ids as
Max 15 alphanumeric value with comma separated. For
ID characters (for user) No - example Id=1,2,…..999.
A to Z
a to z In case user-id /user-id & user-filter are
0 to 9 provided along with id/id & range,
/_\\.@: priority should always be given to user-
id / user-id & user-filter. Value of id/id &
range to be ignored in that case.

0-9
8 digits (each dynamic- Argument dynamic-id will be ignored
dynamic-id No
id) when appointment-no is passed.

Response Fields

Table: Getting Visitor Pre-registration details - Response Fields

Field Name Tag Name Valid Values Remarks

Appointment No. appointment-no 0-9 12 Digits

Visit Date visit-date mm/dd/yyyy

Visit Days visit-days 0-9 Max 3 Digits

Visitor Arrival Time visitor-arrival-time hh:mm

Visiting Hours Per Day visiting-hours-per-day hh:mm

Visitor Name visitor-name 200 Characters

Organization organization-name 45 Characters

Mobile No. mobile-no 20 Characters 0-9 ( ) - +

Email email 125 Characters

Visitor Type visitor-type 0-9 Max 2 digits

Matrix COSEC Web API User Guide 445

Table: Getting Visitor Pre-registration details - Response Fields

Field Name Tag Name Valid Values Remarks

Visit Type visit-type 0-9 Max 2 digits

Additional Visitors additional-visitor-count 0-9 Max 2 digits

Allowed characters
A-Z
Host User ID host-id 15 characters a-z
0-9
/_\\.@:

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

Purpose purpose 50 characters

0 = No (Not Set)
Send Notification To Visitor send-notification-to-visitor
1 = Yes (Set)

0 = Pending/Applied
Status status 1 = Approved
2 = Rejected

Vehicle Registration No. vehicle-registration-no 15 Characters

Vehicle Type vehicle-type 0-99 Max 2 digits

Vehicle Description vehicle-description 50 Characters

Visit Until Date visit-until-date mm/dd/yyyy

Visit Start Time visit-start-time hh:mm Range: 00:00 - 23:59

Visit End Time visit-end-time hh:mm Range: 00:00 - 23:59

0 = Do Not Repeat
Repeat Mode repeat-mode 1 = Daily
2 = Weekly

1: Sunday
2: Monday
Return repeat days in
3: Tuesday
comma-separated format.
Repeat Days repeat-days 4: Wednesday
5: Thursday
i.e. repeat-days=1,3,5
6: Friday
7: Saturday

446 Matrix COSEC Web API User Guide

Table: Getting Visitor Pre-registration details - Response Fields

Field Name Tag Name Valid Values Remarks

6 alpha-numeric
characters.
Location Code location-code If not available, return
blank.

11 characters (max.)
Latitude latitude -90.0000 to +90.0000 If not available, return
blank.

11 characters (max.)
Longitude longitude -180.0000 to +180.0000 If not available, return
blank.

Remark remark 50 Characters

Return additional host

User's ID(s) in comma-
separated format.
Additional Host additional-host i.e.
additional-
host=1542,1421,1320,152
8

Visitor ID visitor-id 0-9 15 characters

Designation designation-name 45 Characters

60 Characters
Visitor Address address

Visitor-City city 30 Characters

Visitor-State state 30 Characters

30 Characters
Visitor-Country country

Pincode pincode 10 Characters

Gender gender NA, Male, Female

Date Of Birth date-of-birth mmddyyyy

Nationality nationality 30 Characters

30 Characters
ID Proof 1 id-proof1

Matrix COSEC Web API User Guide 447

Table: Getting Visitor Pre-registration details - Response Fields

Field Name Tag Name Valid Values Remarks

30 Characters
ID Proof 2 id-proof2

0 = Visitor
Initiated By initiated-by 1 = Host

0 = Visitor
Reschedule By reschedule-by
1 = Host

Reschedule Date Time

reschedule-date-time

0 = Visitor
Verdict By verdict-by
1 = Host

0 = Pending
VisitorHostApproval visitor-host-approval 1 = Approved
2 = Rejected

Verdict Date Time verdict-date-time

Allowed Characters
A-Z
Cancellation Reason cancellation-reason a-z Max 50 chars.
0-9
_.,()[]:@!#$*+/\

Transfer Host ID transfer-host-id Max 15 Alphanumeric Characters

0_mm/dd/yyyy HH:MM = Check-

IN
1_mm/dd/yyyy HH:MM = Start
2_mm/dd/yyyy HH:MM = Paused
3_mm/dd/yyyy HH:MM = Resume
Return visit state with state
4_mm/dd/yyyy HH:MM = Stop
Visit State visit-state changes time stamp.
5_mm/dd/yyyy HH:MM = Check-
OUT

Here,
For visitor valid values = 0 & 5
For Host valid values = 1,2,3,4

Visit Profile ID visit-profile-id 15 alphanumeric

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

Allowed characters
A-Z
a-z
Visit State Change By visit-state-change-by 15 characters
0-9
/_\\.@:

448 Matrix COSEC Web API User Guide

Table: Getting Visitor Pre-registration details - Response Fields

Field Name Tag Name Valid Values Remarks

0 - Pending
EPass Approval epass-approval 1 - Approved
2 - Rejected

Allowed characters
A-Z
Epass Approval By epass-approval-by a-z 15 characters
0-9
/_\\.@:

Allowed Characters
A-Z
Epass Remark epass-remark a-z Max 30 chars
0-9
_.,()[]:@!#$*+/\

Allowed Characters
A –Z
45 characters
Host Organization host-org a-z
0–9
( ) [ ]_-. /&,@‘[Space]

Allowed Characters
A –Z
Visitor Organization visitor-org a-z 45 characters
0–9
( ) [ ]_-. /&,@‘[Space]

Allowed Characters
A-Z
Location Name location-name a-z 50 characters
0-9
-_. ()[]

max 32 numeric
Host Personal Cell host-personal-cell
characters

max 100 alphanumeric

Host Personal E-mail host-personal-email
characters

max 20 numeric
Host Official Cell host-official-cell
characters

max 100 alphanumeric

Host Official E-mail host-official-email
characters

Max 100 characters

Visit Custom Field 1 Field1
ddmmyyy

Max 100 characters

Visit Custom Field 2 Field2
ddmmyyy

Max 100 characters

Visit Custom Field 3 Field3
ddmmyyy

Matrix COSEC Web API User Guide 449

Table: Getting Visitor Pre-registration details - Response Fields

Field Name Tag Name Valid Values Remarks

Max 100 characters

Visit Custom Field 4 Field4
ddmmyyy

Max 100 characters

Visit Custom Field 5 Field5
ddmmyyy

Max 100 characters

Visit Custom Field 6 Field6
ddmmyyy

Max 100 characters

Visit Custom Field 7 Field7
ddmmyyy

Max 100 characters

Visit Custom Field 8 Field8
ddmmyyy

Max 100 characters

Visit Custom Field 9 Field9
ddmmyyy

Max 100 characters

Visit Custom Field 10 Field10
ddmmyyy

Uploaded document tag is

added for checking the
status of uploaded images
for respective field.
Multiple values are
50: Field1 possible in this field.
51: Field2
If documents/images are
52: Field3 present in field1,2 and 5
53: Field4 then uploaded-doc
shouldcontain value of
54: Field5 field1, field 2 and 5 be
Uploaded Doc uploaded-doc 55: Field6 provided in respective
field.
56: Field7
For Example in Json:
57: Field8 "uploaded-doc": "50,51,54"
58: Field9
Example in xml:
59: Field10 <?xml version="1.0"
encoding="UTF-8" ?>
<field5>String</field5>
<field6>String</field6>
<uploaded-
doc>50,51,54</uploaded-
doc>

DD/MM/YY
Applied On application-date
HH:MM

Max 15 chars

Allowed Characters
Final RIC ID final-ric A-Z
a-z
0-9
@_ / : .

450 Matrix COSEC Web API User Guide

Table: Getting Visitor Pre-registration details - Response Fields

Field Name Tag Name Valid Values Remarks

Max 45 chars
Allowed Characters
A-Z
Final RIC Name final-ric-name
a-z
0-9
-_. ()[]

DD/MM/YYYY
Final RIC Verdict Date Time final-ric-verdict-date
HH:MM

1: pending
Provides status of
Final RIC Verdict final-ric-verdict 2: approved
application.
3: rejected

Max 30 chars
Allowed Characters
A-Z
Final RIC Remark final-ric-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC ID nonfinal-ric A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC Name nonfinal-ric-name
a-z
0-9
-_. ()[]

Non-Final RIC Verdict Date MM/DD/YYYY

nonfinal-ric-verdict-date
Time HH:MM

1: pending
Non-Final RIC Verdict nonfina-ric-verdict 2: approved
3: rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC Remark nonfinal-ric-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC2 ID nonfinal-ric2 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC2 Name nonfinal-ric2-name
a-z
0-9
-_. ()[]

Non-Final RIC2 Verdict Date MM/DD/YYYY

nonfinal-ric2-verdict-date
Time HH:MM

Matrix COSEC Web API User Guide 451

Table: Getting Visitor Pre-registration details - Response Fields

Field Name Tag Name Valid Values Remarks

1: pending
Non-Final RIC2 Verdict nonfinal-ric2-verdict 2: approved
3: rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC2 Remark nonfinal-ric2-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC3 ID nonfinal-ric3 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC3 Name nonfinal-ric3-name
a-z
0-9
-_. ()[]

Non-Final RIC3 Verdict Date MM/DD/YYYY

nonfinal-ric3-verdict-date
Time HH:MM

1: pending
Non-Final RIC3 Verdict nonfinal-ric3-verdict 2: approved
3: rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC3 Remark nonfinal-ric3-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars

Allowed Characters
Non-Final RIC4 ID nonfinal-ric4 A-Z
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC4 Name nonfinal-ric4-name
a-z
0-9
-_. ()[]

Non-Final RIC4 Verdict Date MM/DD/YYYY

nonfinal-ric4-verdict-date
Time HH:MM

1: pending
Non-Final RIC4 Verdict nonfinal-ric4-verdict 2: approved
3: rejected

452 Matrix COSEC Web API User Guide

Table: Getting Visitor Pre-registration details - Response Fields

Field Name Tag Name Valid Values Remarks

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC4 Remark nonfinal-ric4-remark
a-z
0-9
_.,()[]:@!#$*+/\

Dynamic ID dynamic-id 0-9 8 digits

Format: VXXRXX.XX
Maximum 10 alphanumeric
COSEC Version cosec-version Example: V06R01 ,
characters V06R02 , V05R08.20

Matrix COSEC Web API User Guide 453

Example1

Sample Request:

To fetch visitor pre-registration details of the users for whom host user- id is specified.

http://192.168.104.12/cosec/api.svc/v2/visitor-pre-registration?action=get;user-id=1

Sample Response:

appointment-no|visit-date|visit-days|visitor-arrival-time|visiting-hours-per-day|visitor-name|organization-
name|mobile-no|email|visitor-type|visit-type|additional-visitor-count|host-id|host-name|purpose|send-
notification-to-visitor|status|vehicle-registration-no|vehicle-type|vehicle-model|vehicle-color
180112000001|01/16/
2018|1|19:30|02:00|Namrata|Infosys|9687624826|[email protected]|1|1|0|1|Chirag||1|1|GJ06FP7691|2||Bla
ck
<EOT>

Example2

Sample Request:

To get visitor pre-registration details based on user filter-1(group).

http://192.168.104.12/cosec/api.svc/v2/visitor-pre-registration?action=get;user-filter=1;user-id=101;

Sample Response:

appointment-no|visit-date|visit-days|visitor-arrival-time|visiting-hours-per-day|visitor-name|organization-
name|mobile-no|email|visitor-type|visit-type|additional-visitor-count|host-id|host-name|purpose|send-
notification-to-visitor|status|vehicle-registration-no|vehicle-type|vehicle-model|vehicle-color
180117000004|01/17/2018|1|17:00|01:00|Meena||9685243158||1|1|0|1|Chirag||0|1||2||
180117000003|01/17/2018|1|16:00|01:00|Rupal||9685243157||1|1|0|1|Chirag||0|1||2||
<EOT>

The Pre-registration applications are shown for the member users (Chirag) who are valid host user and who belong to the reporting
group with reporting incharge id (user id-101) which is used in the API.

Here User ID-101 is for reporting Incharge Khushbu and Chirag is the member of khushbu. So applications where Chirag is host user
will be returned in the API.

454 Matrix COSEC Web API User Guide

Visitor Pre-registration Application

This API is used for applying the visitor pre-registration application for the required date and specified user id. The
Visitor Pre-Registration Application will set only if the user is an Authorized Host User.

Action

action= set

Syntax

http://<servername>/api.svc/v2/visitor-pre-registration?action=<set>;<argument>=<value>...

User Rights

Parameters

User Rights

System Account Enabled if User has rights on any one of the following Pages.
VMS > Pre-Registration
VMS > Pre-Registration Approval
VMS > EPass Approval

ESS User Enabled if User has rights on the following Page.

ESS > Basic > Visitor Pre Registration
ESS > Approval/Authorization > Pre-Registration Approval

Visitor Enabled for All Registered Visitors with “isVerified” flag=1

Table: Visitor Pre-registration application- Parameters

Default Multi language

Argument Valid Values Mandatory Description
Value Support

user-type 0 = Host User / No 0 N

SA User To specify type of user
1 = Visitor

visit-date ddmmyyyy Yes - N The date for which application is being

submitted.

visit-days 0-9 No - N The days for which visitor is supposed

Range: 1-9999 to visit.
Note: "Not Applicable when Logged IN
User is Visitor.

ddmmyyyy No - N Visit Until Date should be greater than

or equals to Visit Date.
Range:
visit-until-date Note: If Visit Days & Visit Until Date is
Current Date to not supplied or If Logged IN User is
31/12/2037 visitor and this field is not supplied then
it will lead to incomplete command.

0 = Do Not No - N -
Repeat
repeat-mode 1 = Daily
2 = Weekly

Matrix COSEC Web API User Guide 455

Table: Visitor Pre-registration application- Parameters

Default Multi language

Argument Valid Values Mandatory Description
Value Support

1: Sunday No - N Note: Mandatory only when repeat-

2: Monday mode = 2
3: Tuesday
repeat-days 4: Wednesday
5: Thursday
6: Friday
7: Saturday

visitor-arrival- hhmm No - N Not Applicable when Logged IN User is

time Range: Visitor.
00:00 - 23:59

hhmm No - N Note: If visitor-arrival-time & visit-start-

visit-start-time Range: time not supplied / If Logged IN User is
00:00 - 23:59 visitor and this field is not supplied then
it will lead to incomplete command.

visiting-hours- hhmm No - N The hours for which visitor is supposed

per-day to visit. Not Applicable when Logged IN
User is Visitor.

visit-end-time hhmm No - N Note: If visiting-hours-per-day & visit-

Range: end-time not supplied / If Logged IN
00:00 - 23:59 User is visitor and this field is not
supplied, then it will lead to incomplete
command. Visit End Time should be
later than Visit Start Time.

location 0 =Select No 0 N
1=Configured
Location -
2 = Custom
Location

location-code 6 alpha-numeric No 0 NA
characters.
Mandatory only when location = 1.

latitude -90.0000 to No 0 N
Mandatory only when location = 2.
+90.0000

longitude -180.0000 to No 0 N
+180.0000 Mandatory only when location = 2.

visitor-name 200 characters Yes - Y (Set2) The name of the visitor. Mandatory field
if supplied mobile number is new.

organization- 45 characters No - Y (Set3)

name 0-9 The name of the visitor’s organization.
A-Z Mandatory field if supplied mobile
a-z number is new.
_- ()[].,/+!@$:&*
<SPACE>

designation- 45 characters No - Y(Set3)

name 0-9
A-Z
The name of the visitor’s designation.
a-z
_- ()[].,/+!@$:&*
<SPACE>

mobile-no 20 characters Yes - NA

The mobile number of the visitor.
0-9 ( ) - +

456 Matrix COSEC Web API User Guide

Table: Visitor Pre-registration application- Parameters

Default Multi language

Argument Valid Values Mandatory Description
Value Support

email 125 characters No - Y(Set1) The Email ID of the visitor.

visitor-type Valid Range: 1-99 No - N General, Supplier, Interviewee, Courier

etc

visit-type Valid Range: 1-99 No - N

Personal, Official etc

additional- 0-99 No - N
Escort visitor
visitors

host-id 15 alphanumeric No-for ESS - N For ESS users: (Not Mandatory field)
Char. (for user) user
A to Z Yes- for SA 'host-id' should be login ESS user's ID.
a to z user If not supplied, logged In user id will be
0 to 9 set.
/_\\.@:
For SA users: (Mandatory field)

host-id' should be authorized host user.

Mandatory field if supplied mobile
number is new.

For Visitor: (Not Mandatory field if

Default Host User is configured)

additional- 15 alphanumeric No - N
host Char. (for user)
A to Z
"Multiple hosts User's ID(s) with
a to z
comma-separated format.
0 to 9
i.e. additional-
/_\\.@:
host=1542,1421,1320,1528
Range: Maximum
99 Host Users

purpose 50 characters No - NA
0-9
A-Z
It is the purpose of visit.
a-z
<space>
!@$*()_-+/[]:.

send- 0 = No (Not Set) No 0 N

notification-to- 1 = Yes (Set) To send notification to the visitor.
visitor

vehicle- 15 Characters No - NA
registration-no A-Z
It is the vehicle number.
a-z
0-9

vehicle-type Valid Range: 1-99 No - NA 2 wheeler, 4 wheeler etc

50 Characters
A-Z
vehicle- a-z
No NA It is the description of vehicle.
description 0-9
<space>
!@$^*()_-+/[].:

Matrix COSEC Web API User Guide 457

Table: Visitor Pre-registration application- Parameters

Default Multi language

Argument Valid Values Mandatory Description
Value Support

return- 0 = Not Required No - NA If value of this argument is given as 1,

appointment- 1 = Required then appointment number of the
no application will be returned.

If this argument is not given then

consider as 0

"If control type for

respected custom
fields is selected
as Textbox in
Global Policy:
Max 100
Alphanumeric
Characters
field<no>
A-Z Mandatory field, if 'Active' &
a-z 'Mandatory' checkbox is checked for
(where <no>
0-9 respective custom fields in Global
will vary from
[]().-_ / Policy.
1 to 10, the
<Space> No - NA Otherwise Not- Mandatory field.
user has to
enter any one
"If control type for When user-type=Visitor, the fields
number here
respected custom should not be mandatory regardless its
from 1 to 10)
fields is selected value configured in global policy
as Date in Global
Policy:
ddmmyyyy
When Multi
Language is
enabled, Invalid
character set =
SET1

Needs to be supplied when Pre-

invite-req-id 9 numeric No - NA registration is requested using Invite
Visitor Link

Note: If login user is System Account user, and an appointment is submitted using action= set. It will get
automatically approved. (Same as Web Page)

Example1

Sample Request:

To apply for visitor pre-registration through SA user for a valid host user.

http://192.168.104.12/cosec/api.svc/v2/visitor-pre-registration?action=set;visit-date=17012018;visit-
days=1;visitor-arrival-time=1600;visiting-hours-per-day=0100;visitor-name=Rupal;mobile-
no=9685243157;host-id=1;

Sample Response:

success: 0860200002 : saved successfully

458 Matrix COSEC Web API User Guide

The visitor Rupal will be pre-registered with host user Id as 1. You can see the reflection in Visitor Management module> Pre-
Registration.

Example2

Sample Request:

To apply for visitor pre-registration for ESS user login who is a valid host user.

http://192.168.104.12/cosec/api.svc/v2/visitor-pre-registration?action=set;visit-date=17012018;visit-
days=1;visitor-arrival-time=1700;visiting-hours-per-day=0100;visitor-name=Meena;mobile-no=9685243158;

Sample Response:

success: 0860200002 : saved successfully

The visitor Meena will be pre-registered with host user Id as 101. Because the ESS login ID was 101. You can see the reflection in
Visitor Management module> Pre-Registration.

Example3

Sample Request:

To apply for visitor initiated pre-registration application.

http://192.168.104.12/cosec/api.svc/v2/visitor-pre-registration?action=set;user-type=1;visit-
date=05122018;visit-until-date=31122018;visit-start-time=1100;visit-end-time=1600;visitor-
name=Naman;mobile-no=8766678909;

Sample Response:

success: 0860200002 : saved successfully

Once the visitor is pre-registered successfully (Visitor initiated applications) then it will go to “Visit Approval” to the selected/default
host user.

Matrix COSEC Web API User Guide 459

Updating Visitor Pre-registration Application

This API is used for editing the visitor pre-registration application for the required date and specific user id.

Action

action= update

Syntax

http://<servername>/api.svc/v2/visitor-pre-registration?action=<update>;<argument>=<value>...

User Rights

User Rights

System Account Enabled if User has rights on any one of the following Pages.
VMS > Pre-Registration

ESS User Enabled if User has rights on the following Page.

ESS > Basic > Visitor Pre Registration

Visitor Enabled for All Registered Visitors with 'isVerified' flag = 1

Parameters

Table: Updating Visitor Pre-registration details- Parameters

Default Multi language

Argument Valid Values Mandatory Description
Value Support

user-type 0 = Host User / No 0 N

SA User To specify type of user
1 = Visitor

appointment- 0-9 Yes - N If appointment-no not supplied,

no 12 Digits message for Incomplete command:
appointment-no will be displayed.
If appointment-no is invalid or no
corresponding record is found for
logged in user, message : “Invalid
command: appointment-no=” will be
displayed
If logged in SA User / ESS User /
Visitor tried to update visitor pre-
registration application which is in
Checked IN / Start / On Hold / Resume
/ Checked OUT state, message: “Not
allowed to update requested
appointment” will be displayed.

visit-date ddmmyyyy No - N The date for which application is being

submitted.

visit-days 0-9 No - N The days for which visitor is supposed

Range: 1 - 9999 to visit.
Note: "Not Applicable when Logged IN
User is Visitor.

460 Matrix COSEC Web API User Guide

Table: Updating Visitor Pre-registration details- Parameters

Default Multi language

Argument Valid Values Mandatory Description
Value Support

ddmmyyyy No - N Visit Until Date should be greater than

or equals to Visit Date."
Range:
visit-until-date
Current Date to
31/12/2037

0 = Do Not No - N -
Repeat
repeat-mode 1 = Daily
2 = Weekly

1: Sunday No - N Note: Mandatory only when repeat-

2: Monday mode = 2
3: Tuesday
repeat-days 4: Wednesday Multiple days are allowed with comma-
5: Thursday separated format.
6: Friday i.e. repeat-days=1,3,5
7: Saturday

No - N Not Applicable when Logged IN User is

visitor-arrival- hhmm Visitor.
time Range: Visit Time should be less than Visit End
00:00 - 23:59 Time for same visit date and visit until
date.

hhmm No - N Visit Start Time should be less than

visit-start-time Range: Visit End Time for same visit date and
00:00 - 23:59 visit until date.

visiting-hours- hhmm No - N The hours for which visitor is supposed

per-day to visit. Not Applicable when Logged IN
User is Visitor.

visit-end-time hhmm No - N Visit End Time should be later than

Range: Visit Start Time,for same visit date and
00:00 - 23:59 visit until date.

location 0 =Select No 0 N
1=Configured
Not Applicable when Logged IN User is
Location
Visitor
2 = Custom
Location

location-code 6 alpha-numeric No 0 NA
characters.
Mandatory only when location = 1.

latitude -90.0000 to No 0 N
Mandatory only when location = 2.
+90.0000

longitude -180.0000 to No 0 N
+180.0000 Mandatory only when location = 2.

visitor-name 200 characters No - Y (Set2)

0-9
A-Z The name of the visitor. Mandatory field
a-z if supplied mobile number is new.
.-_()[]
<SPACE>

Matrix COSEC Web API User Guide 461

Table: Updating Visitor Pre-registration details- Parameters

Default Multi language

Argument Valid Values Mandatory Description
Value Support

organization- 45 characters No - Y (Set3)

name 0-9 The name of the visitor’s organization.
A-Z Mandatory field if supplied mobile
a-z number is new.
_- ()[].,/+!@$:&*
<SPACE>

designation- 45 characters No - Y(Set3)

name 0-9
A-Z
The name of the visitor’s designation.
a-z
!@$&.,/*()_-+[]:
<SPACE>

mobile-no 20 characters Yes - NA

The mobile number of the visitor.
0-9 ( ) - +

email 125 characters No - Y(Set1) The Email ID of the visitor.

visitor-type Valid Range: 1-99 No - N General, Supplier, Interviewee, Courier

etc

visit-type Valid Range: 1-99 No - N

Personal, Official etc

additional- 0-99 No - N
Escort visitor
visitors

host-id 15 characters No - N For ESS users: (Not Mandatory)

host-id can be any authorized host user
to whom the visit is to be transferred

For SA users: (Not Mandatory)

host-id should be authorized host user.

For Visitor: (Not Mandatory)

host-id should be authorized host user.

additional- Allowed No - N
host characters
A-Z
a-z
0-9
"Multiple hosts User's ID(s) with
/_\\.@:
comma-separated format.
i.e. additional-
Range: Maximum
host=1542,1421,1320,1528
99 Host Users

Max Length for

User ID: 15
Characters

purpose 50 characters No - NA
It is the purpose of visit.

send- 0 = No (Not Set) No 0 N

notification-to- 1 = Yes (Set) To send notification to the visitor.
visitor

vehicle- 15 Characters No - NA
registration-no A-Z
It is the vehicle number.
a-z
0-9

462 Matrix COSEC Web API User Guide

Table: Updating Visitor Pre-registration details- Parameters

Default Multi language

Argument Valid Values Mandatory Description
Value Support

vehicle-type Valid Range: 1-99 No - NA 2 wheeler, 4 wheeler etc

vehicle-
50 Characters No - NA It is the description of vehicle.
description

"If control type for

respected custom
fields is selected
as Textbox in
Global Policy:
Max 100
Alphanumeric
Characters
field<no.>
A-Z Mandatory field, if 'Active' &
a-z 'Mandatory' checkbox is checked for
(where <no>
0-9 respective custom fields in Global
will vary from
[]().-_ / Policy.
1 to 10, the
<Space> No - NA Otherwise Not- Mandatory field.
user has to
enter any one
"If control type for When user-type=Visitor, the fields
number here
respected custom should not be mandatory regardless its
from 1 to 10)
fields is selected value configured in global policy
as Date in Global
Policy:
ddmmyyyy
When Multi
Language is
enabled, Invalid
character set =
SET1

Example1

Sample Request:

To update the arrival time for visitor pre-registration application.

http://192.168.104.12/cosec/api.svc/v2/visitor-pre-registration?action=update;appointment-
no=180117000005;visit-date=17012018;visit-days=1;visitor-arrival-time=1730;visiting-hours-per-
day=0100;visitor-name=Meena;mobile-no=9685243158;

Sample Response:

success: 0860300001: successful

The arrival time of visitor Meena is updated from 17:00 to 17:30 hrs. You can see the reflection in Visitor Management module> Pre-
Registration.

Matrix COSEC Web API User Guide 463

Deleting Visitor Pre-registration application

This API is used for deleting the visitor pre-registration application.

Action

action= delete

Syntax

http://<servername>/api.svc/v2/visitor-pre-registration?action=<delete>;<argument>=<value>...

User Rights

User Rights

System Account Enabled if User has rights on any one of the following Pages.
VMS > Pre-Registration

ESS User Enabled if User has rights on the following Page.

ESS > Basic > Visitor Pre Registration

Visitor Enabled for All Registered Visitors with 'isVerified' flag = 1

Parameters

Table: Deleting Visitor Pre-registration application- Parameters

Argument Valid Values Mandatory Default Value Description

user-type 0 = Host User / SA No 0

User To specify type of user.
1 = Visitor

appointment-no 0-9 Yes - To specify the appointment number of

12 Digits the pre-registered application. This
number is available in Pre-registered
visitors’ details.

If logged in ESS user tried to delete

visitor pre-registration application with
status = approved/ rejected or for past
visit date & visitor arrival time, then it
will be failed.

If logged in Visitor tried to delete visitor

pre-registration application with status
= approved/ rejected or tried to delete
host initiated request, then it will be
failed.

464 Matrix COSEC Web API User Guide

 For SA Users:
All type of applications can be deleted. (Host/Visitor Initiated, Approved, Rejected, Applied/Pending)

For Host Users:

Host user can delete only those applications which are initiated by host (Self) and are in pending/applied
state.

For Visitor:
Visitor can delete only those applications which are initiated by Visitor (Self) and are in pending/applied
state.

Matrix COSEC Web API User Guide 465

Getting Additional Visitors details

This API is used to get the additional visitors details in visitor pre-registration application.

Action

action=get

Syntax

http://<servername>/api.svc/v2/additional-visitors-details?action=<get>;<argument>=<value>...

User Rights

User Rights

System Account Enabled if User has rights on any one of the following Pages.
VMS > Pre-Registration

ESS User Enabled if User has rights on the following Page.

ESS > Basic > Visitor Pre-Registration

Parameters

Table: Getting Additional Visitor details- Parameters

Argument Valid Values Mandatory Default Value Description

appointment-no Valid Values: 0-9 No - To specify the appointment number of

12 Digits the pre-registered application. This
number is available in Pre-registered
visitors’ details.

If logged in ESS user tries to get

additional visitor’s details for some
other host user, then it will be failed.

Response Fields

Table: Getting Additional Visitor details - Response Fields

Field Name Tag Name Valid Values Remarks

SRNO srno 0 to 9 Max 2 digits

Name name 200 Characters

M: Male
Gender gender
F: Female

Mobile No. mobile-no 20 Characters

466 Matrix COSEC Web API User Guide

Adding Additional Visitor details

This API is used to add the additional visitors details in visitor pre-registration application.

Action

action=set

Syntax

http://<servername>/api.svc/v2/additional-visitors-details?action=<set>;<argument>=<value>...

User Rights

User Rights

System Account Enabled if User has rights on any one of the following Pages.
VMS > Pre-Registration

ESS User Enabled if User has rights on the following Page.

ESS > Basic > Visitor Pre-Registration

Parameters

Table: Adding Additional Visitor details- Parameters

Multi
Argument Valid Values Mandatory Default Value Language Description
Support

appointment-no 0-9 Yes - N To specify the appointment number

Max 12 Characters of the pre-registered application in
which additional visitor is to be
added.This number is available in
Pre-registered visitors’ details.

If logged in ESS user tries to add

additional visitor’s details for some
other host user, then it will be failed.

If logged IN SA User / ESS User

tried to set additional visitor's
information in visitor pre-registration
application which is in Checked IN /
Start / On Hold / Resume / Checked
OUT state, then it will be failed

Max 200 - Set1

name Yes Name of the additional visitor
Characters

gender Male - N
Yes Gender of the additional visitor
Female

mobile-no Max 20 Characters No - N Mobile number of the additional

visitor

Matrix COSEC Web API User Guide 467

Example1

Sample Request:

To add the additional visitor in visitor pre-registration application.

http://192.168.104.12/cosec/api.svc/v2/additional-visitors-details?action=set;appointment-
no=180117000005;name=Aditi;gender=Female;

Sample Response:

success: 0880200002 : saved successfully

The additional visitor Aditi is added to the pre-registration application no=180117000005

468 Matrix COSEC Web API User Guide

Updating Additional Visitor details

This API is used to edit the additional visitors details in visitor pre-registration application.

Action

action=update

Syntax

http://<servername>/api.svc/v2/additional-visitors-details?action=<update>;<argument>=<value>...

User Rights

User Rights

System Account Enabled if User has rights on any one of the following Pages.
VMS > Pre-Registration

ESS User Enabled if User has rights on the following Page.

ESS > Basic > Visitor Pre-Registration

Parameters

Table: Updating Additional Visitor details- Parameters

Multi-
Argument Valid Values Mandatory Default Value Language Description
Support

appointment-no 0-9 Yes - N To specify the appointment number of

Max 12 the pre-registered application in which
Characters additional visitor is to be updated.This
number is available in Pre-registered
visitors’ details.

If logged in ESS user tries to update

additional visitor’s details for some
other host user, then it will be failed.

If logged IN SA User / ESS User tried to

set additional visitor's information in
visitor pre-registration application which
is in Checked IN / Start / On Hold /
Resume / Checked OUT state, then it
will be failed.

- N It is the Serial number of additional

srno 0-9 visitors. It can be found from the list of
Yes
Max 2 Digits Additional visitor details in VMS module
or VMS Utility.

Max 200 - Set1

name No Name of the additional visitor
Characters

gender Male - N
No Gender of the additional visitor
Female

mobile-no Max 20 No - N
Mobile number of the additional visitor
Characters

Matrix COSEC Web API User Guide 469

Deleting Additional Visitor details

This API is used to delete the additional visitors details in visitor pre-registration application.

Action

action=delete

Syntax

http://<servername>/api.svc/v2/additional-visitors-details?action=<delete>;<argument>=<value>...

User Rights

User Rights

System Account Enabled if User has rights on any one of the following Pages.
VMS > Pre-Registration

ESS User Enabled if User has rights on the following Page.

ESS > Basic > Visitor Pre-Registration

Parameters

Table: Deleting Additional Visitor details- Parameters

Argument Valid Values Mandatory Default Value Description

appointment-no numeric Yes - To specify the appointment number of

the pre-registered application which is
to be deleted.This number is available
in Pre-registered visitors’ details.

If logged in ESS user tries to delete

additional visitor’s details for some
other host user, then it will be failed.

- It is the Serial number of additional

visitors. It can be found from the list of
Additional visitor details in VMS module
or VMS Utility.
srno
Yes If logged in SA User / ESS User tried to
delete additional visitor's information in
visitor pre-registration application which
is in Checked IN / Start / On Hold /
Resume / Checked OUT state, then it
will be failed.

470 Matrix COSEC Web API User Guide

Visitor Pre-registration Approval

This API is used for approving or rejecting the visitor pre-registration application. The Visitor Pre-Registration
Application will set only if the user is an Authorized Host User.

Action

action= set

Syntax

http://<servername>/api.svc/v2/visitor-pre-registration-approval?action=<set>;<argument>=<value>...

User Rights

User Rights

System Account Enabled if User has rights on any one of the following Pages.
VMS > Pre-Registration Approval

ESS User Enabled if User is RIC user and has rights on the following Pages.
ESS > Approval/Authorization > Pre-Registration Approval

Parameters

Table: Visitor Pre-registration approval- Parameters

Multi
Default
Argument Valid Values Mandatory language Description
Value
Support

appointment-no Max 12 digits Yes - N To specify the appointment number of the

pre-registered application which is to be
deleted.This number is available in Pre-
registered visitors’ details.

verdict 1 : Approve Yes - N Multiple applications can be approved/

2 : Reject rejected at once.

If user tries to approve/reject a record

which is already approved/rejected, then
it will be failed.

Host Official Cell

Host Official E-mail

For an application if first reporting in-

charge has rejected it then it will be failed.

For Any1 mode; if any one of RICs/SA

user has already provided verdict and if
other RIC/SA tries to provide verdict then
it will be failed.

For “All” mode, if final authority in-charge

has provided verdict, and other RICs/SA
tries to provide verdict then it will be
failed.

Matrix COSEC Web API User Guide 471

Table: Visitor Pre-registration approval- Parameters

Multi
Default
Argument Valid Values Mandatory language Description
Value
Support

remark Max 50 Yes - Y(Set2)

Characters
It is the remark given by RIC while
authorizing the application.
_-()[].,/\
+ ! @ $ * : and
<space>

Example1

Sample Request:

To authorize the visitor pre-registration application.

http://192.168.104.12/cosec/api.svc/v2/visitor-pre-registration-approval?action=set;appointment-
no=180118000001;verdict=1;remark=Application approved

Sample Response:

success: 0890200002 : Saved Successfully

472 Matrix COSEC Web API User Guide

Visitor Registration

This API is used for registering the visitor details. It is mandatory to create visitor profile before planning any visit.
So the Visitor Registration API will set details of the visitor.

Action

action= set

Syntax

http://<servername>/api.svc/v2/visitor-registration?action=<set>;<argument>=<value>...

License

User Rights Enabled

System Account Enabled if User has rights on any one of the following Pages.
VMS > Pre-Registration
VMS > Frequent Visitor

ESS User Enabled if User has rights on any one of the following Pages.
ESS > Basic > Visitor Pre Registration

Visitor There should be no restrictions provided for Visitor. It should remain to work without any
authentication.

Parameters

Table: Visitor Registration- Parameters

Multilanguage
Argument Valid Values Mandatory Default Value Description
Support

user-type 0 = Host User / SA No 1 NA

If not supplied, default 1
User
should be considered.
1 = Visitor

visitor-name 200 Characters Yes - Y(Set2)

Valid Characters:
A-Z
It is the name of the visitor.
a-z
0-9
-_. ()[]

mobile-no 20 Digits Yes - NA

It is the Mobile number of
Valid Values: the visitor.
0-9
-+()

Matrix COSEC Web API User Guide 473

Table: Visitor Registration- Parameters

Multilanguage
Argument Valid Values Mandatory Default Value Description
Support

email-id 125 Characters No - Y(Set1) It is the Email ID of the

visitor.
Valid Characters:
Same as User/
Contractor Email Id
Field.

organization 45 Characters Yes - Y(Set3) It is the organization of

visitor
Valid Characters:
A -Z,
a-z,
0 - 9,
#
_- ()[].,/+!@$:&*
<space>

designation 45 Characters No - Y(Set3) It is the designation of visitor

Valid Characters:
A -Z,
a-z,
0 - 9,

#
!@$&.,/*()_-+[]:
<space>

60 Characters -

Valid Values:

A -Z,
address a-z, No Y(Set1) It is the address of visitor
0 - 9,
#
_- ()[].,/
+!@$:&*
<space>

city 30 Characters No - Y(Set1) It is the city of visitor

A -Z,
a-z,
0 - 9,
#
_- ()[].,/
+!@$:&*
<space>

state 30 Characters No - Y(Set1)

A -Z,
a-z,
0 - 9,
It is the state of visitor
#
_- ()[].,/
+!@$:&*
<space>

country 30 Characters No - Y(Set1)

A -Z,
a-z,
0 - 9, It is the country of visitor
#
_- ()[].,/
+!@$:&*

474 Matrix COSEC Web API User Guide

Table: Visitor Registration- Parameters

Multilanguage
Argument Valid Values Mandatory Default Value Description
Support

pincode 10 Characters No - N
It is the pincode of visitor

gender NA, Male, No - NA It is gender of visitor.

Female If not supplied, consider as
NA (Default).

date-of-birth ddmmyyyy No - N
It is date of birth of visitor

nationality 30 Characters No - Y(Set1)

A -Z,
a-z,
0 - 9,
It is the nationality of visitor
#
_- ()[].,/
+!@$:&*
<space>

id-proof1 30 Characters No - Y(Set1)

A-Z
a-z
It is id proof-1 of visitor
0-9
<space>
_-()[].,/+!@$:*

id-proof2 30 Characters No - Y(Set1)

A-Z
a-z
It is id proof-2 of visitor
0-9
<space>
_-()[].,/+!@$:*

is-watchlist 0: No No N
1: Yes

If control type for

respected custom
fields is selected as
Textbox in Global
Policy: Max 100
Alphanumeric
Characters

A-Z
a-z
field<no>
0-9
Mandatory field, if 'Active' &
[]().-_ /
(where <no> will vary 'Mandatory' checkbox is
<Space>
from 1 to 10, the user No - NA checked for respective
has to enter any one custom fields in Global
If control type for
number here from 1 Policy.
respected custom
to 5)
fields is selected as
Date in Global
Policy:
ddmmyyyy
When Multi
Language is
enabled, Invalid
character set =
SET1

Matrix COSEC Web API User Guide 475

 For both returning / new visitors, return visitor id in response on successful API execution. Also if OTP is
generated for Mobile Number Verification, return Mobile OTP = 1, otherwise return Mobile OTP = 0.

If OTP is generated for Email ID verification, return Email OTP = 1, otherwise return Email OTP = 0.

If visitor is already registered visitor, return ‘RegisteredVisitor’ = 1, otherwise ‘Registered Visitor’ = 0.

Example1
Following are some sample cases for this API:

Sample Request:

To register the visitor:

http://192.168.104.12/cosec/api.svc/v2/visitor-registration?action=set;visitor-name=Nishit;mobile-
no=9687624826;organization=Samsung;

Sample Response:

success: 0910200002 : saved successfully. Visitor ID = 2, Mobile OTP = 1, Email OTP = 0

The Mobile OTP is generated which is used for verification of the visitor.

476 Matrix COSEC Web API User Guide

Action

action= get

Argument Valid Values Description

Mobile-number 20 Digits -

Valid Values:
0–9
-+()

Response

Field Name Tag Name Valid Values Remarks

Visitor ID visitor-id 0-9

A-Z
a-z
Visitor Name visitor-name 200 Characters
0-9
-_. ()[]

0 to 9
Mobile No mobile-no 20 Digits
-+()

125 characters

Email ID email-id Valid Characters 125 Characters

Use same characters type as

for pre registration API

45 Characters
Valid Characters:
A –Z,
Organization organization a-z, 45 Characters
0 – 9,
_- ()[].,/
+!@$:#&*)

45 Characters
Valid Characters:
A –Z,
Designation designation a-z, 45 Characters

0 – 9,
_- ()[].,/
+!@$:#&*)

Matrix COSEC Web API User Guide 477

Field Name Tag Name Valid Values Remarks

60 Characters
Valid Values:

A –Z,
Address address 50 Characters
a-z,
0 – 9,
_- ()[].,/
+!@$:#&*)

30 Characters 30 Characters

A –Z,
ID Proof 1 Id-proof1 a-z,
0 – 9,
_- ()[].,/
+!@$:#&*)

30 Characters 30 Characters

A –Z,
ID Proof 2 id-proof2 a-z,
0 – 9,
_- ()[].,/
+!@$:#&*)

0=not generated --
Mobile OTP mobile-otp
1=generated

0=not generated --
Email OTP email-otp
1=generated

Max 100 characters --

Visitor Custom Field 1 Field1
ddmmyyy

Max 100 characters --

Visitor Custom Field 2 Field2
ddmmyyy

Max 100 characters --

Visitor Custom Field 3 Field3
ddmmyyy

Max 100 characters --

Visitor Custom Field 4 Field4
ddmmyyy

Max 100 characters --

Visitor Custom Field 5 Field5
ddmmyyy

478 Matrix COSEC Web API User Guide

 Field Name Tag Name Valid Values Remarks

Uploaded document tag is

added for checking the status
of uploaded images for
respective field. Multiple
values are possible in this field.

60: Field1 If documents/images are

present in field1,2 and 5 then
61: Field2
uploaded-doc should contain
62: Field3 value of field1, field 2 and 5 be
Uploaded Doc uploaded-doc provided in respective field.
63: Field4 For Example in Jason:
"uploaded-doc": "60,61,64"
64: Field5

Example in xml:
<?xml version="1.0"
encoding="UTF-8" ?>
<field5>String</field5>
<field6>String</field6>
<uploaded-doc>60,61,64</
uploaded-doc>

Matrix COSEC Web API User Guide 479

Getting Authorized Host User

This API is used to get details of authorized host user for visitor pre-registration request based on different
parameters.

action= get

Syntax

http://<servername>/api.svc/v2/authorized-host-user?action=<get>;<argument>=<value>...

License

VMS (Visitor Management System) License is required for this API.

User Rights

User Rights

System Account Enabled if User has rights on any one of the following Pages.
Visitor Management > Utilities > Authorized Host User

ESS User Enabled if User has rights on any one of the following Pages.
ESS > Basic > Visitor Pre Registration
ESS > Approval/Authorization > Pre-Registration Approval

Visitor Enabled for All Registered Visitors with 'isVerified' flag = 1

Parameters

Table: Getting Authorized Host Users- Parameters

Argument Valid Values Mandatory Default Value Description

user-type 0 = Host User / No 0

SA User
-
1 = Visitor

search-criteria 1: All No All

For Mobile-No and Email-Id, consider
2: Mobile-No
both personal as well as official contact
3: Email-Id
info.
4: Name

480 Matrix COSEC Web API User Guide

Table: Getting Authorized Host Users- Parameters

Argument Valid Values Mandatory Default Value Description

search-string If search- Yes (For - search-criteria = 1

criteria=2 / 3, Search- All Characters except few special
minimum 3 digits criteria=2,3,4) characters such as
is required. &, ', ", <, >, ; & # \

If search-
criteria=4, search-criteria = 2
minimum 1 0-9
characters.
search-criteria = 3
All Characters except few special
characters such as &, ', ", <, >, ; & # \

search-criteria = 4
Allowed Characters
A-Z
a-z
0-9
-_. ()[]

Response Fields

Table: Authorized Host Users - Response Fields

Field Name Tag Name Valid Values Remarks

User ID user-id 15 characters

-

User Name user-name 45 characters -

0: No
Default-Host default-host -
1: Yes

Personal Mobile No personal-mobile-no 0-9 -

0-9
Official Mobile No official-mobile-no -

Personal Email Id personal-email-id - -

Official Email Id official-email-id - -

This is the 'Organization'

Organization Organization 1-999999
of the user.

This is the 'Department' of

Department Department 1-999999
the user.

Matrix COSEC Web API User Guide 481

Table: Authorized Host Users - Response Fields

Field Name Tag Name Valid Values Remarks

This is the 'Designation' of

Designation 1-999999
Designation the user.

482 Matrix COSEC Web API User Guide

Getting VMS Setting

This API is used to get VMS configuration for HOST Users regarding auto transfer & auto approval configuration.

Action

action= get

Syntax

http://<servername>/api.svc/v2/vms-setting?action=<get>;<argument>=<value>...

License

VMS (Visitor Management System) License is required for this API.

User Rights

User Rights

System Account Enabled if User has rights on any one of the following Pages.
Visitor Management > Utilities > Visit Request Handling

ESS User Enabled if User has rights on any one of the following Pages.
ESS > Visitor Management > Visit Request Handling

Parameters

Table: Getting VMS Setting- Parameters

Argument Valid Values Mandatory Default Value Description

user-id 15 characters Yes - For ESS user:

User-id can be login user's ID.

For a System Account user:

User-id can be any user's id which is
authorized host user.

Response Fields

Table: Getting VMS Setting - Response Fields

Field Name Tag Name Valid Values Remarks

User ID user-id Max 15 characters

User Name user-name max 45 alphanumeric characters

Matrix COSEC Web API User Guide 483

Table: Getting VMS Setting - Response Fields

Field Name Tag Name Valid Values Remarks

1: Enable
Auto Transfer auto-transfer -
0: Disabled

Transfer To transfer-to Maximum 15 characters -

1: Enable
Auto Approval-Rejection auto-approval-rejection 0: Disabled -

Days for which auto

1: Sunday
approval of visitor initiated
2: Monday
pre-registrations are
3: Tuesday
enabled.
4: Wednesday
Working Days working-days
5: Thursday
Return working days in
6: Friday
comma-separated format:
7: Saturday
i.e.
working-days=1,3,5

Work Start Time work-start-time hh:mm 00:00 - 23:59

Work End Time work-end-time hh:mm 00:00 - 23:59

Break Start Time break-start-time hh:mm 00:00 - 23:59

Break End Time break-end-time hh:mm 00:00 - 23:59

Range: 0-999
Time in minutes.
Overlapping visit duration
Allow Overlap Time allow-overlap-time 0-9
must be within entered
time to auto approval.

484 Matrix COSEC Web API User Guide

Setting VMS Configuration

This API is used to set VMS configuration for HOST Users regarding auto transfer & auto approval configuration.

Action

action= set

Syntax

http://<servername>/api.svc/v2/vms-setting?action=<set>;<argument>=<value>...

License

VMS (Visitor Management System) License is required for this API.

User Rights

User Rights

System Account Enabled if User has rights on any one of the following Pages.
Visitor Management > Utilities > Visit Request Handling

ESS User Enabled if User has rights on any one of the following Pages.
ESS > Visitor Management > Visit Request Handling

Parameters

Table: Setting VMS Configuration- Parameters

Default Multilanguage
Argument Valid Values Mandatory Description
Value Support

user-id 15 characters Yes - N For ESS user:

User-id can be login user's ID.

For a System Account user:

User-id can be any user's id
which is authorized host user.

auto-transfer 1: Enable No - N
-
0: Disabled

transfer-to Maximum 15 Mandatory N For a System Account user:

characters. (when auto- "User-id can be any user's id
transfer = 1) which is authorized host user.

auto-approval- 1: Enable No - N
rejection 0: Disabled

Matrix COSEC Web API User Guide 485

Table: Setting VMS Configuration- Parameters

Default Multilanguage
Argument Valid Values Mandatory Description
Value Support

working-days 1: Sunday Mandatory - N Days for which auto approval of

2: Monday when auto- visitor initiated pre-registrations
3: Tuesday approval- are enabled.
4: Wednesday rejection = 1.
5: Thursday You can also select multiple
6: Friday working-days, each separated by
7: Saturday ", (comma)"
e.g: working-days=1,2,3,4,5

work-start-time hhmm Mandatory - N

(24 Hrs Format) when auto-
-
approval-
rejection = 1.

work-end-time hhmm Mandatory - N

(24 Hrs Format) when auto-
approval- -
rejection = 1.

break-start-time hhmm Mandatory - N

(24 Hrs Format) when auto-
-
approval-
rejection = 1.

break-end-time hhmm Mandatory - N

(24 Hrs Format) when auto-
-
approval-
rejection = 1.

allow-overlap- 0-9 No - N It is the time in

time minutes.Applicable only when
auto-approval-rejection = 1.

486 Matrix COSEC Web API User Guide

Getting Host Unavailability Days

This API is used to get Holidays / Unavailable Days for Host User for Visitor initiated Pre-Registration Application.

Action

action= get

Syntax

http://<servername>/api.svc/v2/host-unavailability-days?action=<get>;<argument>=<value>...

License

VMS (Visitor Management System) License is required for this API.

User Rights

User Rights

System Account Enabled if User has rights on any one of the following Pages.
Visitor Management > Utilities > Visit Request Handling

ESS User Enabled if User has rights on any one of the following Pages.
ESS > Visitor Management > Visit Request Handling

Parameters

Table: Getting Host Unavailability Days- Parameters

Argument Valid Values Mandatory Default Value Description

user-id 15 characters Yes - For ESS user:

User-id can be login user's ID.

For a System Account user:

User-id can be any user's id which is
authorized host user.

Response Fields

Table: Getting Host Unavailability Days - Response Fields

Field Name Tag Name Valid Values Remarks

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

Matrix COSEC Web API User Guide 487

Table: Getting Host Unavailability Days - Response Fields

Field Name Tag Name Valid Values Remarks

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

SRNO srno 0-9 Max 2 digits

Date date mm/dd/yyyy -

Allowed Characters:

Unavailability Reason unavailability-reason All Characters except few special Max 30 Characters
characters such as
&, ', ", <, >, ; & #

488 Matrix COSEC Web API User Guide

Set Host Unavailability Days

This API is used to set Holidays / Unavailable Days for Host User for Visitor initiated Pre-Registration Application.

Action

action= set

Syntax

http://<servername>/api.svc/v2/host-unavailability-days?action=<set>;<argument>=<value>...

License

VMS (Visitor Management System) License is required for this API.

User Rights

User Rights

System Account Enabled if User has rights on any one of the following Pages.
Visitor Management > Utilities > Visit Request Handling

ESS User Enabled if User has rights on any one of the following Pages.
ESS > Visitor Management > Visit Request Handling

Parameters

Table: Set Host Unavailability Days- Parameters

Multilanguage
Argument Valid Values Mandatory Default Value Description
Support

15 Characters Yes - N For ESS user:

User-id should be login user's
ID.
user-id
For a System Account user:
User-id can be any user's id
which is authorized host user.

date ddmmyyyy Yes - N

unavailability- Max 30 Char Yes - Y It is the reason for unavailability

reason Invalid Char Set: of the host.
Allowed Char: NA
All Characters
except few
special
characters such
as
&, ', ", <, >, ; & #

Matrix COSEC Web API User Guide 489

Update Host Unavailability Days

This API is used to update Holidays / Unavailable Days for Host User for Visitor initiated Pre-Registration
Application.

Action

action= update

Syntax

http://<servername>/api.svc/v2/host-unavailability-days?action=<update>;<argument>=<value>...

License

VMS (Visitor Management System) License is required for this API.

User Rights

User Rights

System Account Enabled if User has rights on any one of the following Pages.
Visitor Management > Utilities > Visit Request Handling

ESS User Enabled if User has rights on any one of the following Pages.
ESS > Visitor Management > Visit Request Handling

Parameters

Table: Update Host Unavailability Days- Parameters

Multilanguage
Argument Valid Values Mandatory Default Value Description
Support

15 Characters Yes - N For ESS user:

User-id should be login user's ID.
user-id
For a System Account user:
User-id can be any user's id which is
authorized host user.

0-9 Yes - N
srno
Max 2 Digits

date ddmmyyyy Yes - Y

Invalid Char
Set: NA

490 Matrix COSEC Web API User Guide

Table: Update Host Unavailability Days- Parameters

Multilanguage
Argument Valid Values Mandatory Default Value Description
Support

unavailability- Max 30 Char Yes - - It is the reason for unavailability of the

reason host.
Allowed Char:
All Characters
except few
special
characters such
as
&, ', ", <, >, ; & #

Matrix COSEC Web API User Guide 491

Delete Host Unavailability Days

This API is used to delete Holidays / Unavailable Days for Host User for Visitor initiated Pre-Registration
Application.

Action

action= delete

Syntax

http://<servername>/api.svc/v2/host-unavailability-days?action=<delete>;<argument>=<value>...

License

VMS (Visitor Management System) License is required for this API.

User Rights

User Rights

System Account Enabled if User has rights on any one of the following Pages.
Visitor Management > Utilities > Visit Request Handling

ESS User Enabled if User has rights on any one of the following Pages.
ESS > Visitor Management > Visit Request Handling

Parameters

Table: Delete Host Unavailability Days- Parameters

Argument Valid Values Mandatory Default Value Description

15 Characters Yes - For ESS user:

User-id should be login user's ID.
user-id
For a System Account user:
User-id can be any user's id which is
authorized host user.

Yes - if invalid date is specified or no date is

date ddmmyyyy
specified, then it will be failed.

492 Matrix COSEC Web API User Guide

Getting Visitor Details

This API is used to get visitor details.

Action

action= get

Syntax

http://<servername>/api.svc/v2/visitor?action=<get>;<argument>=<value>...

License

VMS (Visitor Management System) License is required for this API.

User Rights

User Rights

System Account Enabled if User has rights on any one of the following Pages.
VMS > Pre-Registration
VMS > Pre-Registration Approval

ESS User Enabled only for Action= Get and Set, if User has rights on any one of the following Pages.
ESS > Basic > Visitor Pre Registration
ESS > Approval/Authorization > Pre-Registration Approval

Visitor Enabled for All Registered Visitors

Parameters

Table: Getting Visitor Details- Parameters

Argument Valid Values Mandatory Default Value Description

user-type 0 = Host User / No 0

SA User
1 = Visitor

visitor-filter 0 : individual No 0 Visitor-filter=1 is not applicable if logged

1: all in user is Visitor.

search-criteria 1: All No 0
2: Mobile-No
Applicable only for visitor-filter = 1
3: Email-Id
4: Name

Matrix COSEC Web API User Guide 493

Table: Getting Visitor Details- Parameters

Argument Valid Values Mandatory Default Value Description

search-string If search- No - Applicable only for visitor-filter = 1,

criteria=2 / 3, otherwise it should be ignored.
minimum 1 digits
is required. search-criteria = 1
All Characters except few special
If search-
characters such as
criteria=4, &, ', ", <, >, ; & #
minimum 1
characters.
search-criteria = 2
0-9, ( ) - +

search-criteria = 3
All Characters except few special
characters such as &, ', ", <, >, ; & #

search-criteria = 4
Allowed Characters
A-Z
a-z
0-9
-_. ()[]

visitor-id 15 alphanumeric Yes (when -

Char. (for user) visitor-filter=0)
if logged IN user is visitor and supplied
A to Z
visitor-id is of some other visitor's id, then
a to z
it will not be allowed.
0 to 9
/_\\.@:

Response Fields

Table: Getting Visitor Details - Response Fields

Field Name Tag Name Valid Values Remarks

Visitor ID visitor-id 0-9 -

Visitor Name visitor-name - 200 characters

20 Digits
Mobile No mobile-no 0-9

Email ID email-id - 125 Characters

Organization organization - 45 Characters

Designation designation - 45 Characters

Address address - 60 Characters

494 Matrix COSEC Web API User Guide

Table: Getting Visitor Details - Response Fields

Field Name Tag Name Valid Values Remarks

City city - 30 Characters

State state - 30 Characters

Country country - 30 Characters

Pincode pincode - 30 Characters

Gender gender NA, Male, Female

Date of Birth date-of-birth ddmmyyyy

30 Characters
Nationality nationality -

30 Characters
ID Proof 1 Id-proof1 -

30 Characters
ID Proof 2 id-proof2 -

Return this flag as 0 till the

time OTP Verification is
done, system should mark
1: Yes
the Visitor as 'Unverified'.
Verified User verified-user 0: No
Once OTP verification is
successfully done, return
this flag as 1.

Only Host and System

0: Frequent Visitor Admin login have the rights
Watchlist User is-watchlist 1: Watchlist for firing API to set the
2: Blacklist value for parameter > is-
watchlist= 0 or 1 or 2

Max 100 characters --

Visitor Custom Field 1 Field1
ddmmyyy

Max 100 characters --

Visitor Custom Field 2 Field2
ddmmyyy

Max 100 characters --

Visitor Custom Field 3 Field3
ddmmyyy

Max 100 characters --

Visitor Custom Field 4 Field4
ddmmyyy

Max 100 characters --

Visitor Custom Field 5 Field5
ddmmyyy

Matrix COSEC Web API User Guide 495

Table: Getting Visitor Details - Response Fields

Field Name Tag Name Valid Values Remarks

Uploaded document tag is

added for checking the
status of uploaded images
for respective field.
Multiple values are
possible in this field.

If documents/images are
60: Field1 present in field1,2 and 5
then uploaded-doc should
61: Field2
contain value of field1,
62: Field3 field 2 and 5 be provided
Uploaded Doc uploaded-doc in respective field.
63: Field4 For Example in Jason:
"uploaded-doc":
64: Field5
"60,61,64"

Example in xml:
<?xml version="1.0"
encoding="UTF-8" ?>
<field5>String</field5>
<field6>String</field6>
<uploaded-
doc>60,61,64</uploaded-
doc>

496 Matrix COSEC Web API User Guide

Set Visitor Details

This API is used to edit visitor profile details.

Action

action= set

Syntax

http://<servername>/api.svc/v2/visitor?action=<set>;<argument>=<value>...

License

VMS (Visitor Management System) License is required for this API.

User Rights

User Rights

System Account Enabled if User has rights on any one of the following Pages.
VMS > Pre-Registration
VMS > Pre-Registration Approval

ESS User Enabled only for Action= Get and Set, if User has rights on any one of the following Pages.
ESS > Basic > Visitor Pre Registration
ESS > Approval/Authorization > Pre-Registration Approval

Visitor Enabled for All Registered Visitors

Parameters

Table: Set Visitor Details- Parameters

Default Multilanguage
Argument Valid Values Mandatory Description
Value Support

user-type 0 = Host User / No 0 N

SA User
1 = Visitor

visitor-id 15 Yes 0 N Visitor-filter=1 is not applicable if logged

alphanumeric in user is Visitor.
Char. (for user)
A to Z
a to z
0 to 9
/_\\.@:

Matrix COSEC Web API User Guide 497

Table: Set Visitor Details- Parameters

Default Multilanguage
Argument Valid Values Mandatory Description
Value Support

email-id 125 Characters No - Y (Set1) It is the Email ID of the visitor.

Valid
Characters:
All Characters
except few
special
characters such
as
`~#%^*={}|\\;\"'<
>?

visitor-name 200 Characters No - Y (Set2)

Valid
Characters:
A-Z
a-z
0-9
-_. ()[]

mobile-no 20 Digits No - NA
It is the Mobile number of the visitor.
Valid Values:
0-9
-+()

organization 45 Characters Yes - Y (Set 3) It is the organization of visitor

0-9
A-Z
a-z
_- ()[].,/+!@$:&*
<SPACE>

designation 45 Characters No - Y (Set 3) It is the designation of visitor

0-9
A-Z
a-z
!@$&.,/*()_-+[]:
<SPACE>

address 60 Characters No - Y (Set 1) It is the address of visitor

A-Z
a-z
0-9
_- ()[].,/+!@$:&*
<SPACE>

city 30 Characters No - Y (Set 1) It is the city of visitor

A-Z
a-z
0-9
_- ()[]/+!@$:&*.,
<SPACE>

state 30 Characters No - Y (Set 1)

A-Z
a-z
It is the state of visitor
0-9
_- ()[].,/+!@$:&*
<SPACE>

498 Matrix COSEC Web API User Guide

Table: Set Visitor Details- Parameters

Default Multilanguage
Argument Valid Values Mandatory Description
Value Support

country 30 Characters No - Y (Set 1)

A-Z
a-z
It is the country of visitor
0-9
_- ()[].,/+!@$:&*
<SPACE>

pincode 10 Characters No - N It is the pincode of visitor

gender Male, No - NA
It is gender of visitor
Female

date-of-birth ddmmyyyy No - NA
It is date of birth of visitor

nationality 30 Characters No - Y (Set 1)

A-Z
a-z
It is the nationality of visitor
0-9
_- ()[].,/+!@$:*
<SPACE>

id-proof1 30 Characters No - Y (Set 1)

A-Z
a-z
It is id proof-1 of visitor
0-9
_- ()[].,/+!@$:*
<SPACE>

id-proof2 30 Characters No - Y (Set 1)

A-Z
a-z
It is id proof-2 of visitor
0-9
_- ()[].,/+!@$:*
<SPACE>

is-watchlist 0: Frequent No 0,if no N

Only Host and System Admin login have
Visitor value is
the rights for firing API to set the value for
1: Watchlist supplied.
parameter > is-watchlist= 0 or 1 or 2
2: Blacklist

Matrix COSEC Web API User Guide 499

Table: Set Visitor Details- Parameters

Default Multilanguage
Argument Valid Values Mandatory Description
Value Support

If control type
for respected
custom fields is
selected as
Textbox in
Global Policy:
Max 100
Alphanumeric
Characters

field<no> A-Z
a-z Mandatory field, if 'Active' & 'Mandatory'
(where <no> 0-9 checkbox is checked for respective
will vary from []().-_ / custom fields in Global Policy.
1 to 10, the <Space> No - NA
user has to When user-type=Visitor, the fields should
enter any one If control type not be mandatory regardless its value
number here for respected configured in global policy.
from 1 to 5) custom fields is
selected as
Date in Global
Policy:
ddmmyyyy
When Multi
Language is
enabled, Invalid
character set =
SET1

500 Matrix COSEC Web API User Guide

Deleting Visitor Details

This API is used to delete visitor profile details.

Action

action= delete

Syntax

http://<servername>/api.svc/v2/visitor?action=<delete>;<argument>=<value>...

License

VMS (Visitor Management System) License is required for this API.

User Rights

User Rights

System Account Enabled if User has rights on any one of the following Pages.
VMS > Pre-Registration
VMS > Pre-Registration Approval

Parameters

Table: Delete Visitor Details- Parameters

Argument Valid Values Mandatory Default Value Description

user-type 0 = Host User / No 0

SA User
1 = Visitor

visitor-id 15 alphanumeric Yes 0 Visitor-filter=1 is not applicable if logged

Char. (for user) in user is Visitor.
A to Z
a to z
0 to 9
/_\\.@:

Matrix COSEC Web API User Guide 501

Getting Visitor Profile

This API will be used to create a new Visitor’s profile.

Action

action= Get

Syntax

http://<cosec_server>/api.svc/v2/visitor-profile?action=<get>;<argument>=<value>...

License

Basic+VMS (Visitor Management System) License is required for this API.

User Rights

User Rights

System account user Enabled if User has rights on Page :

Visitor Management > Visitor Profile > view rights

ESS User Disabled

Parameters

Table: Getting Visitor Profile- Parameters

Argument Valid Values Mandatory Default Value Description

id 15 characters No - This is the visitor profile Id.

Valid Values:
A-Z If not mentioned, return records of all
a-z Visitor Profiles as per the rights available
0-9 to the logged in system account user.
@_ :./ Should allow to pass comma separated
ids.

502 Matrix COSEC Web API User Guide

Table: Getting Visitor Profile- Parameters

Argument Valid Values Mandatory Default Value Description

filter 0 : All No 0 Non mandatory field.

1 : Active Visitor
Profiles Default value = 0.
2 : Inactive Visitor
Profiles Conditions:
1.Argument mentioned, but value not
specified, then ignore this parameter.

2.If filter=0 is specified, return all visitor

profiles configured in the system.

3.If filter=1 is specified, return only active

visitor profiles configured in the system.

4.If filter=2 is specified, return only

inactive visitor profiles configured in the
system.

Note:
If filter=1 is specified and multiple-ids are
passed or any enterprise group is passed,
out of which some of them are inactive,
then do not return those visitor profiles
and vice-versa should also be applicable.

If filter=2 is specified and multiple-ids are

passed or any enterprise group is passed,
out of which some of them are active,
then do not return those visitor profiles
and vice-versa should also be applicable.

Response Fields

Table: Getting Visitor Profile - Response Fields

Field Name Tag Name Valid Values Remarks

Allowed Characters
A-Z
id Max 15 chars a-z
Id
0-9
/_.@: \

Field defines whether

Active active 0 or 1 visitor profile is active or
not

Defines whether the Visitor

0 or 1 Profile is free or in use.
status
Status 0 = Free If the Profile is free then
1 = Occupied can be assigned to visitor
else not.

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

Matrix COSEC Web API User Guide 503

Table: Getting Visitor Profile - Response Fields

Field Name Tag Name Valid Values Remarks

A -Z
a-z
Full Name
0-9
()
[]
_ (underscore)
Full-name Max 200 chars - (Hyphen)
. (full Stop)
/
&
, (comma)
@
'(single quote)
[Space]

Defines validity end date of

Access Validity Date access-validity-date ddmmyyyy format
visitor profile.

Max 15 chars
short-name short-name

This is the Reference ID

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

This is the Integration

integration-reference max 20 alphanumeric characters
Integration Reference Reference field

This is the ID of the device

group

If more than one group is

assigned, then it should
fetch multiple group id
separated with comma.
Device Group ID device-group-id
When 99 device
(maximum device allowed)
with individual ID of 5
NUMcharacter is GET then
600 NUMcharacter are
allowed.

This is the name of the

device group

Device Group device-group If more than one group is

assigned, then it should
fetch multiple group name
separated with comma.

This is the access control

PIN pin 0 to 999999999999999 system PIN number of the
Visitor

This is a field that shows

0= unchecked
Roaming User roaming-user-flg whether Visitor is Reaming
1=checked
User or not.

max 20 numeric characters

This is the Access Card 1
Access Card 1 card-1 of the Visitor, required for
max 21 characters= 20 numeric +
access control system.
comma

504 Matrix COSEC Web API User Guide

Table: Getting Visitor Profile - Response Fields

Field Name Tag Name Valid Values Remarks

max 20 numeric characters

This is the Access Card 2
Access Card 2 card-2 of the Visitor, required for
max 21 characters= 20 numeric +
access control system.
comma

Number of fingers enrolled

Enrolled Fingers (Suprema in suprema proprietary
suprema-proprietary-count 0-10
Proprietary) type against a Visitor
Profile

Number of fingers enrolled

Enrolled Fingers (Suprema 0-10
suprema-iso-count in suprema ISO type
ISO)
against a Visitor Profile

Number of fingers enrolled

Enrolled Fingers (Lumidigm 0-10
lumidigm-iso-count in Lumidigm ISO type
ISO)
against a Visitor Profile

Number of fingers enrolled

Enrolled Fingers (Lumidigm 0-10 in Lumidigm proprietary
lumidigm-proprietary-count
Proprietary) type against a Visitor
Profile

Number of palms enrolled

Enrolled Palm enrolled-palms 0-10
for this Visitor Profile

Total Number of faces

Enrolled Faces Enrolled-faces 0-40 enrolled for this Visitor
Profile

Enable/disable visitor
1 – enable bypass bypass the finger
Bypass Finger bypass-finger
0 – disable bypass credential for any access
control feature/rule

Enable/disable visitor
1 – enable bypass bypass the palm credential
Bypass Palm bypass-palm
0 – disable bypass for any access control
feature/rule.

0= unchecked Access Validity applicable

Access Validity access-validity-flg
1=checked to the Visitor or not.

This is the access level

Access Level access-level 1 to 15 assigned to Visitor, used
for access control features.

This field is the the visitor’s

Holiday Schedule holiday-schedule 1 to 99
allowed holidays

This flag tells whether

Enable Advance Access enable-advance-access- 0= unchecked Advance Access Control
Control control 1=checked applicable for the visitor or
not

The access route assigned

Smart Access Route smart-access-route 1 to 99 to the Visitor. (For
Smartcard Users only)

Maximum level assigned

Max Route Level max-route-level 0 to 75 to which Visitor can access
the Smart Access Route.

Matrix COSEC Web API User Guide 505

Table: Getting Visitor Profile - Response Fields

Field Name Tag Name Valid Values Remarks

This flag tells whether

Enable Elevator Access enable-elevator-access- 0= unchecked Elevator Access Control
Control control 1=checked applicable for the visitor or
not.

The floor group assigned

Elevator Floor Group elevator-floor-group 1 to 99 for which Visitor should
have elevator rights

This flag tells whether the

ecanteen.
0= unchecked
Enable Cafeteria Account allow-ecanteen
1=checked (Cafeteria) features
allowed for the selected
Visitor or not.

Visitor applicable discount

Discount Level discount-level 0 to 4 level for any canteen
transactions.

This parameter determines

0 = Prepaid
Account Type account-type the Visitor’s Cafeteria
1= Postpaid
account type.

This parameter determines

the Visitor’s Cafeteria Pre-
Balance Management balance-management balance-management
Paid Account Balance
Management type

This flag tells whether the

0= unchecked Device-Server Balance
Device-Server Balance Check device-server-balance-check
1=checked Check allowed for the
selected Visitor or not.

This defines the max

Allowed Usage Per Month max-allowed-limit 0.01 to 999999.99 allowed limit for the
canteen user for a month.

This defines the max

usage limit for the canteen
user beyond which the
0.01 to 999999.99 Visitor’s canteen account
Max Usage Limit Per Month max-usage-limit
will be blocked.
Value should be as per
Account Type, i.e., Prepaid
or Postpaid

This defines the max daily

usage limit for the canteen
user beyond which the
0.01 to 999999.99 Visitor’s canteen account
Max Usage Limit Per Day max-usage-limit-per-day
will be blocked.
Value should be as per
Account Type, i.e., Prepaid
or Postpaid

Cafeteria usage policy for

Cafeteria Usage Policy cafeteria-usage-policy 1 to 99
Visitor.

This flag determines

whether the Face
0= unchecked
Enable Face Recognition enable-fr Recognition feature
1=checked
applicable for access
control of visitor or not.

Organization ID organization 1 - 999999 -

506 Matrix COSEC Web API User Guide

Table: Getting Visitor Profile - Response Fields

Field Name Tag Name Valid Values Remarks

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 -

Custom Group 1 ID customgroup1ID 1 -9 99999 -

Custom Group 2 ID customgroup2ID 1 - 999999 -

Custom Group 3 ID customgroup3ID 1 - 999999 -

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 -

Custom Group 1 Code customgroup1_code max 6 alphanumeric characters -

Custom Group 2 Code customgroup2_code max 6 alphanumeric characters -

Custom Group 3 Code customgroup3_code max 6 alphanumeric characters -

Should return the

Organization Name organization-name Organization Name of
User

Should return the Branch

Branch Name branch-name
Name of User

Should return the

Department Name department-name
Department Name of User

Should return the Category

Category Name category-name
Name of User

Should return the Grade

Grade Name grade-name
Name of User

Should return the

Designation Name designation-name
Designation Name of User

Should return the Section

Section Name section-name
Name of User

Should return the Custom

Custom Group 1 Name customgroup1_name
Group 1 Name of User

Should return the Custom

Custom Group 2 Name customgroup2_name
Group 2 Name of User

Should return the Custom

Custom Group 3 Name customgroup3_name
Group 3 Name of User

Matrix COSEC Web API User Guide 507

Table: Getting Visitor Profile - Response Fields

Field Name Tag Name Valid Values Remarks

0= None
Enable Offline-Transaction enable-offline-transaction 1= Allow With Discount
2= Allow Without Discount

508 Matrix COSEC Web API User Guide

Setting Visitor Profile

This API will be used to set new visitor’s profile.

Action

action= set

Table 1: Set Visitor profile- Parameters

Argument Valid Values Mandatory Description

Should be same as per User

id Yes This is the visitor profile ID.
API

Max 45 Characters

Allowed Characters This is the name field.

A-Z
name No
a-z Mandatory field (Optional, if full name tag
0-9 is mentioned or case of edit model.)
-_. ()[]
[Space]

max 200 chars

A –Z
a-z
0–9
()
[]
_ (underscore)
- (Hyphen) This is the Full Name field.
. (full Stop)
full-name No
/ Mandatory only if “name” tag is not
& mentioned. Otherwise, Not Mandatory
, (comma)
@
‘(single quote)
[Space]

When Multi Language is On,

Invalid Character set = Set 3

short-name should be as per User API No This is the short name field.

This is the Reference ID field.

reference-code 1 to 99999999 No Unique Reference code for every Visitor

Profile ID should be auto-generated by
system if mentioned value already exists.

This is a field that shows whether Visitor

0 : Inactive Profile is active or not.
1 : Active Note: While creating new Visitor Profile, if
active No
2 : Inactive and Revoke active = 2 is passed then no action should
Devices be performed and created Visitor Profile
will be active by default.

Matrix COSEC Web API User Guide 509

Table 1: Set Visitor profile- Parameters

Argument Valid Values Mandatory Description

This is the Integration Reference field.

This field is provided for integration with

third party software applications (e.g.:
Payroll). In third party applications where
Should be same as per User
integration-reference No the visitor ID has more number of
API
characters and if it wants to integrate with
COSEC Application then it can use
Integration reference to map COSEC to
third party software. (same as per User
API)

This is the ID of the device group.

Allow passing multiple device group ID

values separated by comma.

Note: Any value SET from this API will

Maximum length 600 overwrite the existing value.
NUMCHAR
device-group-id No
If from the entered Device Group IDs only
Blank partial values are valid, then assign the
valid Device Groups mentioned.

When 99 device (maximum device

allowed) with individual ID of 5
NUMcharacter is SET then 600
NUMcharacter are allowed.

This is the name of the device group.

Multiple device group names are allowed

to pass.

device-group If maximum 99 device group names are

added, there is a possibility that it would
lead to exceed maximum URL limit.
In such cases the server will notify the SA
via message and the SA needs to hit
multiple API.

0 to 999999999999999
This is the access control system PIN
pin No
number of the Visitor.
Blank

0= unchecked This is a field that shows whether Visitor is

roaming-user-flg No
1=checked Reaming User or not.

max 20 numeric characters This is the Access Card 1 of the Visitor,

required for access control system.
card-1
max 21 characters= 20 Note: System should not allow same
numeric + comma value of “card-1” & “card-2” against any ID

This is the Access Card 2 of the Visitor,

max 20 numeric characters required for access control system.
card-2
max 21 characters= 20 Note: System should not allow same
numeric + comma value of “card-1” & “card-2” against any
ID.

This flag determines whether the visitor

0= unchecked
bypass-finger No can bypass the finger credential for any
1=checked
access control feature/rule.

510 Matrix COSEC Web API User Guide

Table 1: Set Visitor profile- Parameters

Argument Valid Values Mandatory Description

0= unchecked This flag determines whether the visitor

bypass-palm 1=checked No can bypass the palm credential for any
access control feature/rule.

0= unchecked This flag determines whether the Access

access-validity-flg 1=checked No Validity should be applicable to the Visitor
or not

This is the access validity date of the

Visitor.

This is an Optional field. (Mandatory, if

“access-validity-flg =1”)
access-validity-date ddmmyyyy format No
Not applicable when “access-validity-flg
=0”. So, skip the value mentioned in
“access-validity-date” tag.

Applicable only when “access-validity-flg

=1”

This is the access level assigned to

access-level 1-15 No
Visitor, used for access control features

This field defines the visitor’s allowed

holiday-schedule 1-99 No
holidays.

This flag determines whether Advance

enable-advance-access- 0= unchecked
No Access Control should be applicable for
control 1=checked
the visitor or not.

This field assigns the access route to the

Visitor. (For Smartcard Users only)

Not applicable when “enable-advance-

smart-access-route 1-99 No access-control =0”. So, skip the value
mentioned in “smart-access-route” tag.

Applicable only when “enable-advance-

access-control =1”

This field assigns maximum level to which

Visitor can access the Smart Access
Route.
Not applicable when “enable-advance-
max-route-level 0 to 75 No
access-control =0”. So, skip the value
mentioned in “max-route-level” tag.
Applicable only when “enable-advance-
access-control =1”

This flag determines whether Elevator

Access Control should be applicable for
the visitor or not.
enable-elevator-access- 0= unchecked Not applicable when “enable-advance-access-
No
control 1=checked control =0”. So, skip the value mentioned in
“enable-elevator-access-control” tag.
Applicable only when “enable-advance-
access-control =1”

Matrix COSEC Web API User Guide 511

Table 1: Set Visitor profile- Parameters

Argument Valid Values Mandatory Description

This field assigns the floor group for which

Visitor should have elevator rights
This is an Optional field.
Not applicable when either “enable-
advance-access-control =0” or “enable-
elevator-floor-group 1-99 No elevator-access-control =0”. So, skip the
value mentioned in “elevator-floor-group”
tag.
Applicable only when both “enable-
advance-access-control =1” and “enable-
elevator-access-control =1”

0= unchecked 0= unchecked
allow-ecanteen No
1=checked 1=checked

This value defines the Visitor applicable

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

0 = Prepaid
This parameter determines the Visitor’s
account-type 1= Postpaid No
Cafeteria account type.

This defines the max allowed limit for the

max-allowed-limit 0.01 - 999999.99 No
canteen user for a month

This defines the max usage limit for the

canteen user beyond which the Visitor’s
canteen account will be blocked.
max-usage-limit 0.01 - 999999.99 No
(Consideration for Value passed should
be as per Account Type, i.e., Prepaid or
Postpaid

This defines the max daily usage limit for

the canteen user beyond which the
0.01 - 999999.99 Visitor’s canteen account will be blocked.
max-usage-limit-per-day No
(Consideration for Value passed should
be as per Account Type, i.e., Prepaid or
Postpaid

This parameter defines the Visitor’s

0 = Device Based
balance-management No Cafeteria Pre-Paid Account Balance
1= Server Based
Management type

This flag determines whether the Device-

Server Balance Check should be allowed
for the selected Visitor or not.
0= unchecked
device-server-balance-check No
1=checked
If “balance-management=0” passed then
“device-server-balance-check =0” should
be considered.

cafeteria-usage-policy 1-99 No Cafeteria usage policy for Visitor.

This flag determines whether the Face

0= unchecked
enable-fr No Recognition feature should be applicable
1=checked
for access control of visitor.

512 Matrix COSEC Web API User Guide

Table 1: Set Visitor profile- Parameters

Argument Valid Values Mandatory Description

This is the 'Organization' of the user.

Note: if the user specifies the organization

id and organization code in same http
request, then give error “Organization ID
and Code cannot be specified together”

organization 1 - 999999 No Default organization of respective system

account user who is creating/updating
visitor

OR

Default organization defined in Enterprise

structure

This is the 'Branch' of the user.

Note: if the user specifies the Branch id

and Branch code in same http request,
then give error “Branch ID and Code
cannot be specified together”

branch 1 - 999999 No Default branch of respective system

account user who is creating/updating
visitor

OR

Default branch defined in Enterprise

structure

This is the 'Department' of the user.

Note: if the user specifies the Department

id and Department code in same http
request, then give error “Department ID
and Code cannot be specified together”

department 1 - 999999 No Default department of respective system

account user who is creating/updating
visitor

OR

Default department defined in Enterprise

structure

This is the 'Section' of the user.

Note: if the user specifies the Section id

and Section code in same http request,
then give error “Section ID and Code
cannot be specified together”

section 1 - 999999 No Default section of respective system

account user who is creating/updating
visitor

OR

Default section defined in Enterprise

structure

Matrix COSEC Web API User Guide 513

Table 1: Set Visitor profile- Parameters

Argument Valid Values Mandatory Description

This is the 'Category' of the user.

Note: if the user specifies the Category id

and Category code in same http request,
then give error “Category ID and Code
cannot be specified together”

category 1 - 999999 No Default category of respective system

account user who is creating/updating
visitor

OR

Default category defined in Enterprise

structure

This is the 'Grade' of the user.

Note: if the user specifies the Grade id

and Grade code in same http request,
then give error “Grade ID and Code
cannot be specified together”

grade 1 - 999999 No Default grade of respective system

account user who is creating/updating
visitor

OR

Default grade defined in Enterprise

structure

This is the 'Designation' of the user.

Note: if the user specifies the Designation

id and Designation code in same http
request, then give error “Designation ID
and Code cannot be specified together”

designation 1 - 999999 No Default designation of respective system

account user who is creating/updating
visitor

OR

Default designation defined in Enterprise

structure

This is the 'Custom Group 1' of the user.

Note: if the user specifies the Custom

Group 1 id and Custom Group 1 code in
same http request, then give error
“Custom Group 1 ID and Code cannot be
specified together”
customgroup1ID 1 -9 99999 No
Default customGroup1ID of respective
system account user who is creating/
updating visitor

OR

Default customGroup1ID defined in

Enterprise structure

514 Matrix COSEC Web API User Guide

Table 1: Set Visitor profile- Parameters

Argument Valid Values Mandatory Description

This is the 'Custom Group 2' of the user.

Note: if the user specifies the Custom

Group 2 id and Custom Group 2 code in
same http request, then give error
“Custom Group 2 ID and Code cannot be
specified together”
customgroup2ID 1 - 999999 No
Default customGroup2ID of respective
system account user who is creating/
updating visitor

OR

Default customGroup2ID defined in

Enterprise structure

This is the 'Custom Group 3' of the user.

Note: if the user specifies the Custom

Group 3 id and Custom Group 3 code in
same http request, then give error
“Custom Group 3 ID and Code cannot be
specified together”
customgroup3ID 1 - 999999 No
Default customGroup3ID of respective
system account user who is creating/
updating visitor

OR

Default customGroup3ID defined in

Enterprise structure

When this code is specified, the system

should get the code's corresponding id
and apply this id to the user.

If code is invalid or does not exist, the

system should give error “Organization
Code is either invalid or does not exist”

If organization id is also specified then the

max 6 alphanumeric system should give error “Organization ID
organization_code No
characters and Code cannot be specified together”

Default organization code of respective

system account user who is creating/
updating visitor

OR

Default organization code defined in

Enterprise structure

Matrix COSEC Web API User Guide 515

Table 1: Set Visitor profile- Parameters

Argument Valid Values Mandatory Description

When this code is specified, the system

should get the code's corresponding id
and apply this id to the user.

If branch id is also specified then the

system should give error “Branch ID and
Code cannot be specified together”
max 6 alphanumeric
branch_code No
characters Default branch code of respective system
account user who is creating/updating
visitor

OR

Default branch code defined in Enterprise

structure

When this code is specified, the system

should get the code's corresponding id
and apply this id to the user.

If Department id is also specified then the

system should give error “Department ID
and Code cannot be specified together”
max 6 alphanumeric
department_code No
characters Default department code of respective
system account user who is creating/
updating visitor

OR

Default department code defined in

Enterprise structure

When this code is specified, the system

should get the code's corresponding id
and apply this id to the user.

If Section id is also specified then the

system should give error “Section ID and
Code cannot be specified together”
max 6 alphanumeric
section_code No
characters Default section code of respective system
account user who is creating/updating
visitor

OR

Default section code defined in Enterprise

structure

516 Matrix COSEC Web API User Guide

Table 1: Set Visitor profile- Parameters

Argument Valid Values Mandatory Description

When this code is specified, the system

should get the code's corresponding id
and apply this id to the user.

If Category id is also specified then the

system should give error “Category ID and
Code cannot be specified together”
max 6 alphanumeric
category_code No
characters Default category code of respective
system account user who is creating/
updating visitor

OR

Default category code defined in

Enterprise structure

When this code is specified, the system

should get the code's corresponding id
and apply this id to the user.

If Grade id is also specified then the

system should give error “Grade ID and
Code cannot be specified together”
max 6 alphanumeric
grade_code No
characters Default grade code of respective system
account user who is creating/updating
visitor

OR

Default grade code defined in Enterprise

structure

When this code is specified, the system

should get the code's corresponding id
and apply this id to the user.

If Designation id is also specified then the

system should give error “Designation ID
and Code cannot be specified together”
max 6 alphanumeric
designation_code No
characters Default designation code of respective
system account user who is creating/
updating visitor

OR

Default designation code defined in

Enterprise structure

Matrix COSEC Web API User Guide 517

Table 1: Set Visitor profile- Parameters

Argument Valid Values Mandatory Description

When this code is specified, the system

should get the code's corresponding id
and apply this id to the user.

If Custom Group 1 id is also specified then

the system should give error “Custom
Group 1 ID and Code cannot be specified
together”
max 6 alphanumeric
customgroup1_code No
characters
Default customgroup1 code of respective
system account user who is creating/
updating worker

OR

Default customgroup1 code defined in

Enterprise structure

When this code is specified, the system

should get the code's corresponding id
and apply this id to the user.

If Custom Group 2 id is also specified then

the system should give error “Custom
Group 2 ID and Code cannot be specified
together”
max 6 alphanumeric
customgroup2_code No
characters
Default customgroup2 code of respective
system account user who is creating/
updating worker

OR

Default customgroup2 code defined in

Enterprise structure

When this code is specified, the system

should get the code's corresponding id
and apply this id to the user.

If Custom Group 3 id is also specified then

the system should give error “Custom
Group 3 ID and Code cannot be specified
together”
max 6 alphanumeric
customgroup3_code No
characters
Default customgroup3 code of respective
system account user who is creating/
updating worker

OR

Default customgroup3 code defined in

Enterprise structure

0= None This is a field that allows to configure the

enable-offline-transaction 1= Allow With Discount No transaction type to be allowed when
2= Allow Without Discount device is offline.

Return created Visitor Profile id in response on successful API execution.

518 Matrix COSEC Web API User Guide

Deleting Visitor Profile

This API will be used to delete visitors’ profile.

Action

action= delete

Table 2: Deleting Visitor Profile

Arguments Valid Values Mandatory Description

id Max 15 alphanumeric Yes This is the Visitor Profile ID.

characters
While deleting the profile rights
checking would be done, i.e.
whether the logged in user has
the rights for that particular
profile or not.

Return success message in response on successful API execution (only when API has been executed
successfully)

Matrix COSEC Web API User Guide 519

Getting Invite Visitor Application Details

This API is used to fetch the applied invited visitor application details.

Action

action= get

Syntax

http://<servername>/api.svc/v2/Invite-Visitor?action=<get>;<argument>=<value>...

License

COSEC Centra:
· System Account User: Basic (PLT) License + VMS

· ESS User: BASIC + ESS + VM

User Rights

User Rights

System Account Enabled if User has rights on any one of the following Pages.
VMS >Invite Visitor

ESS User Enabled if User has rights on any one of the following Pages.
ESS >Visitor Management > Invite Visitor

Parameters

Table: Getting Invite Visitor Details - Parameters

Argument Valid Values Mandatory Default Value Description

invite-id 10 digit No -
-
(0-9)

user-filter 0 : individual No user-filter=0

1: group Applicable for login ESS and RIC user.

user-filter=1
Applicable for login RIC and SA user.

date-range ddmmyyyy- No -
ddmmyyyy
Valid Values:
dd (Date): 01-31
mm (Month): 01-
12
yyyy (Year):
1900-2099

520 Matrix COSEC Web API User Guide

Table: Getting Invite Visitor Details - Parameters

Argument Valid Values Mandatory Default Value Description

application-status 0:all No
1: pending
2: approved
3: rejected
4: accessed
5: link expired

field-name The list of valid

fields is
mentioned in the
response section.

Response Fields

Table: Getting Invite Visitor details - Response Fields

Field Name Tag Name Valid Values Remarks

Invite ID invite-id 10 digit Allowed characters

0 to 9

Name visitor-name 40 characters Allowed characters

A-Z
a-z
0-9
-_. ()[]

Mobile Number visitor-mobile-no 20 characters Allowed characters

0 to 9
-+()

Email ID visitor-email-id 125 characters

Organization Name Organization-name 45 Characters Allowed characters

A –Z,
a-z,
0 – 9,
_- ()[].,/
+!@$:#&*)

A to Z
a to z
Host User ID host-id 15 characters
0 to 9
/_\\.@:

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

Visit Date visit-date ddmmyyyy

Visit Until Date visit-until-date ddmmyyyy

Visit Start Time visit-start-time hhmm Range:

00:00 – 23:59

Visit End Time visit-end-time hhmm Range:

00:00 – 23:59

Matrix COSEC Web API User Guide 521

Table: Getting Invite Visitor details - Response Fields

Field Name Tag Name Valid Values Remarks

Purpose purpose 50 characters

Additional Visitors additional-visitors 0-99

0 =None
repeat-mode 1=Daily Default is 0-None
2=Weekly

1=Mon Return repeat days in

Repeat visit 2=Tue comma-separated format.
3=Wed i.e. repeat-days=1,3,5
repeat-days 4=Thu
5=Fri
6=Sat
7=sun

Application Status application-status 1=applied

2=Approved
3=Rejected
4=Accessed
5=Not Accessed

Request Date request-date mm/dd/yyyy

Max 15 chars
Allowed Characters
A-Z
Final RIC ID final-ric
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
a-z
Final RIC Name final-ric-name 0-9
-_. ()[]

MM/DD/YYYY
Final RIC Verdict Date Time final-ric-verdict-date
HH:MM

1: Applied
Final RIC Verdict final-ric-verdict 2: Approved
3: Rejected

Max 30 chars
Allowed Characters
A-Z
Final RIC Remark nonfinal-ric-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars
Allowed Characters
A-Z
Non-Final RIC ID nonfinal-ric
a-z
0-9
@_ / : .

522 Matrix COSEC Web API User Guide

Table: Getting Invite Visitor details - Response Fields

Field Name Tag Name Valid Values Remarks

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC Name nonfinal-ric-name
a-z
0-9
-_. ()[]

Non-Final RIC Verdict Date MM/DD/YYYY

nonfinal-ric-verdict-date
Time HH:MM

1: Applied
Non-Final RIC Verdict nonfinal-ric-verdict 2: Approved
3: Rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC Remark nonfinal-ric-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars
Allowed Characters
A-Z
Non-Final RIC2 ID nonfinal-ric2
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC2 Name nonfinal-ric2-name
a-z
0-9
-_. ()[]

Non-Final RIC2 Verdict Date MM/DD/YYYY

nonfinal-ric2-verdict-date
Time HH:MM

1: Applied
Non-Final RIC2 Verdict nonfinal-ric2-verdict 2: Approved
3: Rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC2 Remark nonfinal-ric2-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars
Allowed Characters
A-Z
Non-Final RIC3 ID nonfinal-ric3
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC3 Name nonfinal-ric3-name
a-z
0-9
-_. ()[]

Matrix COSEC Web API User Guide 523

Table: Getting Invite Visitor details - Response Fields

Field Name Tag Name Valid Values Remarks

Non-Final RIC3 Verdict Date MM/DD/YYYY

nonfinal-ric3-verdict-date
Time HH:MM

1: Applied
Non-Final RIC3 Verdict nonfinal-ric3-verdict 2: Approved
3: Rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC3 Remark nonfinal-ric3-remark
a-z
0-9
_.,()[]:@!#$*+/\

Max 15 chars
Allowed Characters
A-Z
Non-Final RIC4 ID nonfinal-ric4
a-z
0-9
@_ / : .

Max 45 chars
Allowed Characters
A-Z
Non-Final RIC4 Name nonfinal-ric4-name
a-z
0-9
-_. ()[]

Non-Final RIC4 Verdict Date MM/DD/YYYY

nonfinal-ric4-verdict-date
Time HH:MM

1: Applied
Non-Final RIC4 Verdict nonfinal-ric4-verdict 2: Approved
3: Rejected

Max 30 chars
Allowed Characters
A-Z
Non-Final RIC4 Remark nonfinal-ric4-remark
a-z
0-9
_.,()[]:@!#$*+/\

524 Matrix COSEC Web API User Guide

Sending the Invite Visitor Link

This API is used for host to generate an alert on the server to send the invite along with the configuration file to the
visitor.

Action

action= set

Syntax

http://<servername>/api.svc/v2/Invite-Visitor?action=<set>;<argument>=<value>...

License

COSEC Centra:
· System Account User: Basic (PLT) License + VMS

· ESS User: BASIC + ESS + VMS

User Rights

User Rights

System Account Enabled if User has rights on any one of the following Pages.
VMS >Invite Visitor

ESS User Enabled if User has rights on any one of the following Pages.
ESS >Visitor Management > Invite Visitor

Parameters

Table: Set Invite Visitor- Parameters

Default Multilanguage
Argument Valid Values Mandatory Description
Value Support

visitor name 200 characters No - Yes

Valid Charac-
ters:
A-Z
a-z
0-9
-_. ()[]

Matrix COSEC Web API User Guide 525

Table: Set Invite Visitor- Parameters

Default Multilanguage
Argument Valid Values Mandatory Description
Value Support

Visitor-email- 125 Optional -

id
Valid characters • Mandatory if Mobile number is
not provided.
Use same
• The visitor should be sent the
characters type
configuration file attached in an
as for visitor
email on this mail ID.
pre-registration
API

Visitor Mobile 20 characters - - NA

no.
0-9 Mandatory if email-id is not provided.

- + ()

visit-date ddmmyyyy No - N
The date for which application is being
Range: submitted.
Current Date to
31/12/2037

visit-until-date ddmmyyyy No - N
Range:
Current Date to
31/12/2037

repeat-mode 0 = Do Not No - N
Repeat
1 = Daily
2 = Weekly

repeat-days 1: Sunday No - N Mandatory and Applicable only when

2: Monday repeat-mode = 2
3: Tuesday
4: Wednesday Multiple days are allowed with comma-
5: Thursday separated format.
6: Friday i.e. repeat-days=1,3,5
7: Saturday

visit-start-time hhmm No - N

Range:
00:00 – 23:59

visit-end-time hhmm No - N

Range:
00:00 – 23:59

additional 0-99 No - N
visitors

host id 15 characters - N For ESS users: (Mandatory field)

Allowed ‘host-id’ should be login ESS user’s ID
characters If not supplied, logged In user id should
A-Z be set.
a-z
0-9 For SA users: (Mandatory field)
/_\\.@: ‘host-id’ should be authorized host user.

purpose 50 characters
(same as used
fro visitor pre- - Y If not supplied, then it should be ‘NULL’.
registration API
)

526 Matrix COSEC Web API User Guide

In the response of successful API execution return the Invite link to the user as generated on the server.

Example:

success: 1090200002: saved successfully ,Invite Link :<URL>/cosecvisitor/visitorinvite/<RequestID>

<RequestID> = ID of the requested application. (Mx_VMSVSTRInvite.ID)
<URL> = Tenant URL to access visitor portal for the respective tenant.
For Cloud with Enable SSL OFF:
<URL> = Tenant URL to access visitor portal for the respective tenant.
For Premise with Enable SSL On:
<URL> = External URL to access visitor portal. [i.e. COSEC Visitor URL (External)]
For Premise with Enable SSL Off:
<URL> = External URL to access visitor portal. [i.e. COSEC Visitor URL (External)]

Matrix COSEC Web API User Guide 527

Visitor Invites Approval

This API is used for host to approve / reject/transfer visit initiated or rescheduled by Visitor and for Visitor to
approve/reject Visit Initiated or rescheduled by Host.

Action

action= set

Syntax

http://<servername>/api.svc/v2/visitor-invites-approval?action=<set>;<argument>=<value>...

License

COSEC Centra:
· System Account User: Basic + VMS

· ESS User: BASIC + ESS + VMS

· Visitor User: Basic + VMS

User Rights

User Rights

System Account User Enabled if System account user has view and edit rights on
Visitor Management > Visit Approval

Host User Enabled if User has rights on the following Pages.

ESS > Visitor Management > visit Approval

Visitor Enabled if Visitor is registered and verified by using assigned token

Parameters

Table: Set Visitor Invites Approval- Parameters

Default Multilanguage
Argument Valid Values Mandatory Description
Value Support

user-type 0 = Host User No 0 N

1 = Visitor

appointment- Max 12 Digits Yes - N The user can select multiple appointment-
no no, each separated by ", (comma)"
0-9 e.g.:"171212000001, 171212000003,
171213000007…". For "Approve All" /
"Reject All"/"Transfer All" to Approve/
Reject/transfer multiple visitors invite
applications.

528 Matrix COSEC Web API User Guide

Table: Set Visitor Invites Approval- Parameters

Default Multilanguage
Argument Valid Values Mandatory Description
Value Support

verdict 1 : Approve Yes - N

2 : Reject
3 : Transfer Approving/Rejecting/Transferring multiple
4: Reschedule appointment is also allowed.

visit-location 0 : Select No 0 N
Applicable only when user-type = 0 and
1: Configured
verdict =1
2: custom

location-code Max 6 chars No - N

Mandatory and applicable only when
0-9 user-type = 0, verdict =1 and visit-
a-z location=1.
A-Z

latitude Max 8 chars No - N

Mandatory and applicable only when
-90.0000 to
user-type = 0, verdict =1 and visit-
+90.0000
location=2.
Format:
XX.XXXX

longitude Max 9 chars No - N

Mandatory and applicable only when
-180.0000 to user-type = 0, verdict =1 and visit-
+180.0000 location=2.
Format:
XXX.XXXX

additional- Allowed No - N Applicable only when user-type = 0,

host characters verdict =1.
A-Z
a-z Multiple hosts User's ID(s) with comma-
0-9 separated format.
/_\\.@: i.e. additional-host=1542,1421,1320,1528

Range:
Maximum 99
Host Users

cancellation- Max 50 chars. No - Y (Set 1) Applicable only when user-type = 0,

reason Allowed verdict =2.
Characters
A-Z
a-z
0-9
_.,()[]:@!$*+\

<space>

transfer-host- Max 15 Yes - N Mandatory field when user-type = 0 and

id Alphanumeric verdict =3
Characters (for
user) NOTE: while transferring visit, check if
A to Z transfer to host id is available in additional
a to z host, then remove that host from
0 to 9 Additional hosts list and then allow
/_\\.@: successful transfer

Matrix COSEC Web API User Guide 529

Table: Set Visitor Invites Approval- Parameters

Default Multilanguage
Argument Valid Values Mandatory Description
Value Support

visit-date ddmmyyyy Yes - N Optional Mandatory field when verdict =4

is supplied (i.e. from visit date, visit-until-
Range: date, visit time, repeat-mode, repeat-
Current Date to days, repeat-dates anyone must be
31/12/2037 mentioned).

visit-until-date ddmmyyyy Yes - N Optional Mandatory field when verdict =4

Range: is supplied (i.e. from visit date, visit-until-
Current Date to date, visit time, repeat-mode, repeat-
31/12/2037 days, repeat-dates anyone must be
mentioned).

visit-start-time hhmm Yes - N Optional Mandatory field when verdict =4

Range: is supplied (i.e. from visit date, visit-until-
00:00 - 23:59 date, visit time, repeat-mode, repeat-
days, repeat-dates anyone must be
mentioned). Visit Start Time should be
less than Visit End Time.

visit-end-time hhmm Yes - N Optional Mandatory field when verdict =4

Range: is supplied (i.e. from visit date, visit-until-
00:00 - 23:59 date, visit time, repeat-mode, repeat-
days, repeat-dates anyone must be
mentioned). Visit End Time should be
later than Visit Start Time.

repeat-mode 0 = Do Not Yes - N Optional Mandatory field when verdict =4

Repeat is supplied (i.e. from visit date, visit-until-
1 = Daily date, visit time, repeat-mode, repeat-
2 = Weekly days, repeat-dates anyone must be
mentioned).

repeat-days 1: Sunday Yes - N Optional Mandatory field when verdict =4

2: Monday is supplied (i.e. from visit date, visit-until-
3: Tuesday date, visit time, repeat-mode, repeat-
4: Wednesday days, repeat-dates anyone must be
5: Thursday mentioned).
6: Friday
7: Saturday Mandatory only when repeat-mode = 2
Multiple days are allowed with comma-
separated format. i.e. repeat-
days=1,7,2,3

In this API, as we can add maximum upto 99 additional host users, there is a possibility that it will lead to
exceed maximum URL limit. So in such case server will throw an exception.

530 Matrix COSEC Web API User Guide

Set Security Approval

This API is used by the security (system account user) to give verdict on application which is in approved state for
allowing visitor to generate E-Pass.

Action

action= set

Syntax

http://<servername>/api.svc/v2/security-approval?action=<set>;<argument>=<value>...

License

VMS (Visitor Management System) License is required for this API.

User Rights

User Rights

System Account Enabled if User has rights on the following Page.

Visitor Management > Authorization/Approval> Security Approval

Parameters

Table: Set Security Approval- Parameters

Argument Valid Values Mandatory Default Value Multi-Language Description

appointment-no Max 12 Digits Yes 0 N You can select multiple

appointment-no, each
0-9 separated by ", (comma)"
e.g.:"171212000001,
171212000003,
171213000007…". For
"Approve All" / "Reject All"
to Approve/Reject multiple
visitors invite applications.

verdict 1 : Approve Yes 0 N Approving/Rejecting

2 : Reject multiple appointment is
also allowed

remark Max 30 chars No Default Remark Y (Set 2) -

as per verdict
Allowed
Characters
A-Z
a-z
0-9
_.,()[]:@!#$*+/\

Matrix COSEC Web API User Guide 531

Set Visit State

This API is used to update state of any visit. This API is applicable for both Host & visitor, any of them can update
possible Visit State.

Action

action= set

Syntax

http://<servername>/api.svc/v2/visit-state?action=<set>;<argument>=<value>...

License

VMS (Visitor Management System) License is required for this API.

User Rights

User Rights

Host User Enabled if User is Authorized Host User

Visitor Enabled if Visitor is registered and verified by using assigned token

System Account User (security) Enabled if User has VMS Utility rights

Parameters

Table: Set Visit State- Parameters

Default Multi Language

Argument Valid Values Mandatory Description
Value Support

user-type 0 = Host User / No 0 N

SA User To specify the type of user.
1 = Visitor

appointment Max 12 Digits Yes - N "You can select multiple appointment-no,

-no each separated by ", (comma)"
0-9 e.g.:"171212000001, 171212000003,
171213000007…". For "Approve All" /
"Reject All" to Approve/Reject multiple
visitors invite applications.

Note: If host/visitor user tries to change

state for an application which is not
requested to him then there will be error
in processing request.

profile-id Max 15 chars No 0 N

Applicable only when logged in as system
account user & state-change = Check-In.
Valid Values:
A-Z
Profile Id will be assigned based on visitor
a-z
profile rights to system account user on
0-9
create pass.
@_:./

532 Matrix COSEC Web API User Guide

Table: Set Visit State- Parameters

Default Multi Language

Argument Valid Values Mandatory Description
Value Support

station-id Max 2 chars No - N

Applicable only when logged in as system
account user & state-change = Check-In
1-99

state- 0:Check-IN Yes - N Note:

change 1:Start 1.If entered value is of value other than
2:On Hold possible Next Visit State then Invalid
3:Resume Command will occur.
4:Stop Example: If visit current state= Check-IN,
5:Check-OUT & in API value=3 (means Resume) is
entered then it is invalid value
Here,
For visitor & 2. If Host tries to Check-In or Check-Out
Security valid then it will not be allowed.
values = 0 & 5
3. If Security/visitor tries to Start/Pause/
'For Host valid Resume/Stop then it will not be allowed.
values = 1,2,3,4
4. The user cannot Check-In before
[Time] mins from the Visit Start Time.

5. If visitor/security applies check-In (that

is state-change=0) and no visitor profile is
available then error -Maximum concurrent
visit limit reached will occur.

Response:

When state-change = 0 and single appointment-no is passed, return visitor-profile-id and visitor-profile-name in
response on successful API execution.

Example: success: 1180100001: saved successfully. Visitor Profile ID = < visitor-profile-id>, Visitor Profile Name =
< visitor-profile-name>

Matrix COSEC Web API User Guide 533

System Account User

This API is used to get the System Account user information of logged in user.

Action

action= get

Syntax

http://<servername>/api.svc/v2/system-account-user?action=<get>;<argument>=<value>...

License

Basic License is required for this API.

Response Fields

Table: System Account User - Response Fields

Field Name Tag Name Valid Values Remarks

System Account User ID system-account-user-id 15 Characters -

System Account User Name system-account-user-name 45 characters -

Linked-ESS-User ID linked-ess-user-id 15 characters -

Linked ESS User Name linked-ess-user-name 45 Characters -

If logged in system
account user has VMS
0 = Disabled
VMS Utility Rights vms-utility-rights Utility rights, then this
1 = Enabled
should return as 1,
otherwise 0.

Fetch the value from field

Email configured for
Email email 125 characters System Account User
(i.e. stored in
LoginUserMst)

Format: VXXRXX.XX
Maximum 10 alphanumeric
COSEC Version cosec-version Example: V06R01 ,
characters
V06R02 , V05R08.20

534 Matrix COSEC Web API User Guide

OTP Verification

This API is used to verify the visitor for visitor registration and also to verify ESS user when he is trying to change/
set his account password.

Action

action= command

Syntax

http://<servername>/api.svc/v2/otp-verification?action=<command>;<argument>=<value>...

License

COSEC Centra:
• System Account User: Basic (PLT) License + VMS
• ESS User: BASIC + ESS + VMS
• Visitor User: Basic + VMS
• Apply license based on user-type defined below. If User-type=0, VMS license is not mandatory. If User-
type=1, VMS license is mandatory

User Rights

This API will work without any authentication.

Parameters

Table: OTP Verification- Parameters

Argument Valid Values Mandatory Default Value Description

type 0 = Verify No 0
1 = Resend
2= Validate
To verify the OTP or Resend the OTP
3= Resend for
validation

User-type 0= ESS User No 1 When 0=ESS User

1= Visitor Consider for password set verification

When 1-visitor
Consider for contact details verification

mobile-otp 6 Digits Yes when -

type=0 Mandatory Field only when type = 0
Valid Values: 0 - 9 (=Verify) is supplied & OTP is generated
for Mobile Number Verification.

Note- System should check and compare

the values for Maximum Inavlid Attempts,
Auto Unlock Timer (Min) as with the
values configured in the server.

email-otp 6 Digits Yes when - Mandatory Field only when type = 0

type=0 (=Verify) is supplied & OTP is generated
Valid Values: 0 - 9 for Email ID Verification

Matrix COSEC Web API User Guide 535

Table: OTP Verification- Parameters

Argument Valid Values Mandatory Default Value Description

visitor-id 0-9 Yes - Mandatory field only when type = 1.It is

the visitor’s ID.

User-id 15 characters Yes - Mandatory field only when type = 0. For

an ESS user, this will be the Login user’s
ID.

If the ID is invalid or does not match the

login user’s ID, return message for Invalid
Argument Value

For Type: 0 (=Verify)

On successful OTP verification, set Mx_VMSVSTRMST >IsVerified flag as 1 and return message, success:
1000500002 : Visitor Verified successfully.

Login Token =<GUID> ,

Tenant Identifier = NmI1NDVlZDEtYjMzOC00ZWFkLTk5OTgtMDcwZTI0NGFhMzJm

For Type: 1 (=Resend for Validation)

On successful API request, send OTP generated alert & return message: “success: 1000500001 : OTP Sent
Successfully.”

When the OTP verification for user-type=0 is successful update the value of the parameter “user verified for
password” from 1 to 0 again.

Example1
Following are some sample cases for this API:

Sample Request:

To verify the registered visitor using mobile OTP:

http://192.168.104.12/cosec/api.svc/v2/otp-verification?action=command;type=0;mobile-otp=434655;visitor-id=2;

Sample Response:

success: 1000500002 : Visitor Verified successfully. Login Token = d4975589-5733-471e-976a-138cefb87673

The generated token must be saved as it will be used as Password for Pre-registration of the visitor.

536 Matrix COSEC Web API User Guide

Tenant Identifier API

This API is used to fetch the visitor tenant identifier from Global Policy of COSEC Server.

Action

action= get

Syntax

http://<servername>/api.svc/v2/tenant-identifier?action=<get>;<argument>=<value>...

License

COSEC Centra:
• System Account User: Basic (PLT) License + VMS
• ESS User: BASIC + ESS + VMS
• Visitor User: Basic + VMS

User Rights

User Rights

System Account Enabled

ESS User Enabled

Visitor Enabled for All Registered Visitors with 'isVerified' flag = 1

Parameters

Table: Tenant Identifier API- Parameters

Argument Valid Values Mandatory Default Value Description

user-type 0 = Host User / No 0

SA User -
1 = Visitor

Response Fields

Table: Tenant Identifier API - Response Fields

Field Name Tag Name Valid Values Remarks

Fetches tenant identifier

Visitor Tenant Identifier tenant-identifier -
from COSEC DB

Matrix COSEC Web API User Guide 537

538 Matrix COSEC Web API User Guide
CHAPTER 26 Contract Worker
Management

The following API enable the user to perform actions related to Contract Worker Management. This is used to get
list of Contractor, Work Order etc as per the requirement.

Contractor APIs

• Getting Contractor Types

• Set Contractor Types
• Delete Contractor Types

Work Order APIs

• Getting Work -Order Details

• Delete Work-Order

Worker APIs

• Getting Worker Details

• Setting Worker Details
• Deleting Worker Details

Matrix COSEC Web API User Guide 539

Getting Contractor Types

This API will be used to get existing contractor details.

Action

action=get

Syntax

http://<servername>/api.svc/v2/contractor?action=<get>

License

System Account User: Basic + T&A + CWM

User Rights

User Rights

System Account Enabled if User has rights on Page.

CWM > Contractor > Contractor Profile

Parameters

Table: Getting Contractor type- Parameters

Argument Valid Values Mandatory Description

id 15 chars No This is the Contractor ID

Allowed Characters:
A-Z
a-z
0-9
/_.@:

Response Fields

Table: Getting Contractor type - Response Fields

Field Name Tag Name Valid Values Remarks

Allowed Characters
A-Z
ID id Max 15 alphanumeric characters a-z
0-9
/_.@:

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

540 Matrix COSEC Web API User Guide

Table: Getting Contractor type - Response Fields

Field Name Tag Name Valid Values Remarks

Contractor Type con-type 1-999

Validity End Date validity-end-date Dd/mm/yyyy format

A-Z
a-z
Address-1 address-1 30 chars 0-9
!*@$()_-+[]:,./
<Space>

A-Z
a-z
Address-2 address-2 30 chars 0-9
!*@$()_-+[]:,./
<Space>

A-Z
a-z
Street street 30 chars 0-9
!*@$()_-+[]:,./
<Space>

A-Z
a-z
City city 30 chars 0-9
!*@$()_-+[]:,./
<Space>

Pincode pincode Max 10 numeric characters

A-Z
a-z
State state 40 chars 0-9
!*@$()_-+[]:,./
<Space>

A-Z
a-z
Country country 20 chars 0-9
!*@$()_-+[]:,./
<Space>

0-9
Phone phone 30 chars +()-

Allowed Characters
A-Z
a-z
Contact Person 1 contact-person1 max 45 alphanumeric characters 0-9
<space>
-_. ()[]

0-9
Mobile mobile-1 32 characters +()-

Matrix COSEC Web API User Guide 541

Table: Getting Contractor type - Response Fields

Field Name Tag Name Valid Values Remarks

Email email-1 max 100 alphanumeric characters

Allowed Characters
A-Z
a-z
Contact Person 2 contact-person2 max 45 alphanumeric characters
0-9
<space>
-_. ()[]

0-9
Mobile mobile-2 32 characters +()-

Email email-2 max 100 alphanumeric characters

A-Z
a-z
PF No. pf-no Max 30 Alphanumeric Characters 0-9
!*@$()_-+[]:,./
<Space>

A-Z
a-z
PAN No. pan Max 30 Alphanumeric Characters 0-9
!*@$()_-+[]:,./
<Space>

A-Z
a-z
Service Tax No. service-tax-no Max 30 Alphanumeric Characters 0-9
!*@$()_-+[]:,./
<Space>

A-Z
a-z
ESIC No. esic-no Max 31 Alphanumeric Characters 0-9
!*@$()_-+[]:,./
<Space>

A-Z
a-z
License No. license-no Max 30 Alphanumeric Characters 0-9
!*@$()_-+[]:,./
<Space>

Enable Account enable-acc 0 or 1

Edit Basic Details

edit-basic-details 0 or 1

Preferred Language Pref-lang Language assigned to contractor

0 : Not Blacklisted
Blacklisted Blacklisted
1 : Blacklisted

542 Matrix COSEC Web API User Guide

Table: Getting Contractor type - Response Fields

Field Name Tag Name Valid Values Remarks

Max 50 chars
Valid Values :
A-Z
Blacklisted reason Blacklisted-reason a-z
0-9
[space]
!@$*()_-+\[],.:

Matrix COSEC Web API User Guide 543

Set Contractor Types

Action

action= set

Syntax

http://<servername>/api.svc/v2/contractor?action=<set>

License

System Account User: Basic + T&A + CWM

User Rights

User Rights

System Account Enabled if User has rights on Page.

CWM > Contractor > Contractor Profile

Parameters

Default Multi language

Argument Valid Values Mandatory Description
Value Support

id 15 chars NA N This is the Contractor Id.

Allowed
Characters:
A-Z
a-z
0-9
/_.@:

Prefix Max 15 chars No NA N If Id is mentioned, ignore this

parameter
Allowed
Characters
A-Z
a-z
0-9
/_.@:

Auto- 1 to 15 No NA N Mandatory if ID is not mentioned.

generation-
serial-length

0: unchecked No 1 N If Id is mentioned, ignore this

Zero-padding 1: checked parameter

Max 45 Yes Y(Set1) This is the Contractor Name.

name
Characters

Max 3 chars No Default N NOTE: If contractor-type is not passed

contractor- Contracto or values for contractor type are not
type 1-999 r type mentioned, default contractor-type
should be assigned.

544 Matrix COSEC Web API User Guide

 Default Multi language
Argument Valid Values Mandatory Description
Value Support

validity-end- ddmmyyyy Yes NA N This is the validity end date of

date format contractor.

30 chars No NA Y(Set1) The First Address of the Contractor.

A-Z
Address-1
a-z
0-9
!*@$()_-+[]:,./
<Space>

Address-2 30 chars No NA Y(Set1) The Second Address of the Contractor.

A-Z

a-z
0-9
!*@$()_-+[]:,./
<Space>

street 30 chars No NA Y(Set1) Enter the Name of Street

A-Z
a-z
0-9
!*@$()_-+[]:,./
<Space>

city 30 chars No NA Y(Set1)

A-Z
a-z Enter the Name of City
0-9
!*@$()_-+[]:,./
<Space>

pincode max 10 numeric No - N

characters Enter the Pincode

state 40 chars No NA Y(Set1) Enter the Name of State

A-Z
a-z
0-9
!*@$()_-+[]:,./
<Space>

country 20 chars No NA Y(Set1)

A-Z
a-z
0-9
!*@$()_-+[]:,./
<Space>

phone max 30 numeric No NA N

characters
+()-

Matrix COSEC Web API User Guide 545

 Default Multi language
Argument Valid Values Mandatory Description
Value Support

contact- max 45 No NA Y (Set1)

person1 alphanumeric
characters
Allowed
Characters
A-Z
a-z
0-9
-_. ()[]

mobile-1 max 32 numeric No - N

characters The Mobile Number of the Contractor.
0-9
+()-,

email-1 max 100 Yes - -

alphanumeric The Email ID of the Contractor.
characters
@.-

contact- max 45 No - Y(Set1)

person2 alphanumeric
characters
Allowed
Characters
A-Z
a-z
0-9
-_. ()[]

mobile-2 max 32 No - N
numeric
characters The Mobile Number of the Contractor.
0-9
+()-

email-2 max 100 No - -

alphanumeric The Email ID of the Contractor.
characters
@.-

pf-no Max 30 No NA Y(Set1)

Alphanumeric
Characters

A-Z The PF Number of the Contractor.

a-z
0-9
!*@$()_-+[]:,./
<Space>

pan A-Z No - Y(Set1)

a-z
0-9 The PAN Number of the Contractor.
!*@$()_-+[]:,./
<Space>

546 Matrix COSEC Web API User Guide

 Default Multi language
Argument Valid Values Mandatory Description
Value Support

service-tax-no Max 30 No - Y(Set1)

Alphanumeric
Characters
The Service-Tax Number of the
A-Z Contractor.
a-z
0-9
!*@$()_-+[]:,./
<Space>

esic-no Max 31 No - Y(Set1)

Alphanumeric
Characters
The ESIC Number of the Contractor.
A-Z
a-z
0-9
!*@$()_-+[]:,./
<Space>

license-no Max 30 Yes - Y(Set1)

Alphanumeric
Characters
The Licence Number of the Contractor.
A-Z
a-z
0-9
!*@$()_-+[]:,./
<Space>

License- Max 250 No NA Y(Set1)

description Alphanumeric
Characters
A-Z
a-z
0-9
!*@$()_-+[]:,./
<Space>

Blacklisted 0 : Not Blacklisted No NA N

This is a field that shows whether
1 : Blacklisted
contractor is blacklisted or not

Blacklisted- Max 50 Chars No NA N

reason A-Z
a-z
This field specifies the reason for
0-9
blacklisting.
[space]
!@$*()_-+\[]
,.:

Matrix COSEC Web API User Guide 547

Delete Contractor Types

Action

action=delete

Syntax

http://<servername>/api.svc/v2/contractor?action=<get>

User Rights

User Rights

System Account Enabled if User has rights on Page.

CWM > Contractor > Contractor Profile

Parameters

Table: Deleting Visit Type- Parameters

Argument Valid Values Mandatory Default Value Description

15 chars

Allowed
Characters:
id A-Z Yes - -
a-z
0-9
/_.@:

548 Matrix COSEC Web API User Guide

Getting Work -Order Details

This API will be used to get Work-Order details.

Action

action= get

Syntax

http://<servername>/cosec/api.svc/v2/work-order?action=<get>

License

System Account User: Basic + T&A + CWM

User Rights

User Rights

System Account Enabled if User has rights on Page.

CWM > Work Order > Work Orders

Parameters

Table: Getting Work Order Details- Parameters

Argument Valid Values Mandatory Description

id Max 15 alphanumeric No This is Work Order ID

characters

Allowed Characters
A-Z
a-z
0-9
/_.@:

Response Fields

Table: Getting Work Order Details - Response Fields

Field Name Tag Name Valid Values Remarks

Allowed Characters
A-Z
a-z
Work Order id id Max 15 alphanumeric characters
0-9
/_.@:

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

Matrix COSEC Web API User Guide 549

Table: Getting Work Order Details - Response Fields

Field Name Tag Name Valid Values Remarks

Max 3 numeric characters

Type work-order-type -
1-999

Validity Start validity-start dd/mm/yyyy -

Validity End validity-end dd/mm/yyyy -

Total Assigned Worker total-worker-assigned -

Description description Max 250 aphanumeric chars

max 15 alphanumric characters

Allowed characters
Returns the ID of
Associated Contractor associated-contractor-id A-Z
contractor
a-z
0-9
/_.@:

Max 15 alphanumeric characters

A-Z
Returns the ID of Site In-
Site In-Charge site-incharge-id a-z
Charge
0-9
/_.@:

Max 3 numeric characters Returns the ID of Approval

Approval Stage approval-stage-id
1-999 Stage

Max 5 numeric characters

Max Worker Limit max-worker-limit
0-99999

Max 6 numeric characters

Organization organization
1-999999

Max 6 numeric characters

Branch branch -
1-999999

Max 6 numeric characters

Department department -
1-999999

If more than one group is

assigned, then it should
fetch multiple group ID
separated with comma.

Device Group id Device-group-id Max 600 NUMcharacters When 99 device

(maximum device allowed)
with individual ID of 5
NUMcharacter is GET then
600 NUMcharacter are
allowed.

Check Limit While Assigning Max 1 numeric value -

worker-check-limit 1/0
Worker

550 Matrix COSEC Web API User Guide

Setting Work-Order

This API will be used to set Work-Order details.

Action

action= set

Syntax

http://<servername>/api.svc/v2/work-order?action=<set>

License

System Account User: Basic + T&A + CWM

Parameters

Table: Setting Work Order- Parameters

Argument Valid Values Mandatory Default Value Description

Max 15
alphanumeric
This is the Work-order Id.
characters

Allowed Either ID OR (Prefix and Auto-

id Characters: Yes - generation-serial-length) OR only
A-Z
“Auto-generation-serial-length”
a-z
0-9 is a mandatory field to be
/_.@: mentioned in API

Max 15 chars -

Allowed
prefix Characters No
A-Z
a-z
0-9
@_ / :

Mandatory if ID is not mentioned.

Auto-generation-
1-15 No
serial-length
If ID is mentioned, then ignore
this parameter.

Zero-padding 0: unchecked No 1
1: checked

Matrix COSEC Web API User Guide 551

Table: Setting Work Order- Parameters

Argument Valid Values Mandatory Default Value Description

Max 45 Work order name.

Characters

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

Max 3 chars -
work-order-type No -
1-999

ddmmyyyy -

validity-start valid range : Yes -

Current date to
31/12/2099

ddmmyyyy -

validity-end valid range : Yes -

Current date to
31/12/2099

Max 15 chars -

Allowed values:
associated-
A-Z Yes -
contractor-id
a-z
0-9
@_:./

Max 15 chars This field specifies user id which is to be

used as an in charge of site
Allowed
site-incharge-id Characters No -
A-Z
a-z
0-9
@_ / : .

Max 3 chars This field defines stages in which the

approval-stage-id Yes - Induction Approval required
1-999

Max 5 chars This field defines stages in which the

max-worker-limit Yes - Induction Approval required.
Valid range
0-99999

Max 6 characters -
organization No -
1-999999

Max 6 characters -
branch No -
1-999999

552 Matrix COSEC Web API User Guide

Table: Setting Work Order- Parameters

Argument Valid Values Mandatory Default Value Description

Max 6 characters -
department No -
1-999999

A-Z -
a-z
Description 0-9 No -
@!$*()_-+[]:
, . / [space]

This parameter will strictly map worker’s

1=checked
worker-check-limit No 1 limit while assigning new worker to work
0-unchecked
order.

Matrix COSEC Web API User Guide 553

Delete Work-Order

This API will be used to delete Work-Order details.

Action

action= delete

Syntax

http://<servername>/api.svc/v2/work-order?action=<delete>

License

System Account User: Basic + T&A + CWM

User Rights

User Rights

System Account Enabled if User has rights on Page.

CWM > Work Order > Work Orders

Parameters

Table: Deleting Work Order- Parameters

Argument Valid Values Mandatory Default Value Description

Max 15
alphanumeric
characters

Allowed
id Characters: Yes - -
A-Z
a-z
0-9
/_.@:

554 Matrix COSEC Web API User Guide

Getting Worker Details

This API will be used to get existing Worker details.

Action

action=get

Syntax

http://<servername>/api.svc/v2/worker?action=<get>

License

System Account User: Basic + T&A + CWM

User Rights

User Rights

System Account Enabled if User has rights on Page.

CWM > Workers > WorkerProfile

Parameters

Table: Getting Worker details- Parameters

Argument Valid Values Mandatory Description

Range All, organization, No Specifies range of workers

branch ,department,
designation, section,
category, grade,
custom-group-1,
custom-group-2,
custom-group-3

id 15 chars No This is worker id

Allowed Characters
A-Z
a-z
0-9
/_.@:

Field-name field-1 No These are the fields that can be specified to fetch
field-2 worker's specific data.
field-3
field-4

Matrix COSEC Web API User Guide 555

Table: Getting Worker details- Parameters

Argument Valid Values Mandatory Description

Non mandatory field.

Default value = 0.

Conditions:
1.Argument mentioned, but value not specified,
then ignore this parameter.

2.If filter=0 is specified, return all workers

configured in the system.

3.If filter=1 is specified, return only active workers

0 : All configured in the system.
1 : Active Workers
filter 2 : Inactive Workers No 4.If filter=2 is specified, return only inactive
workers configured in the system.
Default: 0

Note:

If filter=1 is specified and multiple-ids are passed

or any enterprise group is passed, out of which
some of them are inactive, then do not return those
workers and vice-versa should also be applicable.

If filter=2 is specified and multiple-ids are passed

or any enterprise group is passed, out of which
some of them are active, then do not return those
workers and vice-versa should also be applicable.

Response Fields

Table: Getting Worker details - Response Fields

Field Name Tag Name Valid Values Remarks

Allowed Characters
A-Z
Id id Max 15 alphanumeric characters a-z
0-9
/_.@:

0: Inactive
1 : Active
Active active 0 or 1 or 2
2 : Inactive and Revoke
Devices

556 Matrix COSEC Web API User Guide

Table: Getting Worker details - Response Fields

Field Name Tag Name Valid Values Remarks

Allowed Characters

A -Z
a-z
0-9
()
[]
_ (underscore)
Full-name full-name max200 alphanumeric characters - (Hyphen)
. (full Stop)
/

, (comma)
@
' (single quote)
[Space]

Short name short name Max 15 Alphanumeric Characters

Reference Code reference-code 1 to 99999999

Integration Reference integration-reference max 20 alphanumeric characters

Date of Birth date-of-birth ddmmyyyy format

Birthday message birthday-message-flg 0 or 1

Joining Date joining date ddmmyyyy formate

Confirmation date confirmation-date ddmmyyyy format

ddmmyyyy format
Leaving Date Leaving-date

Allowed characters
A-Z
a-z
Reason for Leaving Max 15 Alphanumeric Characters
Reason-for-leaving 0-9
!*@$()_-+[]:,./
<Space>

Vehicle Registration No Characters and comma(,)

vehicle-reg-no Max 50 Alphanumeric Characters

A-Z
a-z
0-9
Driving License Max 30 Alphanumeric Characters
driving-license !*@$()_-+[]:,./
<Space>

Matrix COSEC Web API User Guide 557

Table: Getting Worker details - Response Fields

Field Name Tag Name Valid Values Remarks

A-Z
a-z
Passport No. Max 30 Alphanumeric Characters
passport-no 0-9
!*@$()_-+[]:,./
<Space>

A-Z
a-z
Max 30 Alphanumeric Characters
PAN No. pan 0-9
!*@$()_-+[]:,./
<Space>

Aadhar No. aaadhar-no max 12 numeric characters 0-9

.A-Z
a-z
0-9
PF No pf-no Max 30 Alphanumeric Characters
!*@$()_-+[]:,./
<Space>

UAN uan max 12 numeric characters

A-Z
a-z
.Max 30 Alphanumeric
ESI No esi-no 0-9
Characters
!*@$()_-+[]:,./
<Space>

A-Z
Voter ID voter-id max 10 alphanumeric characters a-z
0-9

A-Z
a-z
Visa No. visa-no Max 30 Alphanumeric Characters 0-9
!*@$()_-+[]:,./
<Space>

Visa Expiry Date visa-expiry ddmmyyyy format

A-Z
a-z
20 chars
Nationality nationality 0-9
!*@$()_-+[]:,./
<Space>

A-Z
a-z
Qualification qualification 50 chars 0-9
!*@$()_-+[]:,./
<Space>

A-Z
a-z
Experience experience 50 chars 0-9
!*@$()_-+[]:,./
<Space>

558 Matrix COSEC Web API User Guide

Table: Getting Worker details - Response Fields

Field Name Tag Name Valid Values Remarks

NA
M
Gender gender
F

+NA,A+,A-,B+,B-,AB+,AB-,o+,o-
Blood Group blood-group ,A1-,A1+, A1B-, A1B+,A2-
,A2+,A2B-,A2B+,B1

Height height 0 to 999

Weight Weight 0 to 999

Medical History medical-history max 50 alphanumeric characters

Marital Status marital-status married,unmarried,na

A-Z
a-z
Father/Spouse Namefather-spouse-name 30 chars 0-9
!*@$()_-+[]:,./
<Space>

personal-phone max 30 characters numeric characters or -

Personal Phone

numeric characters + ( ) -
Personal Cell personal-cell max 32 numeric characters Comma for separting
multiple mobile nos.

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

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

Official Extension official-extension max 10 numeric characters

numeric characters + ( ) -
Comma for separting
Official Cell official-cell max 32 numeric characters
multiple mobile nos.

Official E-mail max 100 alphanumeric characters alphanumeric characters

official-email
@-.

A-Z
a-z
Local Address1 local-address1 30 chars 0-9
!*@$()_-+[]:,./
<Space>

Matrix COSEC Web API User Guide 559

Table: Getting Worker details - Response Fields

Field Name Tag Name Valid Values Remarks

Local Address2 30 chars A-Z

a-z
0-9
!*@$()_-+[]:,./
<Space>

Local Street 30 chars A-Z

a-z
0-9
!*@$()_-+[]:,./
<Space>

Local City 40 chars A-Z

a-z
0-9
!*@$()_-+[]:,./
<Space>

Local Pin code pin max 10 numeric characters

A-Z
a-z
Local State local-state 40 chars 0-9
!*@$()_-+[]:,./
<Space>

A-Z
a-z
0-9
Local Country local-country 20 chars
!*@$()_-+[]:,./
<Space>

A-Z
a-z
0-9
Permanent Address1 permanent-address1 30 chars
!*@$()_-+[]:,./
<Space>

A-Z
a-z
Permanent Address2 permanent-address2 30 chars 0-9
!*@$()_-+[]:,./
<Space>

A-Z
a-z
Permanent Street permanent-street 30 chars 0-9
!*@$()_-+[]:,./
<Space>

A-Z
a-z
Permanent City permanent-city 40 chars 0-9
!*@$()_-+[]:,./
<Space>

Permanent Pin Code permanent-pincode max 10 numeric characters

560 Matrix COSEC Web API User Guide

Table: Getting Worker details - Response Fields

Field Name Tag Name Valid Values Remarks

A-Z
a-z
Permanent State permanent-state 40 chars 0-9
!*@$()_-+[]:,./
<Space>

A-Z
a-z
Permanent Country permanent-country 20 chars 0-9
!*@$()_-+[]:,./
<Space>

Organization ID organization 1-999999

Branch ID branch 1-999999

Department ID department 1-999999

1-999999
Section ID section

Category ID category 1-999999

1-999999
Grade ID grade

Designation ID designation 1-999999

customgroup1ID 1-999999
Custom group 1 ID

customgroup2ID
Custom group 2 ID 1-999999

1-999999
Custom group 3 ID customgroup3ID

Reporting In-Charge reporting-incharge 1 to 9999

Approval Policy ID Approval-Policy 1 to 999

Leave Group ID leave_group 2 Digits

Week Off Group week-off-group Max 2 chars Numeric

PIN pin 1 to 999999

Matrix COSEC Web API User Guide 561

Table: Getting Worker details - Response Fields

Field Name Tag Name Valid Values Remarks

Roaming-user-flg Roaming-user-flg 0 or 1

max 20 numeric characters

Card-1 card-1
max 21 characters= 20 numeric +
comma

max 20 numeric characters

Card-2 card-2
max 21 characters= 20 numeric +
comma

1 : enabled
Attendance Calculation attendance-calc
0 : disabled

Attendance Policy (T&A) attendance-policy Max 2 characters 1 to 99

Absentee Policy absentee-policy 1 to 99

1 to 99
Overtime Policy overtime-policy

Late-In Policy lateIn-policy 1 to 99

Early Out policy earlyOut-policy 1 to 99

C-Off Policy coff-policy 1 to 99

Shift Schedule Shift-schedule 1 to 999

Start Shift start-shift max 2 alpha-numeric characters

Holiday Schedule holiday-schedule 1 to 99

Skill ID SkillID 1-999

Valid values
A-Z
Contractor ID ContractorID Max 15 chars a-z
0-9
@_\:.

Valid Values
A-Z
Work Order ID WorkorderID Max 15 chars a-z
0-9
@_\:.

562 Matrix COSEC Web API User Guide

Table: Getting Worker details - Response Fields

Field Name Tag Name Valid Values Remarks

Assignment Period -start date Assignment-start-date ddmmyyyy

Assignment Period -end date Assignment-end-date ddmmyyyy

0 : Disabled
Door Access Through API door-access-api
1 : Enabled

PIN Authentication For Door 0 : Disabled

pin-authentication
Access 1 : Enabled

Driving License Expiry Date driving-license-expiry ddmmyyyy

Passport Expiry Date passport-expiry ddmmyyyy

Blacklisted 0 : Not Blacklisted

blacklisted
1 : Blacklisted

Max 50 chars
Valid Values :
A-Z
Blacklisted reason
Blacklisted-reason a-z
0-9
[space]
!@$*()_-+\[],.:

enabled only when

Reason for punching from 0 : unchecked
punch-reason-flg Location Mandatory For
unassigned location 1 : checked
Punch = 0,1

Valid Characters :
A-Z
Max 100 characters a-z
Custom Field 1 -10 field1-10
ddmmyyyy 0-9
space
[]().-_/

12: driving-license Uploaded document tag is

13: passport-no added for checking the
14: pan status of uploaded images
16: pf-no for respective field.
18: esi-no Multiple values are
21: field1 possible in this field.
22: field2
Uploaded-doc uploaded-doc 23: field3 If documents/images are
24: field4 present in field1,2 and 5
41: field5 then uploaded-doc should
contain value of field1,
42: field6
field 2 and 5 be provided in
43: field7
respective field.
44: field8
45: field9
46: field10

Matrix COSEC Web API User Guide 563

Table: Getting Worker details - Response Fields

Field Name Tag Name Valid Values Remarks

If more than one group is

assigned, then it should
Device Group Name device-group fetch multiple device group
name separated with
comma.

If more than one group is

assigned, then it should
Device Group ID device-group-id max 600 NUMcharacters
fetch multiple device group
id separated with comma.

564 Matrix COSEC Web API User Guide

Setting Worker Details

This API will be used to set existing Worker details.

Action

action=set

Syntax

http://<servername>/api.svc/v2/worker?action=<set>

License

System Account User: Basic + T&A + CWM

User Rights

User Rights

System Account Enabled if User has rights on Page.

CWM > Workers > WorkerProfile

Parameters

Table: Setting Worker details- Parameters

Multi-
Language Default
Argument Valid Values Mandatory Description
Character Value
set

id 15 chars No N NA This is worker id.

Allowed
Characters
When Auto Generate ID flag is OFF (in Global
A-Z
a-z Policy) then: Either “id” or “Prefix Auto-
0-9 generation-serial-length” or only “Auto-
/_.@: generation-serial-length” should be
mentioned in API.

When Auto Generate ID flag is ON (in Global

Policy) then: id/Prefix + Auto-generation-
serial-length/ only Auto-generation-serial-
length” not required to be mentioned in API

Zero-padding 0: unchecked No N 1 The 'zero-padding' tag defines whether in

1: checked mentioned <auto-generation-serial-length>
'0(zero)' is to be appended or not.

Prefix Max 15 chars No N NA If Id is mentioned, ignore this parameter.

Allowed The Prefix tag shows the fixed text which is to
Characters be used while creating new worker Id's
A-Z
a-z
0-9
/_.@:

Auto- 1-15 N NA
generation-
serial-length

Matrix COSEC Web API User Guide 565

Table: Setting Worker details- Parameters

Multi-
Language Default
Argument Valid Values Mandatory Description
Character Value
set

This is a field that shows whether worker is

active or not.
It has two values 0 and 1 for inactive and
active respectively.
Default value
active 0 or 1 No N =1 Note: If active is supplied as 1 and the worker
is blacklisted then error code "0070203002"
will be generated with validation message
"worker is Blacklisted."

This is the User Name.

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

Either "name" or "full-name" is a mandatory

field to be mentioned in API. I.e. if "name" tag
is mentioned than "full-name" is optional and
vice versa.
Allowed Characters
A -Z
a-z
Yes (if name
max200 0-9
not Set 3 NA
full-name alphanumeric ()
mentioned)
characters []
_ (underscore)
- (Hyphen)
. (full Stop)
/ , (comma)
@
' (single quote)
[Space]

If name /full
name is
supplied
This is the short name of worker Allowed
then first 15
Characters
characters
Max 15 A-Z
eliminating
short-name Alphanumeric No Set 2 a-z
invalid
Characters 0-9
values will
-
be set as
.
default
svalue of
short-name

This is the unique Reference code for every

reference -
1 to 99999999 No N NA Worker.
code

Valid values:
!@#$
*()_-
max 20 +[] \
integration -
alphanumeric N NA .,
reference
characters /
A-Z
a-z
0-9

566 Matrix COSEC Web API User Guide

Table: Setting Worker details- Parameters

Multi-
Language Default
Argument Valid Values Mandatory Description
Character Value
set

This is the date of birth of the user.

date-of-birth ddmmyyyy format No N Blank Note: - date-of-birth shall be lower than

joining-date.

birthday- 0=Unchecked
0 or 1 No N 0
message-flg 1=Checked

This is the
unique This is the joining date of the worker.
Reference
joining-date ddmmyyyy formate N Blank
code for Note: - joining-date should be higher than
every User. date-of-birth.

This is the confirmation date of the worker

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

Yes (if
This is the date of leaving of the worker.
reason for
ddmmyyyy format
leaving-date leaving to be N blank
Note: - leaving-date shall not be lower than
configured)
joining-date.

This is the reason of leaving an

organization.Allowed characters
Max 15
reason-for -
Alphanumeric A-Z
leaving No Set 1 blank
Characters a-z
0-9
!*@$()_-+[]:,./
<Space>

vehicle- Max 50 This is the Vehicle Registration No of the

Set 1 blank
registration-no Alphanumeric No user.
Characters Characters and comma(,)

This is the driving license of the user.

Max 30 A-Z
driving-license Alphanumeric Set 1 blank a-z
No
Characters 0-9
!*@$()_-+[]:,./
<Space>

This is the Passport no. of the user.

Max 30 A-Z
passport-no. Alphanumeric Set 1 blank a-z
No
Characters 0-9
!*@$()_-+[]:,./
<Space>

This is the PAN of the user.

Max 30 A-Z
Alphanumeric Set 1 blank a-z
pan-no. No
Characters 0-9
!*@$()_-+[]:,./
<Space>

Matrix COSEC Web API User Guide 567

Table: Setting Worker details- Parameters

Multi-
Language Default
Argument Valid Values Mandatory Description
Character Value
set

This is the Aadhar Number of the user.

0-9

If Aadhaar no entered is not Unique then it

max 12 numeric blank will display validation; “Aadhaar No. already
aadhar-no. No N
characters exists for User: id”

If Aadhar no is mandatory but still it is not

entered then it will display validation; “Enter
Aadhaar No”

This is the PF Number of the user.

.A-Z
Max 30 a-z
pf-No Alphanumeric No Set 1 blank 0-9
Characters !*@$()_-+[]:,./
<Space>

max 12 numeric
uan No N blank This is the UAN of the user
characters

This is the ESI Number of the

A-Z
.Max 30
a-z
esi-no Alphanumeric No Set 1 blank
0-9
Characters
!*@$()_-+[]:,./
<Space>

This is the Voter ID of the user.

max 10
A-Z
voter-id alphanumeric No Set 1 blank
a-z
characters
0-9

Yes (If visa- This is the IQAMA number of the user.

Max 30 expiry date A-Z
visa-no. Alphanumeric to be Set 1 blank a-z
Characters configured) 0-9
!*@$()_-+[]:,./
<Space>

This is the date of expiry of the IQAMA or

visa-expiry-
ddmmyyyy format No N visa.
date

This is the nationality of the user.

A-Z
20 chars a-z
nationality No Set 1 blank
0-9
!*@$()_-+[]:,./
<Space>

This is the qualification of the user.

A-Z
a-z
qualification 50 chars No Set 1 blank
0-9
!*@$()_-+[]:,./
<Space>

568 Matrix COSEC Web API User Guide

Table: Setting Worker details- Parameters

Multi-
Language Default
Argument Valid Values Mandatory Description
Character Value
set

This is the work experience of the user.

A-Z
a-z
experience 50 chars No Set 1 blank
0-9
!*@$()_-+[]:,./
<Space>

NA
M
gender No N NA This is the gender of the user.
F

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

height 0 to 999 No N blank This is the height of the worker

This is the weight of the worker

weight 0 to 999 No N blank

max 50
medical- This is the medical history of the worker
alphanumeric No Set 2 blank
history
characters

married,unmarried,
marital-status No N NA This is the marital status of the worker
na

This is the father or spouse name of the

worker.
A-Z
father/spouse 30 chars No Set 1 blank a-z
0-9
!*@$()_-+[]:,./
<Space>

personal- max 30 characters numeric characters or -

No N NA
phone

max 32 numeric numeric characters + ( ) -

personal-cell No N blank
characters Comma for separting multiple mobile nos.

max 100 alphanumeric characters

personal-e-
alphanumeric No N blank @-.
mail
characters.

max 30 numeric
official-phone No N blank numeric characters or -
characters

official- max 10 numeric This is the extension of the worker.

No N blank
extension characters

Matrix COSEC Web API User Guide 569

Table: Setting Worker details- Parameters

Multi-
Language Default
Argument Valid Values Mandatory Description
Character Value
set

This is the official mobile number of the

max 32 numeric
worker.
official-cell characters No N blank
numeric characters + ( ) -
Comma for separting multiple mobile nos.

No N blank This is the official e-mail of the worker.

official-e-mail max 100 alphanu- alphanumeric characters
meric characters @-.

No Set 1 blank A-Z

a-z
local-address1 30 chars 0-9
!*@$()_-+[]:,./
<Space>

local-address2 30 chars No Set 1 blank A-Z

a-z
0-9
!*@$()_-+[]:,./
<Space>

local-street 30 chars No Set 1 blank A-Z

a-z
0-9
!*@$()_-+[]:,./
<Space>

local-city 40 chars No Set 1 blank A-Z

a-z
0-9
!*@$()_-+[]:,./
<Space>

No N blank
local-pin-code max 10 numeric
characters

A-Z
a-z
local-state 40 chars No Set 1 Blank 0-9
!*@$()_-+[]:,./
<Space>

A-Z
a-z
0-9
local-country 20 chars No Set 1 Blank
!*@$()_-+[]:,./
<Space>

A-Z
a-z
permanent- 0-9
30 chars No Set 1 Blank
address1 !*@$()_-+[]:,./
<Space>

A-Z
a-z
permanent-
30 chars No Set 1 Blank 0-9
address2
!*@$()_-+[]:,./
<Space>

570 Matrix COSEC Web API User Guide

Table: Setting Worker details- Parameters

Multi-
Language Default
Argument Valid Values Mandatory Description
Character Value
set

A-Z
a-z
permanent-
30 chars No Set 1 Blank 0-9
street
!*@$()_-+[]:,./
<Space>

A-Z
a-z
permanent-city 40 chars No Set 1 Blank 0-9
!*@$()_-+[]:,./
<Space>

permanent- max 10 numeric

No N Blank
pincode characters

A-Z
a-z
permanent-
40 chars No Set 1 Blank 0-9
state
!*@$()_-+[]:,./
<Space>

A-Z
a-z
permanent-
20 chars No Set 1 Blank 0-9
country
!*@$()_-+[]:,./
<Space>

Default orga-
nization of
respective
system
account user
who is creat-
ing/updating
worker
organization 1-999999 No N This is the ‘Organization’ of the worker.
OR

Default orga-
nization
defined in
Enterprise
structure

Default
branch of
respective
system
account user
who is creat-
ing/updating
worker This is the ‘branch’ of the worker.
branch 1-999999 No N
OR

Default
branch
defined in
Enterprise
structure

Matrix COSEC Web API User Guide 571

Table: Setting Worker details- Parameters

Multi-
Language Default
Argument Valid Values Mandatory Description
Character Value
set

Default
department
of respec-
tive system
account user
who is creat-
ing/updating
worker This is the ‘department’ of the worker.
department 1-999999 No N
OR

Default
department
defined in
Enterprise
structure

Default sec-
tion of
respective
system
account user
who is creat-
ing/updating
1-999999 worker This is the ‘section’ of the worker.
section No N
OR

Default sec-
tion defined
in Enter-
prise struc-
ture

Default cate-
gory of
respective
system
account user
who is creat-
ing/updating
worker This is the ‘category’ of the worker.
category 1-999999 No N
OR

Default cate-
gory defined
in Enter-
prise struc-
ture

572 Matrix COSEC Web API User Guide

Table: Setting Worker details- Parameters

Multi-
Language Default
Argument Valid Values Mandatory Description
Character Value
set

Default
grade of
respective
system
account user
who is creat-
ing/updating
1-999999 worker This is the ‘grade’ of the worker.
grade No N
OR

Default
grade
defined in
Enterprise
structure

Default des-
ignation of
respective
system
account user
who is creat-
ing/updating
worker This is the ‘designation’ of the worker.
designation 1-999999 No N
OR

Default des-
ignation
defined in
Enterprise
structure

Default cus-
tomgroup1id
of respec-
tive system
account user
who is creat-
ing/updating
customgroup 1-999999 worker This is the ‘custom-group 1’ of the worker.
N
1D
OR

Default cus-
tom group 1
defined in
Enterprise
structure

Matrix COSEC Web API User Guide 573

Table: Setting Worker details- Parameters

Multi-
Language Default
Argument Valid Values Mandatory Description
Character Value
set

Default cus-
tomgroup2id
of respec-
tive system
account user
who is creat-
ing/updating
customgroup 2 worker This is the ‘custom-group 2’ of the worker.
1-999999 N
ID
OR

Default cus-
tom group 2
defined in
Enterprise
structure

Default cus-
tomgroup3id
of respec-
tive system
account user
who is creat-
ing/updating
customgroup 3 1-999999 worker This is the ‘custom-group 3’ of the worker.
N
ID
OR

Default cus-
tom group 3
defined in
Enterprise
structure

reporting-in- This is the ‘reporting incharge’ of the worker.

1 to 9999 No N
Charge

approval-pol- This is the ‘approval policy’ of the worker.

1 to 999 No N
icy ID

This is the leavegroup’ of the worker.

leave-group ID 2 Digits No N

week-off- This is the ‘week-off’ of the worker.

Max 2 chars No N
group Numeric

This is the access control system pin number

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

roaming-user-
0 or 1 No N 0 This is for roaming worker
flg

574 Matrix COSEC Web API User Guide

Table: Setting Worker details- Parameters

Multi-
Language Default
Argument Valid Values Mandatory Description
Character Value
set

max 20 numeric
characters
card-1 No N
max 21 charac-
ters= 20 numeric +
comma

max 20 numeric
characters
card-2 No N
max 21 charac-
ters= 20 numeric +
comma

attendance- 1 : enabled This is the ‘attendance calculation’ of the

No N 1
calc 0 : disabled worker

attendance- Max 2 characters This is the ‘attendance policy’ of the worker

No N
policy (T&A) 1 to 99 1 to 99

This is the absentee policy of the worker.

absentee-pol-
1 to 99 No N
icy For a worker the policy can be updated 99999
times.

This is the overtime policy of the worker.

overtime-pol- 1 to 99
No N
icy For a worker the policy can be updated 99999
times.

This is the late-in policy of the worker.

late-in-policy 1 to 99 No N
For a worker the policy can be updated 99999
times.

This is the early-out of the worker.

early-out-pol-
1 to 99 No N
icy For a worker the policy can be updated 99999
times.

This is the c-off policy of the worker.

c-off-policy 1 to 99 No N
For a worker the policy can be updated 99999
times.

Shift Schedule 1 to 999 No N This is theshift-schedule of the worker

max 2 alpha-
Start Shift No N This is thestart shift of the worker
numeric characters

Holiday
1 to 99 No N This is the holiday schedule of the worker
Schedule

Skill ID 1-999 No N default skill This is the skill of the worker.

Matrix COSEC Web API User Guide 575

Table: Setting Worker details- Parameters

Multi-
Language Default
Argument Valid Values Mandatory Description
Character Value
set

This is the contractor id for the worker

Valid values
A-Z
ContractorID Max 15 chars No N
a-z
0-9
@_\:.

This is the work order id for the worker

Valid Values
A-Z
WorkOrderID Max 15 chars No N
a-z
0-9
@_\:.

Work
This is the assignment start period of work
Order's
Assignment- assigned to worker. If the entered start date is
ddmmyyyy N validity start
start date greater than work order's end date then fail
date
message will returned.

Work
This is the assignment period of work
Order's
Assignment- assigned to worker.If the entered end date is
ddmmyyyy validity end
end date less than current date then fail message will
date
be returned.

If invalid value is mentioned or value supplied

door-access- is blank then, message returned: Invalid value
0 : Disabled
api No N 0 entered for Allow Door Access Through API.
1 : Enabled
It can be 0 or 1.

pin-authentica- 0 : Disabled
No N 0
tion 1 : Enabled

driving- ddmmyyyy
No N - This is the date of expiry of Driving License
license-expiry

passport-
expiry ddmmyyyy -
No N This is the date of expiry of Passport.

This is a field that shows whether user/worker

is blacklisted or not.

0 : Not Blacklisted NOTE : If an worker is already blacklisted and

1 : Blacklisted N Blacklisted = 1 or 2 is passed, then no action
Blacklisted No -
2 : Blacklist and should be performed.
Revoke Devices If a worker is blacklisted and Blacklisted = 0 is
passed, then the user should be restored
back, but should remain in inactive state.

Max 50 Chars
A-Z
Blacklisted- a-z
This specifies the reason for being black-
reason 0-9 No - -
listed.
[space]
!@$*()_-+\[]
,.:

576 Matrix COSEC Web API User Guide

Table: Setting Worker details- Parameters

Multi-
Language Default
Argument Valid Values Mandatory Description
Character Value
set

If control type for

repeated custom
fields is selected
as Textbox in
Global Policy:

Max 100
Alphanumeric
Characters:
A-Z
field <no>
a-z
0-9 This is to set value in custom fields.
(where <no>
will vary from 1 []().-_ /
<Space> If field is mandatory; and some value is
to 10, the user - -
already stored in DB for this field, then not
has to enter No
necessary to pass this argument in API
any one If control type for
syntax again
number here respeted custom
from 1 to 10) fields is selected
as Date in Global
Policy:

ddmmyyyy

When Multi
Language is
enabled, Invalid
character set =
SET1

Return created worker id in response on successful API execution.

Example:
success: 1060100001: saved successfully. Worker ID = <WorkerID>

If maximum limit in case of IDs is reached, for e.g., if auto – generation serial length=2 and zero-
padding =1, and all IDs from 00 to 99 are already existing, then return message : “failed: 1060203005
: Maximum limit reached for this configuration for ID creation”

If Contractor-id is updated and Work-order is set to ‘Null’, which further on set Assignment Start Date and
Assignment End Date as ‘NULL’.

While creating new worker, If active =0 is mentioned and any of the CWM related fields (Skill ID,
Contractor ID, Work order ID, Assignment Start Date, assignment end Date) is/are mentioned then return
message: “failed : 1060203002 : CWM related parameters cannot be added for inactive worker“

When ID is auto generated (by auto generate User ID flag in global policy) and maximum limit is reached,
then return message: “failed : 1060203005 : Maximum ID Creation limit reached by Auto Generation
process. ”

Matrix COSEC Web API User Guide 577

Deleting Worker Details

This API will be used to delete existing Worker details.

Action

action=delete

Syntax

http://<servername>/api.svc/v2/worker?action=<delete>

License

System Account User: Basic + T&A + CWM

User Rights

User Rights

System Account Enabled if User has rights on Page.

CWM > Workers > WorkerProfile

Parameters

Default
Argument Valid Values Mandatory Description
Value

id 15 chars yes This is worker id.If values other than the valid
Allowed values are entered, then fail message will be
Characters returned.
A-Z
a-z
0-9
/_.@:

578 Matrix COSEC Web API User Guide

CHAPTER 27 Integrate Alert API

This API is used to send the alert to the configured COSEC Server on completion of scheduled Integrate Process
as well as Retry Process.

Action = Command

• Alerting COSEC Server

Matrix COSEC Web API User Guide 579

Alerting COSEC Server

This API is used to send the alert to the COSEC server after the completion of schedule process in Integrate.

Action

action= command

Syntax

http://<servername>/api.svc/v2/integrate-alert?action=<command>;<argument>=<value>...

User Rights

User Rights

System Account Enabled if Enable API Access is enabled

ESS User Disabled

Parameters

Table: Sending Integrate Alert to COSEC Server - Parameters

Argument Valid Values Mandatory Default Value Description

This is the value of Integration mode to

be sent to the server:

1 : Export To MS SQL Server

2 : Import From Active Directory
3: Export To Postgre Server
4 : Export To Oracle Server
5 : Export To .csv
6: Export To MYSQL
7: Export To Text File
8: Export To GRP
9 : Export To DB2
11 : Import From MS SQL
1-37 except 13 : Import From Postgre
10,12,15,18,19,20, 14 : Import From Oracle Server
Integration-mode 25,26,29,30,32,33, Yes - 16 : Import From MySQL
35,36 17: Export To PeopleWorks
21 : Import From Customized SAP : Sql
Server
22: Custom Export-FP Template: Sql
Server
23 : Custom Export-FP Template:
Oracle
24 : Import From Customized SAP :
Oracle
27 : Export To Progress OpenEdge
28 : Export FP Template To File
31 : Import Events : SQL Server
34 : Import Events : Oracle
37 : Import From Progress OpenEdge

Yes It will fetch and send the export-

if Integration Mode= 1/ template-id to configured COSEC
Export-Template-id 1-999 -
3/4/5/6/7/8/9/17/22/23/ server corresponding to Integration
27/28 Mode.

580 Matrix COSEC Web API User Guide

Table: Sending Integrate Alert to COSEC Server - Parameters

Argument Valid Values Mandatory Default Value Description

Here, values should be sent to server

Yes corresponding to following template
If Integration Mode= 2/ type :
Import-Template-id 1-3 -
11/13/14/16/21/24/31/ 1=User
34/37 2=Event
3=User_Shift

It will fetch and send the scheduled

time of export/import process to
Schedule-datetime ddmmyyyyhhmm Yes - COSEC server.
Schedule-datetime cannot be later than
current datetime"

It will fetch and send the total number

Total-records 0-9(valid values) Yes - of records for export/import process to
COSEC server

It will fetch and send the number of

records, that were successfully
Succeeded-records 0-9(valid values) Yes -
transferred in scheduled export/import
process to COSEC server

Yes
only if COSEC
It will fetch and send the total number
Integrate >Schedule>
Previously-failed-total 0-9(valid values) - of records that were failed in previous
Include Previously
scheduled process to COSEC server
Failed is enabled and
checked

Yes
It will fetch and send the number of
only if COSEC
records(that were failed in previous
Integrate >Schedule>
previous-succeeded 0-9(valid values) - scheduled process but successfully
Include Previously
transferred in current scheduled
Failed is enabled and
process) to COSEC server
checked

Matrix COSEC Web API User Guide 581

582 Matrix COSEC Web API User Guide
CHAPTER 28 Multiple APIs Call

This API is a common API which can invoke multiple APIs from a single POST request.

Syntax

http://<servername>/api.svc/v2/multipleapi?

License Required

Time and Attendance License or VMS License

User Rights

User Rights

System Account Enabled

ESS User Enabled for all ESS users.

Visitor Enabled for All Registered Visitors with 'isVerified' flag = 1

Parameters

Table: Multiple APIs Call- Parameters

Argument Valid Values Mandatory Default Value Description

0 = Host User / SA
User If value not supplied, default 0 will be
user-type No 0
1 = Visitor considered.

Send the array of multiple API URLs as post data.

Matrix COSEC Web API User Guide 583

584 Matrix COSEC Web API User Guide
CHAPTER 29 API Response

Every time a request is received the syntax, format and the supported authentication shall be validated prior to
generating a response. This chapter discusses the response structure of COSEC Web APIs. The API response
shall consist of the following:

• Response Message

• Response Code

The generic response format will be as follows:

<status> : <response code> : <response message>

Response Messages
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: <response code> : successful>

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

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

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

<failed: <response code> Invalid syntax “#”>

• For incorrect argument values:

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

• If a mandatory argument is missing:

<failed: <response code> Incomplete command “#”>

Matrix COSEC Web API User Guide 585

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

• “ # ” specifies the entire request string.

Response Codes
Every COSEC API response message is accompanied by a 10 digit numeric response code. The response code is
structured as follows:

Fig. Response Code

• API Code - Digits 1-3. Valid values: 000-999. Identifies the API (See Table).

• Action Code - Digits 4-5. Valid values: 00-99. Identifies the Action requested (See Table).

• Category Code - Digits 6-7. Valid values: 00-99. Identifies the category of response (See Table).

• Actual Response Code - Digits 8-10. Valid values: 000-999. Identifies the actual response (See Table).

Table: API Codes

API Request Type API Code

none 000

attendance-daily 001

attendance-monthly 002

event-ta 003

event-ta-date 004

event-acs 005

event-acs-date 006

user 007

device 008

organization 009

branch 010

designation 011

section 012

department 013

category 014

586 Matrix COSEC Web API User Guide

Table: API Codes

API Request Type API Code

grade 015

group-rename-list 016

template-list 017

template-details 018

import-template-list 019

import-template-details 020

events 021

accessroutemaster 022

accessroutedetails 023

site 024

event-others 025

device-commands 026

device-users 027

datatransfer 028

template-data 029

leave-balance 030

leave-group 031

leave-details 032

leave-application 033

leave-approval 034

holiday 035

group-members 036

attendance-correction 037

canteen-account-details 038

canteen-expenditure-summary 039

canteen-menus 040

canteen-menus-schedule 041

canteen-correction-application 042

shift-schedule 043

shift-details 044

notifications 045

loginuser 046

attendance-correction-approval 047

short-leave-entry 048

short-leave-authorization 049

attendance-authorization 050

Matrix COSEC Web API User Guide 587

Table: API Codes

API Request Type API Code

ot-coff-authorization 051

encryption-key 052

coff-details 053

search-user 054

in-out-reasons 055

canteen-expenditure-details 056

change-password 058

imei-registration 059

coff-balance 060

monthly-process 061

Table: Action Codes

Action Description Action Code

none Action not available 00

get To fetch details from server 01

set To create new records 02

update To update existing records 03

delete To delete a particular record 04

command To send command to server 05

assign To assign devices to user 06

To delete user's credentials from the

del-credential 07
system

enroll To enroll new credentials 08

list To get a list of devices 09

revoke To revoke user's access 10

set-credential To save user's credentials 11

setphoto To save user's photo 12

Table: Category and Actual Response Codes

Category: Success Description Category Code Actual Response Code

Request is valid, but no

No Records Found 00 000
records are present

Data/Request Submitted and

Successful 00 001
processed successfully

Saved Successfully For Set/Update APIs 00 002

588 Matrix COSEC Web API User Guide

Table: Category and Actual Response Codes

Other Messages for Applied/Deleted/Updated/

00 003
Success Changed Successfully

Category: URL Description Category Code Actual Response Code

Syntax Errors Error in processing the URL 01 001

Required License not

License 01 002
available for API

Mandatory parameter is
01 003
Parameter missing

Parameter is invalid 01 003

Correct Parmeter specified

01 004
Value but value is missing

Correct Parameter specified

01 004
but value is Invalid

Category: Access Description Category Code Actual Response Code

Login user does not have

API Access Rights 02 001
rights to access any API

Login user does not have

API Specific Rights rights to access a specific 02 002
API

Rights on Users Insufficient User Rights 02 003

Rights on Device Insufficient Device Rights 02 004

Server Access URL Access is denied 02 005

Category: Process Description Category Code Actual Response Code

Wrong/Unexpected
Invalid Command 03 001
parameter Values

Restrictions or checks on
Invalid Command 03 002
parameter value

Parameter combination
Invalid Command 03 003
violation

Invalid Command Date Validations 03 004

Invalid Command Maximum Limit 03 005

Invalid Command Already Exists 03 006

A value does Not exist or

Invalid Command 03 007
Disabled

Process Failure/Exception/
Invalid Command 03 008
Error

Example

Sample Request:

http://matrixserver/api.svc/v2/organization?action=set;code=Apex;name=Apex Industries

Sample Response:

success: 0090200001 : successful

Matrix COSEC Web API User Guide 589

In the given example, the request sent to add an organization to the COSEC database returns a successful
response. The response code “0090200001” can be read as shown:

• 009 - API code for “organization”

• 02 - Action code for “set”
• 00 - Category code for “success”
• 001 - Actual Response Code for successful submission and processing of data.

In the following example, the API requests a user’s profile to be updated with ‘date of birth’. However the ‘id’
argument is left without a value.

Sample Request:

http://matrixserver/api.svc/v2/user?action=set;id=;date-of-birth=22061978

Sample Response:

failed: 0070201003 : Incomplete command id

• Response Messages accompanying a Response Code are descriptive and may vary or change
depending on the parameters, values etc. of the particular case in question. Third party applications
should use only Response codes for decision making.

• In each API response, a specific validation message may also appear depending on the API,
access rights, device rights etc. For e.g. “User is not a Reporting Group In-Charge”, “Insufficient
User Rights” or “Authorization not allowed for Dates later than current date” etc.

590 Matrix COSEC Web API User Guide

CHAPTER 30 Symptoms

This shall be used to get server’s configured symptoms, their threshold values & warning message.

Action

action=get

Syntax

http://<servername>/api.svc/v2/symptoms?action=<get>

License Requirement:

COSEC Centra:

· System Account User: Basic License

· ESS User: BASIC + ESS

If license is not available, return message: “License not available for this API.”

User Rights

User Rights

System Account Enabled

ESS Enabled

Response Field
Response should be the configured values in server at Admin, User, Temperature and Threshold Configuration. The
response will contain the following fields:

Field Name Tag Name Valid Values Remarks

Temperature Applicable temperature-applicable 0: Disable Parameter will indicate

1: Enable whether temperature regarding
field and details needs to be
display or not on self
declaration page and records
page.
Also, if value is enable then
only, application will receive
temperature in further
responses.

Matrix COSEC Web API User Guide 591

Field Name Tag Name Valid Values Remarks

Temperature Type temperature-type 0: Fahrenheit Provide the value set in server

1: Celsius regarding type of temperature.

Temperature Threshold temperature-threshold max 5 characters Threshold value of

temperature should return.

Symptoms Applicable symptoms-applicable 0: Disable Parameter will indicate

1: Enable whether symptoms regarding
field and details needs to be
display or not on self
declaration page and records
page.
Also, if value is enable then
only, application will receive
symptoms in further
responses.

Symptoms ID symptoms-id 0-99999 All the configured symptoms ID

should be sent with comma
separated values
Symptom ID = 0 has been
fixed for value ‘None’

Symptoms Name symptoms-name 50 characters Name of the symptoms should

be returned, Name should be
synchronized with ID of
symptom.
For e.g. Symptoms ID are :
0,1,3,5
Symptoms Name are: None,
Fever, Cold, Headache
The mapping should be: 0-
None, 1-Fever, 3-Cold, 5-
Headache

Symptoms Threshold ID Symptoms-threshold-id 0-99999 Configured symptoms ID

threshold should be sent.
Symptoms Threshold ID = 0
has been fixed for value ‘All’.
Below will be the mapping:
All - 0
Any one - 1
Any two - 2
Any three - 3
Any four - 4

Symptoms Threshold Name symptoms-threshold-name NA Threshold value of Symptoms

should return.
Symptoms Threshold Name
should be mapped with
Symptoms Threshold ID.

Warning warning Max 100 characters Warning message which

should display when user
reaches/exceeds threshold
value.

592 Matrix COSEC Web API User Guide

CHAPTER 31 Health Declaration

This shall be used to get the user’s declared Health Records data for the specific date-range, and to submit new Self-
Declaration for Temperature and Symptoms.

Action

For Action= GET

For Action= SET
For Action= UPDATE

Syntax

http://<servername>/api.svc/v2/health-declaration?action=<get/set/update>;<argument>=<value>...

License Requirement

ESS License. If license is not available, return message: “License not available for this API.”

COSEC Centra:
· ESS User: BASIC + ESS

If license is not available, return message: “License not available for this API.”

User Rights

User Rights

System Account Enabled if SA has rights on provided user and rights on

Admin > System Account > Roles & Rights Configuration
> Users > Health Declaration (For Declaration page)
Admin > System Account > Roles & Rights Configuration
> Users > Health Records (For Records page)

ESS Enabled if User has ESS enabled and has User Rights
on the following Page:
ESS >Health > Self Declaration
ESS > Health > Health Records

Matrix COSEC Web API User Guide 593

Parameters

For Action= GET

Argument Valid Values Description

userid varchar(15) Mandatory field.

Note:
For ESS user:
The userid should be login user’s ID.
For a System Account user:
The userid can be any user’s id. If the
System account user has rights on
that user, return the records.
Otherwise, return message as per
mentioned below.
With comma separation, SA can
provide multiple user’s ID.

date-range ddmmyyyy-ddmmyyyy (From Date – The period for which the User Health
To Date) Records need to be fetched.
Valid Values: Not a mandatory field.
dd (Date): 01-31 If not mentioned, then by default the
mm (Month): 01-12 response will contain Health Records
for the current date.
yyyy (Year): 4 digits

field-name temperature Not mandatory field.

symptoms This argument will return specific
temperature, symptoms parameter’s value for the user for
specified date.
If argument passed with value
temperature then, in response only
‘Temperature’ of user for the defined
date should be sent.
If argument passed with value
symptoms then, in response only
‘Symptoms’ of user for the defined
date should be sent.
If argument passed with value
temperature, symptoms then, in
response ‘Temperature & Symptoms’
of user for the defined date should be
sent.

594 Matrix COSEC Web API User Guide

Response Field

Based on the value of supplied arguments, the API will return the health Data for the users, for selected date. The
response will contain the following fields:

Field Name Tag Name Valid Values Remarks

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

TID (form no.) tid 10 Digits Same as form-number.

Auto Generated on
submitting health
parameters through health
declaration

Declaration-Date declaration-date dd/mm/yyyy Date for which Self-

Declaration is done.
Valid values:
mm(Month): 01-12
dd(Date): 01-31
yyyy(Year): 4 digits

Date Time time dd/mm/yyyyhh:mm Date-Time of each entry for

the selected date.
Note: Server will have
multiple entries for each
day.

Temperature Source Temperature-source 1: ESS Source of the temperature

2: App and will be provided.

3: SA Provide ID of the source.

4: Device Note: ID should be

internally fixed in server
5: Others
and application as per
provided.
As per our updated new
design, we will always keep
new records of temperature
when we are receiving
temperature through others
and when we receive
symptoms through ‘Others’
then we will overwrite it as
we will keep only one
record for symptoms for a
day.

Temperature temperature For Fahrenheit: 90.0 - Provide declared/detected

110.0 temperature
For Celcius: 32.0 – 43.0

Matrix COSEC Web API User Guide 595

 Field Name Tag Name Valid Values Remarks

Symptoms Source Symptoms-source 1: ESS Source of the symptoms

2: App declaration will be
provided.
3: SA
Provide ID of the source.
5: Others
Note: As of now, in this
argument we will never
receive ‘Device’ as
currently there is no
provision of providing
symptoms through device.

Symptoms symptoms 0-999 Here, server will send

comma corresponding selected ID
of the symptom.
While displaying the
symptoms to user,
application needs to map
ID with name through API
‘symptoms’.

Below is the example of user’s records of a date: 10/05/2020

1. Self-Declaration through ESS at 10:00

• Temperature: 100.5
• Symptoms: Fever, Headache
• TID: 001

2. Device Detected Temperature at 10:30

• Temperature: 101.5
• TID: 002
3. Received Temperature through source others at 15:00
• Temperature: 101.1
• TID: 003

Response should be:

<health-declaration>
<userid> 123 </userid>
<tid> 001 </tid>
<declaration-date> 10/05/2020 </declaration-date>
<time> 10/05/202010:00 </time>
<temperature-source> 1 </temperature-Source>
<temperature> 100.5 </temperature>
<symptoms-source> 1 </symptoms-Source>
<symptoms> 1,2 </symptoms>
</health-declaration>
<health-declaration>
<userid> 123 </userid>
<tid> 002 </tid>
<declaration-date> 10/05/2020 </declaration-date>
<time> 10/05/202010:30 </time>
< temperature-source> 4 </ temperature-Source>
<temperature> 101.5 </temperature>
</health-declaration>

596 Matrix COSEC Web API User Guide

<health-declaration>
<userid> 123 </userid>
<tid> 003 </tid>
<declaration-date> 10/05/2020 </declaration-date>
<time> 10/05/202015:00 </time>
< temperature-source> 5 </ temperature-Source>
<temperature> 101.1 </temperature>
</health-declaration>

For Action= SET

Multi-language
Argument Valid Values Default View Description
character set

action set NA NA This is a command to

set health-declaration
of user.
When SET request is
received then rights
of self-declaration
needs to be checked.
Mandatory Field.

user id Max 15 chars NA NA Mandatory Field.

declaration-date 8 characters NA NA Mandatory Field.

Format: ddmmyyyy
dd(Date): 01-31
mm(Month): 01-12
yyyy: Year

Source 2,5 NA NA Mobile Application

needs to provide
source ID while
sending SET request
to server.
For SET request,
application will
always needs to send
ID = ‘2’ (i.e. App) for
temperature and/or
symptoms
declaration.

temperature Fahrenheit: 90.0 - NA NA If ‘temperature-

110.0 applicable’ is enable
Celcius: 32.0 – 43.0 under ‘symptoms’
API then, this
argument is
mandatory.
If disable then it is
non-mandatory.

Matrix COSEC Web API User Guide 597

 Multi-language
Argument Valid Values Default View Description
character set

symptoms 0-999 NA None If ‘symptoms-

comma applicable’ is enable
under ‘symptoms’
API then, this
argument is
mandatory.
If disable then it is
non-mandatory.

NOTE: Return success message in response on successful API execution (only when API has been executed
successfully)
Example:
Success: 1160200002: saved successfully.

For Action= UPDATE

Argument Valid Values Description

Action update This is a command to update health-Declaration of
user for specified Declaration Date.

When UPDATE request is received then rights of

self-declaration needs to be checked.

Mandatory field.
tid max 10 numeric characters Mandatory field.
userid Max 15 chars Mandatory field.
An application will be identified, based on tid and
userid.
Source 2,5 Mobile Application needs to provide source ID while
sending UPDATE request to server.

For UPDATE request, application will always needs

to send ID = ‘2’ (i.e. App) for temperature and/or
symptoms declaration.
temperature Fahrenheit: 90.0 - 110.0 If ‘temperature-applicable’ is enable under
Celsius: 32.0 – 43.0 ‘symptoms’ API then, this argument is mandatory.

If disable then it is non-mandatory.

symptoms 0-9999 If ‘symptoms-applicable’ is enable under
‘symptoms’ API then, this argument is mandatory.

If disable then it is non-mandatory.

If argument not available even if ‘symptoms-

applicable’ is enable, then system should consider
the value as ‘None’.

The response will contain the actual validation as seen on the web page.

598 Matrix COSEC Web API User Guide

NOTE: Return success message in response on successful API execution (only when API has been executed
successfully)

Example:
success: 1160300002: saved successfully

Matrix COSEC Web API User Guide 599

600 Matrix COSEC Web API User Guide
CHAPTER 32 Custom Field

This shall be used to get the status of custom fields, for 3rd party applications as well as for APTA application.

Action

action= get

Syntax

http://<servername>/api.svc/v2/custom-field?action=<get>;<argument>=<value>...

License Requirement:

If license is not available, return message: “License not available for this API.”

User Rights

User Rights

System Account Enabled

ESS Enabled

Visitor Enabled if Visitor is registered and verified by using

assigned token

Matrix COSEC Web API User Guide 601

For Action= Get

Argument Valid Values Description

Not Mandatory Field.

If not supplied, default 0 should

be considered.

If user-type is set 0 then all the

field should be returned for
User / Worker in response.
0: User/Worker
1: Contractor If user-type is set 1 then all the
user-type field should be returned for
2: Visit
3: Visitor Contractor in response.

If user-type is set 2 then all the

field should be returned for
Visit in response.

If user-type is set 3 then all 5

fields should be returned for
Visitor in response

Not Mandatory Field.

If not supplied, default 0 should
be considered.
0=No "If visitor-login is set 1 then it
visitor-login 1=Yes implies that it is visitor login
and they can view custom
fields of Visit/Visitor through
user-type parameter.

Response Field:

Field Name Tag Name Valid Values Description

1=field1
2=field2
3=field3
4=field4
5=field5
Field No. field-no
6=field6
7=field7
8=field8
9=field9
10=field10

0= Inactive
Active active
1= Active

A-Z
a-z
Field Name field-name Max 100 characters 0-999
[]().-_/
<Space>

Type
1 = Textbox
type
0= = Datepicker

602 Matrix COSEC Web API User Guide

 Field Name Tag Name Valid Values Description

0 = Uploading document not

allowed
Upload allow-upload
1 = Uploading document
allowed

Mandatory 0 = Not Mandatory

mandatory
1 = Mandatory

0 = User/Worker Applicable For field name is

1= Contractor used to differentiate between
Applicable For applicable-for
2= Visit User and Contractor and Visit
3= Visitor and Visitor.

Matrix COSEC Web API User Guide 603

604 Matrix COSEC Web API User Guide
CHAPTER 33 Mark Group Attendance

This shall be used to submit new Mark Group Attendance application and to get or delete Mark Group Attendance
records from server via APTA or 3rd party application.

Syntax

http://<servername>/api.svc/v2/mark-group-attendance?action=<get/set/delete>;<argument>=<value>...

License Requirement:

• System Account User: Basic (PLT) License + T&A

• ESS User: BASIC + ESS + T&A
• If license is not available, return message: "License not available for this API."

User Rights

User Rights

System Account Enabled if SA has "Add /Delete" rights on:

Admin > System Account > Roles & Rights Configuration
> Time and Attendance > Mark Group Attendance

ESS User Enabled if User is RIC user & has In-charge Permissions'
of Mark Group Attendance.

It supports the following APIs:

• GET APIs
• SET APIs
• DELETE APIs

Matrix COSEC Web API User Guide 605

GET APIs

Action

action= get

Parameters For Action= Get

Argument Valid Values Description

month-year Mmyyyy Month-year for which Group Attendance Entry are to

be fetched.
If month-year is not mentioned then consider it to be
“current month” and “current year” by default.

Response:
• No Group Attendance entry added by user, then return "No Record Found"
• If any Group Attendance entry added by user, then return id, name, and attendance detail like "in-out,
event-datetime, count, spfid, User-id's, source used in that attendance.
• For RIC User, the mark Group attendance added by him will be shown in the list. for SA, all mark group
attendance entries will be shown.

Example:

Tag Valid Values Description

Id max 15 numeric characters Unique ID of the attendance

This is the date time with group

application-datetime ddmmyyyyhhmmss format
attendance application was generated

Name Max 45 Characters Name of the Attendance.

0=IN
In-out This is the IO type for the event.
1=OUT

This is the event date time. i.e. the date

event-datetime ddmmyyyyhhmmss format
time when actually happened.

numeric characters
Count Count of user for which event is generated
Max 3 digit

2 digits This value specifies any special functions

Spfid
Valid range = 0-12 associated with the event.

This is the ids of the users for whom event

is marked. Multiple user-id should be
user-id Varchar(15)
comma separated.
(The userid passed should be unique.)

11= ESS
Source Source of the application
12= APP

606 Matrix COSEC Web API User Guide

SET APIs

Action

Action= set

Field Name Valid Values Description

This is the application Name.

Allowed Characters
A-Z
Name Max 45 chars
a-z
0-9
-_. ()[]

Not Mandatory Field.

0= Create
Application If not supplied, default 0 should be
1= Save
considered.

Allowed Characters : 10 numeric Char.

It is a mandatory field when application = 1
Temporary-id 0 to 9
(save). Value should be ignored if
application = 0

This is the user id for which attendance is

to be marked. Allow to set multiple id,
Allowed Characters : 15 alphanumeric
each separated by ", (comma)" e.g.:"1, 3,
Char.
7, 9…”
A to Z
Mandatory field if application= 1. System
mark-user-id a to z
should provide message for incomplete
0 to 9
command, if this field is not provided.
/_\\.@:
Value should be ignored if Application is
not 1.

This is the event date time. i.e. the date

time when actually happened.
Mandatory field if Application=1.

If value has more than 14 characters

event-datetime ddmmyyyyhhmmss format
length, then system will consider only first
14 characters for processing in the format
of ddmmyyyyhhmmss.
Value should be ignored if Application is
not 1.

This is the IO type for the event.

Valid values 0,1 If Application=1 and value is not specified,

In-out 0= IN (Default) default value will be considered.
1=OUT
Value should be ignored if Application is
not 1.

This value specifies any special functions

associated with the event.

2 digits If Application=1 and value is not specified

Spfid
Valid range = 0-12 then default (0) will be considered.

Value should be ignored if Application is

not 1.

Matrix COSEC Web API User Guide 607

Field Name Valid Values Description

When location is calculated via GPS.

This parameter will contain : latitude

Format : +XXX.XXXXXX or -XXX.XXXXXX

Valid Values : -90.000000 to +90.000000

Gps_latitude 11 characters
If Latitude is invalid or out of range, return
error message for invalid parameter.

Value should be ignored if Application is

not 1.

When location is calculated via GPS.

This parameter will contain : latitude

Format : +XXX.XXXXXX or -XXX.XXXXXX

Valid Values : -180.000000 to

Gps_longitude 11 characters +180.000000

If Latitude is invalid or out of range, return

error message for invalid parameter.

Value should be ignored if Application is

not 1.

6 characters Not Mandatory.

A-Z
location-code a-z Location Code from configured location
0-9 master.

Max 50 alphanumaric characters.

A-Z
Not Mandatory.
a-z
punch-reason 0-9
Value should be ignored if Application is
_-
not 1.
<space>
()[].,/+!@$:*

'temporary-id'" - duration for this HTTP session will be maximum 30 minutes

608 Matrix COSEC Web API User Guide

DELETE APIs

Action

action= delete

Field Name Valid Values Description

Allowed Characters : 10 numeric Char. It is a mandatory field when application = 1

Temporary-id 0 to 9 (save). Value should be ignored if
application = 0

Matrix COSEC Web API User Guide 609

610 Matrix COSEC Web API User Guide
CHAPTER 34 Group FR Process

This shall be used to request for FR Process on Image or to Update FR result on image via APTA or 3rd party
application.

Action

action= command

Syntax

http://<servername>/api.svc/v2/group-fr-process?action=<command/update >;<argument>=<value>...

License Requirement:

• System Account User: Basic (PLT) License + T&A

• ESS User: BASIC + ESS + T&A
• If license is not available, return message: “License not available for this API.”

User Rights

User Rights

System Account Enabled if SA has "Add /Delete" rights on:

Admin > System Account > Roles & Rights Configuration
> Time and Attendance > Mark Group Attendance

ESS User Enabled if User is RIC user & has In-charge Permissions'
of Mark Group Attendance.

For Action = Command

Argument Valid Values Description

temporary-id Allowed Characters : 10

It is a mandatory field when application = 1
numeric Char.
(save). Value should be ignored if application =
0 to 9 0

image-id Allowed Characters : 10 Mandatory field if application= 1.

numeric Char. System should provide message for incomplete
0 to 9 command, if this field is not provided.

Matrix COSEC Web API User Guide 611

Response:

If Face is detected then return the

• All the Detected Face Co-ordinates
• FR result of each face
• Detected user's ID for whom Face Recognition Feature is enabled and current user is Reporting Group In-
Charge (Login User has rights).

The response will contain Face Count and list of Face ID, FR result, Face Co-ordinates and User ID in below
defined fields

Tag Valid Values Description

Defines the count of faces detected from a

detected-face 0-20
image

face-id max 10 numeric characters Unique ID of the face.

0- Not recognized
fr-result 1- Not in your group Result of the face.
2- recognized

user-id ID of the recognized user

States the co-ordinates of the detected

face
Should be send in below format:
Coordinates
StartX, LengthX, StartY, LengthY
Example: 1,3,4,7

Example:

Face ID FR Result User ID Coordinates

1 0 1,3,4,7

2 1 6,6,3,5

3 2 1001 2,5,7,4

612 Matrix COSEC Web API User Guide

Action

action= update

Field Name Valid Values Description

Allowed Characters : 10 numeric Char. It is a mandatory field when application = 1

temporary-id 0 to 9 (save). Value should be ignored if
application = 0

Mandatory field if application= 1.

System should provide message for
image-id max 10 numeric characters incomplete command, if this field is not
provided.

Mandatory field if application= 1.

System should provide message for
face-id max 10 numeric characters incomplete command, if this field is not
provided.

0- Not recognized (Default)

fr-result Result of the face.
1- recognized

15 alphanumeric Char.
A to Z
ID of the recognized user.
tag-user-id a to z
It is a mandatory field if fr-result=2
0 to 9
/_\\.@:

Matrix COSEC Web API User Guide 613

SECURITY SOLUTIONS

MATRIX COMSEC

Head Office:
394-GIDC, Makarpura, Vadodara - 390010, India.
Ph.: (+91)18002587747
E-mail: [email protected]

Website: www.MatrixSecuSol.com