Biometric Web API 3.0 (BioAPI 3.0)
CAMS is the pioneer and global leader in Biometric Research and Development. It supports the Biometric Web API 3.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 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
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
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.
Biometric API
CAMS offers two set of APIs as described below.
- Attendance API : Gives you the realtime biometric attendance data to your server, through your server URL (CallBack API)
- Management API: Helps to manage the user in the device through CAMS's RESTful URL and receives the user information from the device through your CallBack API
There are two parameters to be passed in every request. One with POST PARAM, one as stream data.
- stgid: Service tag id of the device should be passed in query string with parameter name stgid
- The parameter would be sent as raw/stream data where no parameter name is required to pass data.
Request Data Format
This is the format of the data that all the request would follow.{ "{CommandName}": { "CommandFor": {OperationData} }, "OperationID": "", "AuthToken": "", "Time": "" }
- CommandName: This says request is for which operation. The Possible Operations are: RealTime, Add, Delete, Load, Resend and more
- CommandFor: This says that the above CommandName is for what. The possible values are: User, Template, Photo and more
- OpeartionData: The actual data for performing the request command/operation. This data structure would varry based on the CommanName and CommandFor
- 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
- OperationID: Unique alpha number id sent along with every API call. Length varries from 10-15
- Time: Operation requested time in "YYYY-MM-DD HH:mm:SS GMT +TZ" format. Eg: 2020-09-17 11:09:09 GMT +0530.
Response: Following is the expected response from your server to be returned for all the request you receive from CAMS. Even if there is any business/data validation faliure at your end, you must return the following response. Otherwise, same request will be coming to your server again and again till return the expected response.
{ status: "done" }
Attendance API
Command | Data Structure | Description |
---|---|---|
Receive Real Time Attendance |
{ "RealTime": { "OperationID": "", "PunchLog": { "UserId": "", "LogTime": , "Type": "", "InputType": "", "Temperature": "", "FaceMask": false, }, "AuthToken": "", "Time": "" } }Sample data |
UserID: Employee id or user id of the user.
LogTime: Attendance time in "YYYY-MM-DD HH:mm:SS GMT +TZ" format. Eg: 2020-09-17 11:09:09 GMT +0530 Type: CheckOut, CheckIn, BreakOut, BreakIn, OverTimeIn, OverTimeOut, MealIn, MealOut InputeType: Indicates what input was used for recording the attendance. Values are: Fingerprint, Face, Password, Card, Palm, FingerVein, Iris, Retina and Palm Temperature: Temperature data of the user as mesaured during the attendance/punch FaceMask: Says if the user has worn mask or not while his/her face was detected Temperature and FaceMask will come based on the hardware capability. If hardware doesn't support, then these fields may not appear in the json object. |
Management API
Command | Data Structure | Description |
---|---|---|
Add User |
{ "Add": { "User": { "UserID": "", "FirstName": "", "LastName": "", "UserType": "" } }, "OperationID": "", "AuthToken": "", "Time": "" }Sample data |
UserID: Employee id or user id of the user.
FirstName: Self-explanatory LastName: Self-explanatory UserType: Values: User, Administrator |
Add user with Template(s) |
{ "Add": { "User": { "UserID": "", "FirstName": "", "LastName": "", "UserType": "" }, "Template": [ { "Type": "", "UserID": "", "Data": "" }, { "Type": "", "UserID": "", "Data": "", "Size":"", "Index": "" } ] }, "OperationID": "", "AuthToken": "", "Time": "" }Sample data |
Every template should be in array of a struture, even if there is only one template is being passed.
Type: Values are: Fingerprint, Palm, Face, Card, Password, Fingervein, Iris, Retina UserId: user id whom the template belongs to Data: Template data Size: Size of the template Index: Index of fingerprint/face. Keep it zero, if not sure about the index value |
Add User Photo |
{ "Add": { "Photo": { "Type": "", "UserID": "", "Size": "", "Data": "" } }, "OperationID": "", "AuthToken": "", "Time": "" }Sample data |
Type: Supported value is Base64 Data: png/jpeg photo content in Base64 format |
Manually user added in the device |
{ "RealTime": { "UserUpdated": { "UserID": "", "FirstName": "", "LastName": "", "UserType": "", "OperationTime": "", "Template": [] }, "OperationID": "", "AuthToken": "", "Time": "" } }Sample data |
This data would be posted to your server when user is added/updated with name, password and card in single step. Template[]: Array of template information of Card and/or Password. |
Manually template added/updated in the device |
{ "RealTime": { "UserUpdated": { "OperationTime": "", "Template": [ { "Type": "", "UserID": "", "Size": "", "Index": "0", "Data": "" } ] }, "OperationID": "", "AuthToken": "", "Time": "" } }Sample data |
Not all the templated be posted as a single object. You will have to take care of integrating them into single object and store in your database. Face may have 10-15 templates. So your call back url shall be posted 10-15 times for every single face registered. Similarly for every fingerprint,card, password, palm will have each one service call. The size of the templates may varry from 1k to 20k |
Delete User |
{ "Delete": { "User": { "UserID": "", } }, "OperationID": "", "AuthToken": "", "Time": "" }Sample data |
UserID: user id to delete in the biometric device |
Delete All Users |
{ "Delete": { "User": "All" }, "OperationID": "", "AuthToken": "", "Time": "" }Sample data |
Delete all the users registered in the biometric device |
Load Punchlog |
{ "Load": { "PunchLog": { "Filter": { "StartTime": "", "EndTime": "", "OffSet": "0" } } } }Sample data |
Load all the punch logs between given date. Offset should by default zero. If the resultset is more than 50, then you will get only 50 records and a offset value. Call the same api with received offset to get the next set of 50 data. StartTime and EndTime formate is YYYY-MM-DD HH:mm:SS GMT TZ, ex: 2020-09-17 16:55:15 GMT +0530. You can get only from last 30 days of data. So, you should have pulled the data and stored in your server prior to the expiry time. |
Response of RESTful API
Following will be the response of your RESTful calls.
{ "Status": "done", "OperationID": "", "StatusCode": }Status will be done and StatusCode will be 0 for successful calls. The list of possible StatusCodes 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_SECURITY_KEY = 13
- API_RESPONSE_INVALID_TEMPLATE = 15
- API_RESPONSE_UNKNOWN_ERROR = 999
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.)Ports supported
Your call back url should be bound with port: 80. 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.
Sample Biometric API Request and Response
Sample data for all the operations are listed at https://camsunit.com/application/biometric-web-api-sample-request-response.html
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 lite version protocol engine which should be installed at your server (windows/linux/unix). Once its installed, Your 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, where/for the complete system is expected to run in the LAN network and there is no internet in the network.
List of Protocol Engines
- If you are using Cams RSP1x series devices or Cams R2x series devices then you have to buy 1x/2x protocol Engine
- If you are using 3rd party biometric devices such ash ZkTeco, eSSL, BioMax, Identix and etc , then you have to buy ZkTeco API Engine
- If you are using Cams 3x series devices then you have to buy 3x protocol Engine
Non-Server web application
If your complete systems are running on local computer which is not exposed to public ip/domain, then with the help of LoadLog 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 https://camsunit.com/product/home.html
Cost of API
-
What you need to buy:
- 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 | 3000 | 70 | Per Device |
Yearly Attendance API License | 1700 | 40 | Per Device/Year |
Management & Attendance API Activation | 4500 | 90 | Per Device |
Yearly Management & Attendance API License | 2200 | 45 | Per Device/Year |
Protocol Update for non-CAMS (eSSL, ZkTeco, BioMax, Identix and etc) devices You will have to make sure your device is verified with https://developer.camsunit.com. For more information refer here |
4500 | 80 | Per Device |
Protocol Update for non-CAMS devices with visible light version suchs as SpeedFaceV5, FaceDepot 8AL, Airface-Uranus and etc. The device can be veirifed manually with our technical team, to confirm if we can support the API. | >=7500 | >=120 | 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 the BioAPI for the biometric devices from ZkTeco, eSSL, BioMax, RealTime, 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
PS: The video gives the idea about how to integrate the biometric device. For the typical data format of request and respone, please follow this documentationPHP 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
$rawdata = file_get_contents("php://input"); $stgid= $_GET["stgid"]; // We capture all the incoming data from CAMS into file: cams-attendance-record.txt. // If you need to maintain it in your own database, you need to impletement the same here. $raw = json_decode($rawdata); $ret = "done"; $data = json_decode($rawdata, true); if( isset( $data["RealTime"] )) { $ret = handle_attendance_log($stgid, $rawdata); } else $ret = "Else"; $response = new StdClass(); $response->status="done"; header("Content-Type: application/text;charset=utf-8"); http_response_code(200); echo json_encode($response); function handle_attendance_log($request_data) { $ret = "done"; // Sample rawdata // { // "RealTime": { // "OperationID": "123123123", // "PunchLog": { // "Type": "CheckOut", // "Temperature": "36.8", // "FaceMask": false, // "InputType": "Fingerprint", // "UserId": "2", // "LogTime": "2020-09-17 07:48:22 GMT +0530" // }, // "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs", // "Time": "2020-09-17 04:19:03 GMT +0000" // } // } $request = new StdClass(); $request->RealTime = new StdClass(); $request->RealTime->AuthToken=""; $request->RealTime->Time=""; $request->RealTime->OperationID=""; $request->RealTime->PunchLog = new StdClass(); $request->RealTime->PunchLog->UserId=""; $request->RealTime->PunchLog->LogTime=""; $request->RealTime->PunchLog->Temperature=""; $request->RealTime->PunchLog->FaceMask=""; $request->RealTime->PunchLog->InputType=""; $request->RealTime->PunchLog->Type= ""; $request = json_decode($rawdata); $content = 'ServiceTagId:' . $stgid . ",\t"; $content = $content . 'UserId:' . $request->RealTime->PunchLog->UserId . ",\t"; $content = $content . 'AttendanceTime:' . $request->RealTime->PunchLog->LogTime . ",\t"; $content = $content . 'AttendanceType:' . $request->RealTime->PunchLog->Type . ",\t"; $content = $content . 'InputType:' . $request->RealTime->PunchLog->InputType . ",\t"; $content = $content . 'Operation: RealTime->PunchLog' . ",\t"; $content = $content . 'AuthToken:' . $request->RealTime->AuthToken . "\n"; $file = fopen("cams-attendance-record.txt","a"); fwrite($file, $content); }
URL Testing
Ensure that your URL is tested at our URL Test Tool or ensure that your URL is tested using any 3rd part tool and response is returned as expected. Following is the screenshot taken from Postman for your reference.
Contact Us
Write sales@camsunit.com for availing the APIs support for CAMS Machines or WhatsApp to +91-98-409-81006 for technical queries.