Biometric Web API 2.0

CAMS is the pioneer and global leader in Biometric Research and Development. It supports the Web API 2.0 for the biometric time, attendance and access control machines, to integrate with a website or any web application. It provides the powerful REST APIs and Callback APIs for various operations to communicate with the biometric machines from the your own server application. API supports reading the inputs with Fingerprint, Face, Card, Palm, Vein, Retina, Body Temperature and Password

Biometric Device To Web Application Communication Architecture Biometric time and attendance devices can be kept in any location across the globe. As long as they are connected to online, they can be integrated with your own web application to get the realtime attendance logs and the users in the device can be managed from the web application. All the communication happens over HTTP. Hence, no software at the local network is required for establising the communication.

Protocol Engine Top Level Design

Top Level Digram of CAMS Biometric Web API Communication Architecture Biometric devices placed at any location are connected to the CAMS Protocol Engine through internet. Protocol Engine is hosted at CAMS Data Server. Lite version of Protocol Engine can also be hosted at your server. This engine is responsible for receiving, managing, and sending data to the Cloud systems and the biometric device. Engine maintains the attendance data only when the cloud server or the biometric device is not reachable or failed to respond. As soon as adjacent systems are start running, then the respective data would be wiped out.

Simple Integration

To receive the realtime attendance data from biometric device to your server, you just need to expose an URL from your server and map it with the device in API Monitor. URL should handle the incoming parameters which will have user id, attendance time, device id and etc,. Check the sample request of various operatiosn from Sample Request Formats. Sample program for recording realtime attendance is available at the bottom of this page. Once the URL is mapped, you can start giving attendance in the biometric device and your server will start receiving the real time attendance data.

To communicate with device for adding, deleting and managing various operations, you will have to call the CAMS RESTful API (to be shared once purchased) which will take care of the requested operations

API Types

CAMS offers two set of APIs.

Attendance API : Gives you the realtime biometric attendance data to your server.
Management API: Helps to manage the device with the following features

Add a user in the device (Operation: AddUser)
Delete a user from the device (Operation: DeleteUser)
Trigger Enroll Fingerprint in device (Operation: EnrollFingerprint)
Display a Short Message on the device when user is punching on device (Operation: EnableMessage)
Disable displaying Short Message (Operation: DisableMessage)
Trigger device to send user's photo taken by the device during the punch (Operation: SendAttendancePhoto)
Notification when a user is added/updated in the device (Operation: ManuallyUserUpdated)
Notification when a user is deleted in the device (Operation: ManuallyUserDeleted)
Notification when date is modified in the device (Operation: ManuallyDateModified)
Load the attendance data between given timeline (Operation: LoadPunchLog)
Get device information such subscription status(Operation: SendDeviceInfo)
Clear all attendance logs in the device(Operation: ClearLog)
Trigger device to send all user information include their templates (Operation: TriggerUserDetail)

License for every API has to be purchased to avail its features.

URL Types

CallBack API: For any communication, from the device to your server, you have to expose an URL at your server which will be called back. The communication is realtime, there will not be any time latency
RESTful API: For any communication, from your server to the device, the exposed URL from CAMS should be called. The time latency may vary from 30 secs to 60 secs

API Monitor

For all the services purcased, API Monitor login shall be provided, where the configurations such as CallBack URL, Security Key, Your server IP and etc can be configured to every device.

You will be able to monitor the live attendance records transferring device to your server. You can do bulk excel upload for adding/deleting the user in the device. You can request for resending attendance data from the device. and more monitoring activities shall be performed on this tool.

Data Format for CallBack API

All the request data and response data would be in JSON format.

Note that, the request data will be passed in POST Body parameter with the key name as request_data

{
	ServiceTagId:
	ApiRequestInfo:{
		AuthToken:,
		Operation:,
		UserId:,
		OperationTime:,
		OperationReferenceId:,
		OperationData:
	},
}

ServiceTagId: This is a device id, which will be given while you buy a device or registered a 3rd party device with CAMS
ApiRequestInfo.AuthToken: This is something configured in the API Monitor by you for every device. You can validate this token while you receive the request data
ApiRequestInfo.Operation: This says request is for which operation.
- PunchLog : Sends the real time attendance logs to your server
- ManuallyUserUpdated : User has added/modified signature (fingerprint/ face/ palm/ password/ pin) in the device
- All possible RESTful API operations
ApiRequestInfo.UserId: User id registered in the device, if applicable to the operation
ApiRequestInfo.OperationTime: Operation requested time in EPOCH/unix timestamp format. Note that, the time time displaying on the device is already timezone adjusted. So, while converting this, it should be converted it to GMT+0 to get the time in your timezone.
ApiRequestInfo.OperationReferenceId: In CallBack API, this will be NULL. In Lazy Response, this will be same id as one passed in your request call
ApiRequestInfo.OperationData: This can be null or some valid data as per the operation. The data format of this object shall be shared with operation details in the following sections.

Response: Following is the expected response from your server to be returned for all the request you receive from CAMS.

{
	status: "done"
}

If the status is anything other than done, then the same request data will be passed again and again till your server send this response. So if there is any failure at your server while processing the incoming request, keep it as internal to your server. But return always as expected above.

Data Format for RESTful API

RESTful API calls should be made when your server needs to talk to the biometric device. All the request data and response data would be in JSON format. Note that, the request data should be passed in POST body parameter with the key name as request_data.

There are two responses to be return for every request. One will be returned immediately after receiving the request. Two is Lazy Response, which will be coming to your server through your CallBack API after receiving the response from te device. Since, the response from the device is not the real-time, as soon as the response comes from the device, your server will be notified with lazy response.

The request object for CallBack and RESTful API are same. You need to pass any reference id in ApiRequestInfo.OperationReferenceId:. This is can empty or any alphanumeric value. The same will be returned in the Lazy Response.

Response of RESTful API

{
	StatusCode:
	Status: done
	RequestedOperation:
	OperationReferenceId:
	OperationData:
}

Status will be done and StatusCode will be 0 for successful calls. The list of StatusCode and Status are:

done = 0
API_RESPONSE_INVALID_REQUEST_DATA = 1
API_RESPONSE_INVALID_SERVICE_TAG_ID = 2
API_RESPONSE_INVALID_ORIGIN_IP = 3
API_RESPONSE_INVALID_ENCRYPTION = 4
API_RESPONSE_INVALID_SUBSCRIPTION = 5
API_RESPONSE_INVALID_OPERATION = 6
API_RESPONSE_INVALID_AUTHTOKEN = 7
API_RESPONSE_INVALID_OPERATION_TYPE = 8
API_RESPONSE_INVALID_START_TIME = 9
API_RESPONSE_INVALID_USERID = 10
API_RESPONSE_INVALID_API_CONFIGURATION = 11
API_RESPONSE_INVALID_API_REQUEST_INFO = 12
API_RESPONSE_INVALID_SECURITY_KEY = 13
API_RESPONSE_INVALID_OPERATION_DATA = 14
API_RESPONSE_INVALID_TEMPLATE = 15
API_RESPONSE_UNKNOWN_ERROR = 999

OperationData would be empty, unless there is any special response data is expected from CAMS in the immediate response.

Lazy Response of RESTful API

Your CallBack API shall be called whenever the response comes device as per your request (such as AddUser, DeleteUser, etc.)

Attendance API

An HTTP(port:80) URL should be exposed from your server and to be configured in API Monitor. Once the URL is configured, whenever a punch is registered in the device, the configured URL will be called automatically with realtime attendance information. Now your server can read and maintain the records in their database as per your business logic. If you are looking for a non-standard HTTP while testing your application, then you can use 8123 for a short while. If you like to configure HTTPS URL with its standard port, make sure that your SSL certificate doesn't force us to restart the server.

The attendance api (CallBack) url should be configured in api monitor to the specific device. When a new punch/attendance is received in the device, this url will be called with Operation: RealTimePunchLog.

While receiving attendance data following is OperationData:

{
	AttendanceType:,
	InputType:
	Temperature:
	FaceMask:
}

While receiving photo taken during attendance following is OperationData:

{
	AttendancePhotoe:,
}

ApiRequestInfo.Operation: This would be RealTimePunchLog ApiRequestInfo.OperationData.AttendanceType: Possible values are CheckIn, CheckOut, BreakOut, BreakIn, OverTimeIn, OverTimeOut, MealStart, MealEnd, None
ApiRequestInfo.OperationData.InputType:Punch is registred with one of following possible values Password, Card, Fingerprint, Face, Palm
ApiRequestInfo.OperationData.Temperature:The registered body, palm, and forehead temperature of the user
ApiRequestInfo.OperationData.FaceMask:Sends true if the user has worn the mask while registering attendance ApiRequestInfo.OperationData.AttendancePhoto:It is base64 jpg image.

Management API

Possible operations are :

ManuallyUserUpdated: CallBack URL will be called when user is added in the device manually. OperationData will be in the following structure
```
{
	Name:,
	FirstName:,
	LastName:,
	Priority:,
	Signature:[
		{
			Template:,
			Type:
			AdditionalData1: 
			AdditionalData2:
		}
	]
}
```
- ApiRequestInfo.OperationData.Name: User name registered in the device. FirstName and LastName to be considered only if your device supports.
- ApiRequestInfo.OperationData.Priority: 0 means registered user is a regular user, 16 means admin user
- ApiRequestInfo.OperationData.Signature:It is an array of objects. For every template one array item will be created. This object will point the templates of Fingerprint, Face, Palm, Card and Password. Every array element will have one template. In the array items, card and password can come together (in two array items). Rest of the templates (template of every finger, template of every face [A single face/palm may send you 5-20 templates with AdditionalData1 between 1 and 20]) will be coming in separate requests. Only when the type is either card or password, Name and Priority will be coming. For rest of the templates, Name and Priority will be empty. Hence don't read on other cases.
  - ApiRequestInfo.OperationData.Signature.Template: The would be the template value. You can use it when you want to add this user in another device.
  - ApiRequestInfo.OperationData.Signature.Type: Possible Types are:
    - Fingerprint
    - Face
    - Palm
    - Password
    - Card
    - TemplatePhoto - Base64 format of jpg image, normally the size is 300x300 pixel
    - UserPhoto - Base64 format of jpg image, normally the size is 300x300
  - ApiRequestInfo.OperationData.Signature.AdditionalData1: This can be template id of the finger, face,or palm. On other cases, it is empty
  - ApiRequestInfo.OperationData.Signature.AdditionalData2: Ignore this, reserved for future usage
AddUser: Call the RESTful API, with this operation to add the user in the device. Pass the OperationData which should be same as the one received in ManuallyUserUpdated operation, filling with UserId and Name. While adding user manaully, you would name and templates from different calls. It is suggested to merge all into single JSON object and pass while calling AddUser
DeleteUser: Call the RESTful API, with this operation to delete the user in the device. Pass empty string in OperationData
EnrollFingerprint: Call the RESTful API with this operation, to when you need to popup the enroll the fingerprint screen on the device. Pass empty string in OperationData
LoadPunchLog: Call the RESTful API with this operation, to load the attendance logs between given start and end time. OperationData structure as follows:
```
{
	StartTime:,
	EndTime:,
	OffSet:
}
```
StartTime: Time in EPOCH/unix format
EndTime: Time in EPOCH/unix format
OffSet: The maximum no. of rows returned in single response is 50. If the no. of records are more than 50, then a offset value will be return in the response. While requesting the next set of data, you need to pass this Offset in next call with the same start and end time.
The Response would be in
```
{
	StatusCode:,
	Status: done,
	OperationReferenceId: ,
	RequestedOperation: LoadPunchLog
	ReturnRowCount: 
	OperationData: {
		OffSet: ,
		ActualRowCount: ,
		Punch: [
			{
				AttendanceType: ,
				InputType: ,
				UserID: ,
				AttendanceTime: 
			},
			{
				AttendanceType: ,
				InputType: ,
				UserID: ,
				AttendanceTime: 
		},
	}
}
```
OperationData will have the array of attendance data object as described above

SendDeviceInfo: Call the RESTful API with this operation, to get the device information such as last connected time of the device, model of the device, active services and etc. OperationData structure as follows:
```
{
	SerialNumber:
	LastConnectedTime: 
	DeviceLabelName:
	Model:
	TimeZone: 
	Services[]
	{
		ServiceName:
		ActivationDate:
		ExpiryDate:
	}
}
```
SerialNumber: Serial Number of the device .
LastConnectedTime: will be in epoch/unix timestamp format.
DeviceLabelName: Device Name which is configured in API Monitor
Model: Model of the device
TimeZone: Time zone associated with the device. It will be like UTC+01:00
Services: List of the services associated with this device will be returned
Services.ServiceName: Possible values are AttendanceAPI, ManagementAPI, ScannerAPI, and CloudService
Services.ActivationDate: Service Activation Date in Epoch/Unix timestamp format
Services.ExpiryDate: Service Expiry Date in Epoch/Unix timestamp format
ClearLog: Call the RESTful API with this operation, to clear all the attendance log from the device. OperationData will be empty.
TriggerUserDetail: Call the RESTful API with this operation, to trigger the device to send all the user information through your configured callback url. OperationData will be empty. In the callback, the operation name would be ManuallyUserUpdated.
ClearLog: Call the RESTful API with this operation, to clear all the attendance log from the device. OperationData will be empty.
XLevel API

EnableMessage: Call the RESTful API, with this operation which displays a short message on the device when the given user punches in.
DisableMessage: Call the RESTful API, with this operation to disable the message which is enabled by EnableMessage

Sample Request and Response data

Sample data for all the operations are listed at http://developer.camsunit.com/cams-api-test-v2

Encryption

In the API Monitor login you can configure an AES-256 Encryption Key as a security key. If it is configured, all the data (request.ApiRequestInfo and response) gets transferred between the CAMS and your server will be encrypted by the configured Encryption Key. Whole request_data will/should not be encrypted as ServiceTagId is mandatorily visible to load the security key associated to the device.

Biometric Attendance SDK for Connecting to Web Application

Are you looking for fingerprint attendance system SDK?: Before answering, let us understand, what does SDK mean?. SDK means, a development tool or some set of programs that needed to perform a certain operations, and the code of the SDK will be part of the main application once the application is developed. For CAMS systems, SDK is not required, all the operations are executed by the CallBack URL and RESTful URLs. So, for integrating the biometric machine with your websites/web-application or any web based softwares/portals like OpenERP, ERPNext, HRAPP, Zoho, SAP, Tally and etc., what you need is, Just API!. But it can be claimed as online SDK for fingerprint attendance system or biometric attendance system, if you wish.

If you wish to avail SDK for developing windows based desktop application for interacting with the biometric device, then you can avail from us.

How does communication between machine and your web application happen?

CAMS Machines are tightly coupled with CAMS DataServer. Attendance information from machine will be updated to your server by passing through cams data server. Adding or removing users in the machine shall be triggered through APIs exposed by the data server and, the data server will communicate with the machine and sends the response back to your server

The punches recorded when the device was online, will be posted to your server by real time.

The punches recorded when the device was offline will be posted to your server one by one while device comes online. The order of the data shall be varying from device to device. So, the business logic should be built assuming the old punch data can come after new punch data

Want to receive data without coming through CAMS Dataserver?

Yes. We provide the windows lite version protocol engine which should be installed at your windows server. Once its installed, You web api endpoints will start getting triggered whenever attendance is registered at the device. The Activation cost and Yearly License cost are still applied as listed below. This case is also, applicable when the complete system is expected to run in the LAN network and there is no internet in the network. The Protocol engine costs 10,000 USD

Intranet Communication

If your complete systems are running on local computer which is not exposed to public ip/domain, then with the help of LoadPunchLog API you can load the attendance logs between given timeline. You only need to ensure that device is online

Web API supported Biometric machines

Various Web API supported biometric machines with Fingerprint support, Palm support, Face Recognition support, card support (LHF, UHF, QR Code) and password support are listed at http://camsunit.com/product/home.html

Cost of API and other services

If you are looking for receiving only attendance from the device to your server, you need to buy Attendance API Activation and its yearly license
If you are looking for receiving attendance from the device to your server, and managing the device from your website, then you need to buy Attendance and Management API Activation and its yearly license
If you are looking for enabling your own biometric device to attach with our API system, along with one of the API activation and Licenses, you need to buy Protocol Update

Service	INR	USD	Unit
Attendance API Activation and Setup	2500	70	Per Device
Yearly Attendance API License	1200	40	Per Device/Year
Management & Attendance API Activation and Setup	4500	90	Per Device
Yearly Management & Attendance API License	2000	45	Per Device/Year
Protocol Update for non-CAMS devices You will have to make sure your device is verified with http://developer.camsunit.com	4500	80	Per Device
Zoho Integration Watch video for this feature How to do the Zoho Attendance Integration With Biometric Attendance System Attendance API has to be purchased	6500	120	Per Device

For R20x series devices such as R20v5, R20p8, R20m2, R20b5 and R20b7:

Service	INR	USD	Unit
Attendance API Activation and Setup	4000	100	Per Device
Yearly Attendance API License	2000	60	Per Device/Year
Management & Attendance API Activation and Setup	6000	150	Per Device
Yearly Management & Attendance API License	2500	80	Per Device/Year
Protocol Update for non-CAMS devices such as SpeedFace V5L [TD]	6000-15000	100-275	Per Device

Biometric Web API FAQs

If you need a solution to any one of the following problems or questions, then you are at the right place and mail us as soon as to get the your solution implemented:

Can we use your Web API for integrating our ZkTeco Biometric devices with our own web application/server?
Answer: Yes, you can. We support biometric devices from ZkTeco, eSSL, BioMax, RealTime, Suprema, Mantra and more. You must ensure that devices are tested and got verified message at CAMS API BOT. Many of the companies are partnered with us for their API support.
How to integrate biometric attendance system with our web site?
Answer: Please refer this biometric web api documentation page from the beginning.
Can i integrate biometric face recognition attendance report with my PHP online application?
Answer: Please refer this biometric web api documentation page from the beginning.
How do i integrate fingerprint attendance system reports with my mobile app?
Answer: With the help of our Web API, this can be done.
Is there any API available to integrate our access control system with our HRM portal?
Answer: Yes, Please refer this biometric web api documentation page from the beginning.
I like to integrate the biometric fingerprint attendance with school ERP software, can i do?
Answer: Please provide an URL from your ERP as per the specification mentioned this page. We will map at our pass through server which will call back your URL for every attendance received from the machine.
What is the best Biometric machines available in the market with WebAPI support?
Answer: CAMS attendance machines are the best machines as they support offline SDK, online API, Cloud system and mobile App
We have my C# and ASP .Net web based application. Can we integrate our fingerprint attendance and access control system with our web applications?
Answer: Please refer this biometric web api documentation page from the beginning.
Is there any web based face-recognition or fingerprint attendance system available?
Answer: Please check our product page where you would get the list of face recognition machines that supports web based reporting system and API system
How do i store the fingerprint biometric attendance system report into my database directly?
Answer: With the help of Web API you can achieve this. For API details, please refer this biometric web api documentation page from the beginning.
How can i pull the attendance report from machine to my server automatically?
Answer: Instead of pulling the attendance record, CAMS offers the posting the attendance records to your server on real time based. You have to follow the Web API implementation. Please refer this biometric web api documentation page from the beginning.
Is it possible to integrate the biometric attendance system with my Linux server?
Answer: Yes. You can do it very well. Implement a server application and host in your Linux server and makes sure the application has exposed an URL as per our Web API specification. Now rest will be done by CAMS.
Can we read the biometric system report to my web application without any intermediate software?
Answer: With the help of our Web API, this can be done.
How to get data from biometric device
Answer: Please refer this API speficiation page from the beginning which address your question.
How to implement the Web Based Biometric attendance system
Answer: With the help of our Web API, you can develop your own web application and attache the CAMS biometric machines with that application.
Looking for SDK for integrating the biometric attendance machines with my own web application of HRM or CRM?
Answer: Please refer this biometric web api documentation page from the beginning.
Can I integrated the Biometric Attendance with Odoo / OpenERP directly?
Answer: Please refer this biometric web api documentation page from the beginning.
How can i integrate the Biometric Attendance with ERPNext or Zoho?
Answer: Please refer this biometric web api documentation page from the beginning.
I have my GYM software, Can i block user, in the biometric access control system, from entering into the door, if the user's subscription is expired?
Answer: With the help of our Management API, you can handle your use cases
How can i integrate the student's attendance in the school van using ID card or fingerprint?
Answer: Fix the CAMS biometric or Card machines that are supported by GPRS, in the vehicle. Now integrate our Web API with your attendance system. Now your system will have the real time attendance data. Please refer this biometric web api documentation page from the beginning for API integration details.
Does it provide the Time Clock API on real time basis?
Answer: Yes. It provides. Please refer this biometric web api documentation page from the beginning.
Will the renewal cost remain same for life long, once a service is purchased?
Answer:No, While renewing the service, listed license cost at the time of renewal will be applied
Can i leave the licence without renew?
Answer: Expired license, will not allow to access the respective services. Expired services can not be renewed. It has to be activated again to avail the services
Is it possible, if we get the same data again to our server?
Answer: Yes. It is possible. Based on the machine's capability, same data may come again. So you need to make sure to ignore if the same data from same device is coming.

How To Integrate Biometric Attendance Device with your Own Server - Demo with PHP program

PHP Program to receive the real-time biometric attendance data

Download the sample PHP file from Download Here! to connect with the biometric machine. If you want to test? or if you want to know how to connect the CAMS biometric or fingerprint attendance machine with your website?, just place this downloaded file at you server and configure the URL at API monitor

Now whenever an attendance is registered in the machine, you can see cams-attendance-record.txt gets generated in the same location where you have placed the PHP file, and the same file will be updated with real time attendance data. Now you can update this code to store in your own DB. You need to make sure that your machine is connected to the online for receiving real-time attendance. Following is the code snippet for your quick reference

	$request_data= $_POST["request_data"];

	$Operation = json_decode($request_data)->ApiRequestInfo->Operation;

	if ($Operation == 'RealTimePunchLog' )
	{
		handle_attendance_log($request_data);
	}

function handle_attendance_log($request_data)
{
	// Sample request_data
	// {
	//   "ApiRequestInfo": {
	//     "AuthToken": "k3wgUszWcH4EjXM7sUWI38yJPkXhmvao",
	//     "Operation": "RealTimePunchLog",
	//     "OperationData": {
	//       "AttendanceType": "CheckIn",
	//       "InputType": "Card"
	//     },
	//     "OperationReferenceId": "",
	//     "OperationTime": "1556637142",
	//     "UserId": "852"
	//   },
	//   "ServiceTagId": "ST-KY19123123"
	// }

	$request = new StdClass();
	$request->ServiceTagId="";
	$request->ApiRequestInfo = new StdClass();
	$request->ApiRequestInfo->AuthToken="";
	$request->ApiRequestInfo->Operation="";
	$request->ApiRequestInfo->UserId="";
	$request->ApiRequestInfo->OperationTime="";
	$request->ApiRequestInfo->OperationReferenceId="";
	$request->ApiRequestInfo->OperationData= new StdClass();
	$request->ApiRequestInfo->OperationData->AttendanceType="";
	$request->ApiRequestInfo->OperationData->InputType="";

	$request = json_decode($request_data);

	$content = 'ServiceTagId:' . $request->ServiceTagId . ",\t";
	$content = $content . 'Operation:' . $request->ApiRequestInfo->Operation . ",\t";
	$content = $content . 'AuthToken:' . $request->ApiRequestInfo->AuthToken . ",\t";
	$content = $content . 'UserId:' . $request->ApiRequestInfo->UserId . ",\t";
	$content = $content . 'AttendanceTime:' . date("Y-m-d H:i:s", $request->ApiRequestInfo->OperationTime) . ",\t";
	$content = $content . 'AttendanceType:' . $request->ApiRequestInfo->OperationData->AttendanceType . ",\t";
	$content = $content . 'InputType:' . $request->ApiRequestInfo->OperationData->InputType . "\n";

	$file = fopen("cams-attendance-record.txt","a");
	fwrite($file, $content);
	fclose($file);
}

Contact Us

Write sales@camsunit.com for availing the APIs support for CAMS Machines or WhatsApp to +91-98-409-81006 for technical queries.