FAQ, SDK and cost
Common questions from integrators, plus how the SDK and API pricing work.
Additional Information
Frequently Asked Questions
Common questions about integrating with the Cams Biometrics Web API 3.0.
General
Q: What is the Cams Biometric Gateway and its Biometric API?
The Cams Biometric Gateway is a universal cloud platform that exposes a Biometric API enabling any web application to communicate with biometric attendance and access control devices in real time. It supports 38 operations across Callback (inbound) and RESTful (outbound) APIs — without requiring any device SDK or static IP.
The Cams Biometric Gateway is a universal cloud platform that exposes a Biometric API enabling any web application to communicate with biometric attendance and access control devices in real time. It supports 38 operations across Callback (inbound) and RESTful (outbound) APIs — without requiring any device SDK or static IP.
Q: Do I need an SDK to integrate?
No. Cams does not provide or require an SDK. All communication uses standard HTTP/HTTPS POST requests with JSON payloads. Any language that can make HTTP calls will work.
No. Cams does not provide or require an SDK. All communication uses standard HTTP/HTTPS POST requests with JSON payloads. Any language that can make HTTP calls will work.
Q: Which programming languages are supported?
Any language that can send/receive HTTP POST with JSON — PHP, Python, Java, C#, Node.js, Go, Ruby, and more. We provide AI code generator prompts for 7 languages.
Any language that can send/receive HTTP POST with JSON — PHP, Python, Java, C#, Node.js, Go, Ruby, and more. We provide AI code generator prompts for 7 languages.
Q: What is the Cams Protocol Engine?
It is the cloud middleware that sits between biometric devices and your server. It handles protocol translation, data normalization, offline caching, and delivers a consistent JSON API regardless of the underlying device brand or model.
It is the cloud middleware that sits between biometric devices and your server. It handles protocol translation, data normalization, offline caching, and delivers a consistent JSON API regardless of the underlying device brand or model.
Q: What is the API Monitor?
The API Monitor is your admin portal where you configure Callback URLs, manage AuthTokens, set Security Keys, view device status, and access your RESTful endpoint URL and Service Tag IDs.
The API Monitor is your admin portal where you configure Callback URLs, manage AuthTokens, set Security Keys, view device status, and access your RESTful endpoint URL and Service Tag IDs.
Device Compatibility
Q: Which biometric devices are supported?
All Cams Biometrics machines (listed at camsbiometrics.com/product) support the full API with Native Push. Devices verified at developer.camsbiometrics.com also have full Native Push support.
All Cams Biometrics machines (listed at camsbiometrics.com/product) support the full API with Native Push. Devices verified at developer.camsbiometrics.com also have full Native Push support.
Q: Can non-Cams devices (ZkTeco, eSSL, BioMax, etc.) use this API?
Yes, with a Protocol Update. Non-Cams and non-verified devices operate via Hybrid Push. Some features may be limited depending on the connection mode and hardware capabilities.
Yes, with a Protocol Update. Non-Cams and non-verified devices operate via Hybrid Push. Some features may be limited depending on the connection mode and hardware capabilities.
Q: What is the difference between Native Push and Hybrid Push?
Native Push: Full API support with no limitations — all 38 operations work. Available for Cams machines and verified devices.
Hybrid Push: For non-Cams/non-verified devices. Feature availability depends on the communication mode (SDK, DB Pull, or File Processing). See Connection Modes.
Native Push: Full API support with no limitations — all 38 operations work. Available for Cams machines and verified devices.
Hybrid Push: For non-Cams/non-verified devices. Feature availability depends on the communication mode (SDK, DB Pull, or File Processing). See Connection Modes.
Q: What biometric methods are supported?
Fingerprint, facial recognition, palm vein, RFID/proximity card, numeric PIN/password, iris scanning, and body temperature measurement (device-dependent).
Fingerprint, facial recognition, palm vein, RFID/proximity card, numeric PIN/password, iris scanning, and body temperature measurement (device-dependent).
Q: Some API features don't work with my device. Why?
This depends on (a) the connection mode — DB Pull and File Processing modes only support attendance push, not RESTful APIs, and (b) hardware limitations — some device models may not support specific features at the firmware level. Test with your hardware and contact Cams support for assistance.
This depends on (a) the connection mode — DB Pull and File Processing modes only support attendance push, not RESTful APIs, and (b) hardware limitations — some device models may not support specific features at the firmware level. Test with your hardware and contact Cams support for assistance.
Callback API (Device → Server)
Q: What is the Callback API?
The Callback API delivers real-time events from biometric devices to your server. When a punch occurs or a user is modified on the device, the Cams Protocol Engine immediately POSTs a JSON payload to your configured Callback URL.
The Callback API delivers real-time events from biometric devices to your server. When a punch occurs or a user is modified on the device, the Cams Protocol Engine immediately POSTs a JSON payload to your configured Callback URL.
Q: What must my server respond with?
Always return
Always return
{"status":"done"} with HTTP status 200 — even if your internal processing fails. Never block the Cams Protocol Engine. Queue heavy processing for async execution.Q: What happens if my server is offline when a punch occurs?
The Biometric Gateway caches all events and delivers them automatically once your server is back online. No data is lost.
The Biometric Gateway caches all events and delivers them automatically once your server is back online. No data is lost.
Q: How do I handle duplicate punches?
Implement duplicate-detection logic on your server using the combination of
Implement duplicate-detection logic on your server using the combination of
UserID + LogTime. The same punch may be re-sent during offline recovery or network retries.Q: What punch types are supported?
CheckIn, CheckOut, BreakOut, BreakIn, OverTimeIn, OverTimeOut, MealIn, MealOut. The InputType field shows the biometric method used: Fingerprint, Face, Palm, Card, or Password.Q: How do user templates work in Callbacks?
When a user is updated on the device (operations #3–#9), templates may arrive one at a time or in groups across multiple callbacks. Each callback only carries templates that changed — not the full set. Your server must merge/upsert by
When a user is updated on the device (operations #3–#9), templates may arrive one at a time or in groups across multiple callbacks. Each callback only carries templates that changed — not the full set. Your server must merge/upsert by
Type + Index as the unique key. Never overwrite all templates on a single callback.Q: Can I receive attendance photos?
Yes. Operation #10 RealTimeAttendancePhoto delivers a Base64-encoded JPEG snapshot captured at punch time. This is separate from the punch log callback (#11) and available on devices with camera support.
Yes. Operation #10 RealTimeAttendancePhoto delivers a Base64-encoded JPEG snapshot captured at punch time. This is separate from the punch log callback (#11) and available on devices with camera support.
Q: Does the Callback include temperature and mask detection?
Yes, if the device supports it. The
Yes, if the device supports it. The
PunchLog object includes Temperature (body temperature reading) and FaceMask (boolean — whether a face mask was detected).RESTful API (Server → Device)
Q: What is the RESTful API?
The RESTful API lets your server send commands to biometric devices — adding/deleting users, loading logs, enrolling biometrics, and controlling access. You POST JSON to the endpoint URL found in your API Monitor account.
The RESTful API lets your server send commands to biometric devices — adding/deleting users, loading logs, enrolling biometrics, and controlling access. You POST JSON to the endpoint URL found in your API Monitor account.
Q: Where do I find my RESTful endpoint URL?
Log in to your API Monitor account. Your RESTful endpoint URL and Service Tag IDs (
Log in to your API Monitor account. Your RESTful endpoint URL and Service Tag IDs (
stgid) are listed there.Q: What is the latency for RESTful commands?
Approximately 15 seconds. The Biometric Gateway queues your command and delivers it to the device when it next connects (which is near-continuous for online devices).
Approximately 15 seconds. The Biometric Gateway queues your command and delivers it to the device when it next connects (which is near-continuous for online devices).
Q: What is the maximum date range for LoadLog?
Recommended max is 30 days per request. For larger ranges, make multiple requests with consecutive time windows.
Recommended max is 30 days per request. For larger ranges, make multiple requests with consecutive time windows.
Q: Can I add a user with multiple biometric templates at once?
Yes. The Template array accepts multiple entries. For example, operation #27 adds a user with Card + Fingerprint + Password + Face + Palm + UserPhoto all in one request.
Yes. The Template array accepts multiple entries. For example, operation #27 adds a user with Card + Fingerprint + Password + Face + Palm + UserPhoto all in one request.
Q: What happens if the device is offline when I send a RESTful command?
The Biometric Gateway queues the command and delivers it automatically when the device reconnects. You'll receive status code
The Biometric Gateway queues the command and delivers it automatically when the device reconnects. You'll receive status code
5 (Device Offline) if the device doesn't respond within the timeout window.Q: How do I check the command result?
RESTful responses include a
RESTful responses include a
StatusCode field. Code 0 means success. See Response Status Codes for the full list of error codes and their meanings.Q: Can I trigger fingerprint enrollment remotely?
Yes. Operation #35 EnrollFingerPrint triggers an on-device enrollment session. However, the user must be physically present at the device to scan their finger.
Yes. Operation #35 EnrollFingerPrint triggers an on-device enrollment session. However, the user must be physically present at the device to scan their finger.
Security & Networking
Q: Can I use HTTPS for callbacks?
Yes. HTTPS with a valid SSL certificate on port 443 is fully supported and recommended for production.
Yes. HTTPS with a valid SSL certificate on port 443 is fully supported and recommended for production.
Q: Is encryption mandatory?
No. AES-256 encryption is optional. To enable it, configure a Security Key in the API Monitor. When enabled, all JSON payloads are encrypted/decrypted using AES/ECB/PKCS5PADDING with Base64 encoding.
No. AES-256 encryption is optional. To enable it, configure a Security Key in the API Monitor. When enabled, all JSON payloads are encrypted/decrypted using AES/ECB/PKCS5PADDING with Base64 encoding.
Q: How do I validate that a callback is genuinely from Cams?
Every callback includes an
Every callback includes an
AuthToken field. Compare it against the token configured in your API Monitor. Reject any request with a mismatched token.Q: Which ports should I open?
Port
Port
80 (HTTP) or 443 (HTTPS) for production. Port 8123 is available for testing only. See Ports Supported.Q: How do I test locally without deploying to a server?
Use a public IP with port forwarding, or a tunneling tool like ngrok. See Testing Locally for a step-by-step guide.
Use a public IP with port forwarding, or a tunneling tool like ngrok. See Testing Locally for a step-by-step guide.
Data & Design Considerations
Q: What data format does the API use?
All requests and responses are raw JSON with UTF-8 encoding. Use
All requests and responses are raw JSON with UTF-8 encoding. Use
Content-Type: application/json header. No form encoding.Q: What timestamp format is used?
YYYY-MM-DD HH:mm:ss GMT +OFFSET (e.g., 2020-09-17 07:48:22 GMT +0530). The Time field is in UTC; device-local timestamps (like LogTime, OperationTime) may use a different timezone offset.Q: How should I handle offline punches and retroactive data?
Design your application to accept punches that arrive out of chronological order. When a device was offline, it will push cached punches once reconnected. You may need to retroactively update attendance status (e.g., mark a user who was shown as "absent" to "present").
Design your application to accept punches that arrive out of chronological order. When a device was offline, it will push cached punches once reconnected. You may need to retroactively update attendance status (e.g., mark a user who was shown as "absent" to "present").
Q: How do I determine IN/OUT when a user has multiple devices?
Sort all punches for a user by
Sort all punches for a user by
LogTime across all devices, then apply your business logic. Do not rely solely on the Type field (CheckIn/CheckOut) from a single device if the user punches on different machines.Q: What is the OperationID and how should I use it?
A unique string identifier for each operation. For inbound callbacks, it's generated by the Biometric Gateway. For outbound RESTful requests, you should generate a unique one per request (UUID or timestamp-based). The response echoes it back so you can correlate request/response pairs.
A unique string identifier for each operation. For inbound callbacks, it's generated by the Biometric Gateway. For outbound RESTful requests, you should generate a unique one per request (UUID or timestamp-based). The response echoes it back so you can correlate request/response pairs.
Q: How are biometric templates stored and transmitted?
Biometric data (fingerprint, face, palm, user photo) is Base64-encoded in the
Biometric data (fingerprint, face, palm, user photo) is Base64-encoded in the
Data field of the Template object. Fingerprint and face templates also include Size (byte length) and Index (slot number). Card numbers and PINs are plain strings.Pricing & Licensing
Q: How is the API licensed?
Per biometric machine. First year requires API Activation + Yearly License. Subsequent years require only the yearly license renewal. See Cost of API for pricing.
Per biometric machine. First year requires API Activation + Yearly License. Subsequent years require only the yearly license renewal. See Cost of API for pricing.
Q: What happens if my API license expires?
API communication for that device stops until the license is renewed. Your existing data is not affected, but no new callbacks or RESTful commands will be processed.
API communication for that device stops until the license is renewed. Your existing data is not affected, but no new callbacks or RESTful commands will be processed.
Q: Is there an on-premise option?
Yes. The Protocol Engine Lite can be installed on your own server (Windows/Linux) for LAN-only or self-hosted environments. Contact sales@camsbiometrics.com for details.
Yes. The Protocol Engine Lite can be installed on your own server (Windows/Linux) for LAN-only or self-hosted environments. Contact sales@camsbiometrics.com for details.
Additional Information
Biometric Attendance SDK
Cams does not provide a traditional SDK. All operations use standard HTTP Callback and RESTful APIs — no library installation needed.
No SDK needed. Communication is handled entirely through the Cams Protocol Engine using Callback URLs and RESTful HTTP endpoints.
This makes integration straightforward with any web platform:
OpenERPERPNextZoho PeopleSAPTallyHRAPPOdooCustom Web Apps
Additional Information
Cost of API
API licenses are billed per biometric machine. First-year = activation + license; subsequent years = license renewal only.
| Service | USD | Notes |
|---|---|---|
| Native Push — Cams & Verified Devices | ||
| API Activation | $120 | One-time per machine. |
| Yearly API License | $60 – $120 | Annual renewal required. |
| Protocol Update (non-Cams) | $120 – $280 | One-time. Enables Cams protocol on non-Cams devices. |
| Hybrid Push — ZKTeco, eSSL & All Third-Party Brands | ||
| API Activation | $150 | One-time per machine. |
| Yearly API License | $90 – $150 | Annual renewal required. |
| Hybrid Connector (non-verified) | $150 – $300 | One-time. Required for non-verified devices using Hybrid Push. |
| Hardware & Other | ||
| Hardware | $220 – $720 | Varies by model. |
Protocol Engine Lite (on-premise) — For LAN-only or self-hosted environments. Cost: $500–$10,000. Contact sales for details.