Introduction

Cams Biometric Gateway — Web API 3.0

The Cams Biometric Gateway is the universal Biometric API that connects any biometric attendance or access control machine with your application — ERP, HRMS, payroll, school management, custom software, or AI/automation workflow. It supports all major device brands and provides a standardised JSON-over-HTTP Biometric API regardless of the hardware.

38 Operations — 11 Callback APIs (Device → Server) and 27 RESTful APIs (Server → Device). All payloads are raw JSON over HTTP/HTTPS.

All biometric machines are supported. Cams machines, verified devices, and third-party brands (ZKTeco, Suprema, Hikvision, Anviz, Morpho/IDEMIA, Virdi, Mantra, Nitgen, Realtime/Startek, Biomax, Secugen, eSSL, Matrix COSEC, and more). Choose the connection mode suitable for your setup.

How It Works

The Biometric Gateway consists of:

Gateway ServerCloud-hosted platform that includes the Cams Protocol Engine (protocol translation, data normalization, offline caching, authentication) and the Standardised API layer that delivers a consistent interface to your application.

Protocol EngineThe core engine within the Gateway Server that communicates with biometric devices, translates vendor-specific protocols, and handles secure data transaction logging and identity management.

Protocol Engine LiteAn on-premise version installable on your own server (Windows/Linux) for LAN-only or self-hosted environments. Same API, deployed locally.

Integrates With

OdooERPNextSAPMicrosoft Dynamics ZohoBitrix24 OrangeHRMBayZatPalmHRuKnowva FedenaTeachmintEduBricz RazorPayPayruler n8nMakeZapier Claude (MCP)GeminiChatGPT Custom Web Apps

Your Application

ERP HRMS Payroll School ERP AI Workflow (n8n, Zapier) MCP — Claude · Gemini · ChatGPT Custom Apps

↑ Callback API Gateway → Your Server (Push)

↓ RESTful API Your Server → Gateway (Command)

Biometric Gateway

Protocol Engine

Secure Auth Processing Data Transaction Logging Protocol Translation Offline Cache & Queue AES-256 Encryption · Auth Token Validation

Standardised API Layer

Identity Management AI / MCP Integration Callback Dispatcher REST Command Router Data Normalization · Multi-brand Protocol Support

Internet

Fingerprint · Face Recognition · Palm Vein · RFID Card · PIN · QR / Barcode · GPS Tracking

Biometric Devices — All Brands Supported

Cams ZKTeco Suprema Hikvision Anviz Morpho / IDEMIA Virdi Mantra Nitgen Realtime Biomax Secugen eSSL Matrix + Many More

API Type	Direction	Latency	Use Case
Callback API	Device → Your Server	Real-time / zero latency	Receive attendance punches, user sync events
RESTful API	Your Server → Device	~15 seconds	Add/delete users, load logs, enroll biometrics

Introduction

Getting Started

Integrate in three steps. Your server needs a publicly reachable URL to receive callbacks.

Configure your Callback URL

Log in to the API Monitor portal. Set your server's public HTTPS URL as the Callback URL for your device(s). The API engine will POST biometric events to this endpoint in real time.

Receive attendance punches

Your endpoint receives a POST with a raw JSON body — no query parameters needed for Callback APIs. Validate the AuthToken, parse the punch data, and respond with {"status":"done"}.

Call RESTful APIs to manage users & devices

POST a JSON command to the RESTful endpoint URL provided in your API Monitor account, with your stgid (Service Tag ID) as a query parameter. The engine queues the command and the device acknowledges within ~15 seconds.

Endpoint Format

API Type	Method	How to send
Callback API (inbound)	POST	Device posts to your configured URL. Raw JSON body; no parameters.
RESTful API (outbound)	POST	You POST to the RESTful endpoint URL (found in your API Monitor account) with `?stgid=YOUR_SERVICE_TAG_ID` and raw JSON body.

Always respond to Callback requests immediately. Your server must return {"status":"done"} (HTTP 200) to acknowledge receipt. Do not perform heavy processing before responding — queue it.

Introduction

Machine Compatibility

The Cams Biometric Gateway supports all biometric attendance and access control machines. The only decision you make is which connection mode suits your setup.

Native Push

Cams Machines

All machines at camsbiometrics.com/product. Full API — all 38 operations, no setup required.

Native Push

Verified Devices

Devices verified at developer.camsbiometrics.com. Full API — all 38 operations.

Hybrid Push

All Other Brands

Any other machine works via Hybrid Push. You choose the connection mode that suits your setup — API features depend on the mode selected.

Supported Device Brands

Cams Biometrics ZKTeco Suprema Hikvision Anviz Morpho / IDEMIA Virdi Mantra Nitgen Realtime / Startek Biomax Secugen eSSL Matrix COSEC + Any other brand

Supported Authentication Modalities

Fingerprint Facial Recognition Palm Vein RFID Card PIN / Password QR / Barcode GPS Tracking

Cams Biometric Machines: SlimBeast (i34), Macronium (i35), Hawking Plus (f38+), Hawking (f38), Ultron MultiFaceFP (f34), Ultron MultiFace (f35), Galaxy (f36), Ultron GPS (f37), CanBio34, GymBio34, RSP10i3, RSP10f1, and more.

Introduction

Connection Modes & API Availability

Every biometric machine connects to the Cams Biometric Gateway through one of two push modes. Your device type determines which mode to use.

Native Push Cams & Verified Devices

All Cams Biometrics machines and devices verified at developer.camsbiometrics.com connect via Native Push. No additional setup needed — the device communicates directly with the Biometric Gateway over the internet.

Full API support. All 38 operations work with no limitations — both Callback and RESTful APIs. Zero latency on callbacks, ~15 seconds for RESTful commands.

Hybrid Push All Other Machines

For non-Cams and non-verified machines, you choose a Hybrid Push connection mode that suits your environment. The combination of communication method and deployment topology determines which API features are available.

Communication Methods

(a) Device SDKThe Gateway communicates with the hardware via the device manufacturer's SDK. All features the SDK supports are available through the API. Best option for full API access.

(b) DB PullThe Gateway reads from a local database installed on the site computer (where the device software stores attendance). Only attendance/punch log push to your server is supported. No RESTful APIs (no add/delete user, no load log, etc.).

(c) File ProcessingA designated attendance file on the local computer is placed under continuous surveillance. Every time the file is updated by the device software, new attendance records are automatically detected, pulled, and pushed to your Callback URL in real time. Same API limitations as DB Pull -- attendance push only, no RESTful APIs.

Deployment Topologies

(X) DirectThe site computer has a public IP with port forwarding to the local network. The Biometric Gateway connects to the device/DB/files directly over the internet.

(Y) IndirectA Hybrid Connector is installed on the local computer. It acts as a bridge between the local machine/DB/files and the Biometric Gateway — no public IP required on the customer side.

Hybrid Push — Feature Availability Matrix

Mode	Communication	Topology	Callback API	RESTful API
Direct Device	(a) SDK	(X) Public IP	Full	Full (SDK limits)
Indirect Device	(a) SDK	(Y) Hybrid Connector	Full	Full (SDK limits)
Direct DB	(b) DB Pull	(X) Public IP	Attendance only	Not supported
Indirect DB	(b) DB Pull	(Y) Hybrid Connector	Attendance only	Not supported
Direct File	(c) File	(X) Public IP	Attendance only	Not supported
Indirect File	(c) File	(Y) Hybrid Connector	Attendance only	Not supported

Which mode should I choose? If your non-Cams device has an SDK supported by the Gateway, choose Device SDK mode (a) for full API access. If not, DB Pull (b) or File Processing (c) will still get attendance data flowing. For topology, choose Indirect (Y) with Hybrid Connector if you cannot set up a public IP — it is the easiest to deploy.

Hardware limitations may further restrict API features. Even in Device SDK mode, specific APIs may not function depending on the device model's firmware or SDK capabilities. Always test with your hardware and verify with the Cams support team.

API Reference

API Architecture

Property	Callback API	RESTful API
Initiator	Device / Biometric Gateway	Your server
Direction	Device → Your Server	Your Server → Device
Latency	Real-time (milliseconds)	~15 seconds
Trigger	Biometric event on device	HTTP POST from your code
Your role	Receive & acknowledge	Send command & poll/wait for response
Response body	`{"status":"done"}`	`{"Status":"done","OperationID":"…","StatusCode":0}`
Offline behaviour	Cached by engine; delivered when server is back online	Queued by engine; delivered when device reconnects

API Reference

Common Fields

All requests — both Callback and RESTful — share these top-level fields.

AuthTokenString. A 32-character token that identifies and authenticates requests from a specific device. Configured in the API Monitor portal. Validate this on every inbound callback.

OperationIDString. A unique identifier for this operation instance (e.g. "j95xfejt3vr1"). RESTful responses echo the same OperationID so you can match requests to responses.

TimeString. UTC timestamp of when the event was processed, in the format YYYY-MM-DD HH:mm:ss GMT +0000. Device-local timestamps within the payload may use a different timezone offset.

stgid (query param)String. Service Tag ID — identifies the target device for RESTful API calls. Pass as a URL query parameter to the endpoint found in your API Monitor account: POST https://<your-endpoint>?stgid=YOUR_TAG_ID.

Template Types

Biometric and credential data is carried in a Template array. Each item has a Type field:

Template Merge Behaviour — Important for Callback Handlers
When user data is pushed from the device (Callback operations #3–#9), templates may arrive one at a time or in groups, across multiple callbacks. Each callback does not contain the user's full template set — it only carries the templates that were added or changed.

Your server must merge incoming templates with existing stored templates for that user. The unique key for each template is Type + Index. For example:
• Callback 1 arrives with Fingerprint Index 0 → store it
• Callback 2 arrives with Face Index 0 + Card → merge, don't overwrite fingerprint
• Callback 3 arrives with Fingerprint Index 0 (new data) → update the existing fingerprint at Index 0
Never replace all templates on a callback — always upsert by Type + Index.

Type	Description	Key extra fields
`Card`	RFID / proximity card number	`Data` (card number string)
`Password`	Numeric PIN	`Data` (PIN string)
`Fingerprint`	Fingerprint template — Base64 encoded binary	`Index` (finger index 0–9), `Size`, `Data`
`Face`	Face template — Base64 encoded JPEG or binary	`Index`, `Size`, `Data`
`Palm`	Palm vein template — Base64 encoded binary	`Index`, `Data`
`UserPhoto`	User profile photo — Base64 encoded JPEG	`Data`

API Reference

Response Status Codes

RESTful API responses include a numeric StatusCode. Callback API responses always use the simple {"status":"done"} form regardless of outcome.

Code	Status	Description
`0`	Success	Operation completed successfully.
`1`	Invalid Request Data	The JSON body is malformed or contains invalid values.
`2`	Invalid Service Tag ID	The `stgid` query parameter does not match any registered device.
`3`	Invalid Request	Request structure does not match the expected operation format.
`4`	Invalid Encryption	Payload encryption (AES-256) could not be decrypted. Check your encryption key.
`5`	Device Offline	The target device is not currently connected to the Biometric Gateway.
`6`	Operation Timeout	The device did not acknowledge the command within the timeout window.
`7`	Invalid Auth Token	The `AuthToken` in the request does not match the device's configured token.
`8`	User Already Exists	An Add operation was attempted for a UserID that already exists on the device.
`9`	User Not Found	The specified UserID does not exist on the device.
`10`	Template Error	The biometric template data is corrupt or in an unsupported format.
`11`	Device Memory Full	The device has reached its maximum user or template capacity.
`13`	Invalid Security Key	The security key configured in the API Monitor does not match.
`15`	Feature Not Supported	The requested operation is not supported by this device model or communication mode.
`999`	Unknown Error	An unexpected error occurred. Contact Cams support with the OperationID.

Callback APIs Device → Your Server · Operations 1–11

#01

ManuallyUserDeleted

Callback APIDevice → Server

Triggered when a user is manually deleted directly on the device. Contains the UserID and deletion time.

Request — sent to your server

{
  "RealTime": {
    "OperationID": "oy1kjign3sm7",
    "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
    "Time": "2020-09-17 07:42:02 GMT +0000",
    "UserDeleted": {
      "UserID": "1",
      "OperationTime": "2020-09-17 13:12:02 GMT +0530"
    }
  }
}

Response — your server must return

{ "status": "done" }

#02

ManuallyDateModified

Callback APIDevice → Server

Triggered when the device's date/time is manually changed. Reports the new value set.

Request — sent to your server

{
  "RealTime": {
    "OperationID": "1aci5f5o6kbi1",
    "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
    "Time": "2020-09-17 07:52:31 GMT +0000",
    "DateModified": {
      "ModifiedTo": "2020-09-17 10:22:24 GMT +0530",
      "OperationTime": "2020-09-17 13:22:31 GMT +0530"
    }
  }
}

Response — your server must return

{ "status": "done" }

#03

ManuallyUserUpdatedWithoutTemplate

Callback APIDevice → Server

User profile (name/type) updated on device — no biometric change. Template array is empty.

Request — sent to your server

{
  "RealTime": {
    "UserUpdated": {
      "UserID": "1",
      "FirstName": "jency",
      "LastName": "mary",
      "UserType": "User",
      "OperationTime": "2020-09-16 18:45:34 GMT +0530",
      "Template": []
    },
    "LabelName": "Burj Khalifa",
    "SerialNumber": "ZHM11xxxxxxxx",
    "OperationID": "1vsyboxnuuorq",
    "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
    "Time": "2020-09-16 13:15:33 GMT +0000"
  }
}

Response — your server must return

{ "status": "done" }

#04

ManuallyUserUpdatedWithCard

Callback APIDevice → Server

User updated on device with a card/RFID template. Data holds the card number.

Request — sent to your server

{
  "RealTime": {
    "UserUpdated": {
      "UserID": "8", "FirstName": "", "LastName": "", "UserType": "User",
      "OperationTime": "2020-09-17 15:33:38 GMT +0530",
      "Template": [{ "Type": "Card", "UserID": "8", "Data": "9804445" }]
    },
    "LabelName": "Burj Khalifa",
    "SerialNumber": "ZHM11xxxxxxxx",
    "OperationID": "oldcu1ekxdbz",
    "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
    "Time": "2020-09-17 10:03:38 GMT +0000"
  }
}

Response — your server must return

{ "status": "done" }

#05

ManuallyUserUpdatedWithPassword

Callback APIDevice → Server

User updated on device with a PIN/password. Data is the numeric PIN string.

Request — sent to your server

{
  "RealTime": {
    "UserUpdated": {
      "UserID": "8", "FirstName": "", "LastName": "", "UserType": "User",
      "OperationTime": "2020-09-17 15:33:38 GMT +0530",
      "Template": [{ "Type": "Password", "UserID": "8", "Data": "124445" }]
    },
    "LabelName": "Burj Khalifa", "SerialNumber": "ZHM11xxxxxxxx",
    "OperationID": "oldcu1ekxdbz",
    "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
    "Time": "2020-09-17 10:03:38 GMT +0000"
  }
}

Response — your server must return

{ "status": "done" }

#06

ManuallyUserUpdatedWithFingerPrint

Callback APIDevice → Server

User updated with fingerprint. Index = finger slot 0–9, Size = byte length, Data = Base64 binary.

Request — sent to your server

{
  "RealTime": {
    "UserUpdated": {
      "OperationTime": "2020-09-17 12:48:28 GMT +0530",
      "Template": [{
        "Type": "Fingerprint", "UserID": "2",
        "Size": "1176", "Index": "6",
        "Data": "SjNTUzIxAAADcHcECAUHCc7Q..."
      }]
    },
    "LabelName": "Burj Khalifa", "SerialNumber": "ZHM11xxxxxxxx",
    "OperationID": "vq01h140jswo",
    "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
    "Time": "2020-09-17 13:15:31 GMT +0000"
  }
}

Response — your server must return

{ "status": "done" }

#07

ManuallyUserUpdatedWithFace

Callback APIDevice → Server

User updated with a face template. Data is Base64-encoded JPEG or proprietary face binary (device-dependent).

Request — sent to your server

{
  "RealTime": {
    "UserUpdated": {
      "OperationTime": "2020-09-17 19:04:55 GMT +0530",
      "Template": [{
        "Type": "Face", "UserID": "2",
        "Size": "28112", "Index": "0",
        "Data": "/9j/4AAQSkZJRgABAQAAAQABAAD..."
      }]
    },
    "LabelName": "Burj Khalifa", "SerialNumber": "ZHM11xxxxxxxx",
    "OperationID": "5qwmu986vm7c",
    "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
    "Time": "2020-09-17 13:15:31 GMT +0000"
  }
}

Response — your server must return

{ "status": "done" }

#08

ManuallyUserUpdatedWithPalm

Callback APIDevice → Server

User updated with a palm vein template. Data is Base64-encoded palm binary.

Request — sent to your server

{
  "RealTime": {
    "UserUpdated": {
      "OperationTime": "2020-09-17 19:10:12 GMT +0530",
      "Template": [{
        "Type": "Palm", "UserID": "2", "Index": "0",
        "Data": "apUBEOAHv98IAAwAAc/qAgzWDlDL..."
      }]
    },
    "LabelName": "Burj Khalifa", "SerialNumber": "ZHM11xxxxxxxx",
    "OperationID": "p3rm9kqx1yz0",
    "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
    "Time": "2020-09-17 13:40:12 GMT +0000"
  }
}

Response — your server must return

{ "status": "done" }

#09

ManuallyUserUpdatedWithUserPhoto

Callback APIDevice → Server

User updated with a profile photo. Data is Base64-encoded JPEG.

Request — sent to your server

{
  "RealTime": {
    "UserUpdated": {
      "UserID": "5", "FirstName": "Alex", "LastName": "Thomas",
      "UserType": "User",
      "OperationTime": "2020-09-17 20:00:00 GMT +0530",
      "Template": [{ "Type": "UserPhoto", "UserID": "5", "Data": "/9j/4AAQSkZJRgABAQAAAQABAAD..." }]
    },
    "LabelName": "Burj Khalifa", "SerialNumber": "ZHM11xxxxxxxx",
    "OperationID": "up9h2bxk7q11",
    "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
    "Time": "2020-09-17 14:30:00 GMT +0000"
  }
}

Response — your server must return

{ "status": "done" }

#10

RealTimeAttendancePhoto

Callback APIDevice → Server

Real-time punch event with a captured snapshot (for devices with photo capture). LogPhoto is Base64-encoded JPEG.

Request — sent to your server

{
  "RealTime": {
    "Log": {
      "UserID": "3",
      "LogPhoto": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
      "LogTime": "2020-09-17 07:48:30 GMT +0530"
    },
    "OperationID": "x58636uon24u",
    "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
    "Time": "2020-09-17 04:19:18 GMT +0000"
  }
}

Response — your server must return

{ "status": "done" }

#11

RealTimePunchLog

Callback APIDevice → Server

Primary real-time attendance event — fires on every punch. Includes type, input method, temperature, and face-mask status.

Type: CheckIn · CheckOut · BreakOut · BreakIn · OverTimeIn · OverTimeOut · MealIn · MealOut | InputType: Fingerprint · Face · Palm · Card · Password

Request — sent to your server

{
  "RealTime": {
    "OperationID": "9nu1wak5616p",
    "LabelName": "Burj Khalifa",
    "SerialNumber": "ZHM11xxxxxxxx",
    "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"
  }
}

Response — your server must return

{ "status": "done" }

RESTful APIs Your Server → Device · Operations 12–38

#12

LoadLog

RESTful APIServer → Device

Retrieves attendance punch logs from the device within a time window. Recommended max range: 30 days.

Request — POST to your RESTful endpoint

{
  "Load": {
    "PunchLog": {
      "Filter": {
        "StartTime": "2020-09-17 00:01:33 GMT +0530",
        "EndTime": "2020-09-17 22:01:33 GMT +0530"
      }
    }
  },
  "OperationID": "j95xfejt3vr1",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-17 12:01:33 GMT +0530"
}

Response — from device

{
  "Status": "done",
  "OperationID": "j95xfejt3vr1",
  "PunchLog": {
    "ReturnRowCount": "18",
    "Log": [
      { "Type": "CheckOut", "Temperature": 36.8, "InputType": "Face", "UserID": "2", "LogTime": "2020-09-17 16:53:43 GMT +0530", "FaceMask": false },
      { "Type": "CheckOut", "Temperature": 36.6, "InputType": "Palm", "UserID": "1", "LogTime": "2020-09-17 16:54:15 GMT +0530", "FaceMask": false },
      { "Type": "CheckIn",  "Temperature": 36.5, "InputType": "Fingerprint", "UserID": "3", "LogTime": "2020-09-17 09:01:44 GMT +0530", "FaceMask": false }
    ]
  }
}

#13

LoadDeviceInformation

RESTful APIServer → Device

Retrieves hardware details, capacity limits, registered user/template counts, and license dates from the device.

Request — POST to your RESTful endpoint

{
  "Load": { "DeviceInformation": "All" },
  "OperationID": "j95xfejt3vr1",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-08-28 12:01:33 GMT +0530"
}

Response — from device

{
  "Status": "done",
  "OperationID": "j95xfejt3vr1",
  "StatusCode": 0,
  "DeviceInformation": {
    "DeviceModel": "Hawking Plus (f38+)",
    "Manufacturer": "Dheeram Innovations",
    "MacAddress": "00-01-A9-16-27-AB",
    "StartDate": "03/04/2024",
    "EndDate": "03/04/2025",
    "LastConnectedTime": "13-11-2025 18:03:48 GMT +0530",
    "RegisteredUsers": "0",
    "RegisteredFaces": "0",
    "RegisteredFingerprints": "0",
    "MaximumFacesSupported": "5000",
    "MaximumFingerprintsSupported": "10000",
    "MaximumAttendanceLogsSupported": "500000"
  }
}

#14

AddUserWithCard

RESTful APIServer → Device

Registers a new user with a card/RFID number as their only credential.

Request

{
  "Add": {
    "User": { "UserID": "100", "FirstName": "Manu", "LastName": "Mona", "UserType": "USER" },
    "Template": [{ "Type": "Card", "UserID": "100", "Data": "102836" }]
  },
  "OperationID": "1jxpjeoasu8wl",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-17 11:09:09 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "1jxpjeoasu8wl", "StatusCode": 0 }

#15

AddUserWithPassword

RESTful APIServer → Device

Registers a new user with a numeric PIN/password as their only credential.

Request

{
  "Add": {
    "User": { "UserID": "100", "FirstName": "Manu", "LastName": "Mona", "UserType": "USER" },
    "Template": [{ "Type": "Password", "UserID": "100", "Data": "123456" }]
  },
  "OperationID": "1jxpjeoasu8wl",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-17 11:09:09 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "1jxpjeoasu8wl", "StatusCode": 0 }

#16

AddUserWithFace

RESTful APIServer → Device

Registers a user with a face template. Data is Base64-encoded JPEG or device-specific binary. Size is the byte length.

Request

{
  "Add": {
    "User": { "UserID": "100", "FirstName": "Manu", "LastName": "Mona", "UserType": "USER" },
    "Template": [{ "Type": "Face", "UserID": "100", "Size": "25072", "Index": "0", "Data": "/9j/4AAQSkZJRgABAQAAAQABAAD..." }]
  },
  "OperationID": "1jxpjeoasu8wl",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-17 11:09:09 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "1jxpjeoasu8wl", "StatusCode": 0 }

#17

AddUserWithFingerPrint

RESTful APIServer → Device

Registers a user with one fingerprint template. Index specifies the finger slot (0–9).

Request

{
  "Add": {
    "User": { "UserID": "100", "FirstName": "Manu", "LastName": "Mona", "UserType": "USER" },
    "Template": [{ "Type": "Fingerprint", "UserID": "100", "Size": "1176", "Index": "0", "Data": "TW9TUzIxAAAELC4ECAUHCc7Q..." }]
  },
  "OperationID": "1jxpjeoasu8wl",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-17 11:09:09 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "1jxpjeoasu8wl", "StatusCode": 0 }

#18

AddUserWithPalm

RESTful APIServer → Device

Registers a user with a palm vein template. Data is Base64-encoded palm binary.

Request

{
  "Add": {
    "User": { "UserID": "100", "FirstName": "Manu", "LastName": "Mona", "UserType": "USER" },
    "Template": [{ "Type": "Palm", "UserID": "100", "Index": "0", "Data": "apUBEOAHv98IAAwAAc/qAgzWDlDL..." }]
  },
  "OperationID": "1jxpjeoasu8wl",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-17 11:09:09 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "1jxpjeoasu8wl", "StatusCode": 0 }

#19

AddUserWithUserPhoto

RESTful APIServer → Device

Registers a user with a profile photo stored on the device. Data is Base64-encoded JPEG.

Request

{
  "Add": {
    "User": { "UserID": "100", "FirstName": "Manu", "LastName": "Mona", "UserType": "USER" },
    "Template": [{ "Type": "UserPhoto", "UserID": "100", "Data": "/9j/4AAQSkZJRgABAQAAAQABAAD..." }]
  },
  "OperationID": "1jxpjeoasu8wl",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-17 11:09:09 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "1jxpjeoasu8wl", "StatusCode": 0 }

#20

AddUserWithCardAndPassword

RESTful APIServer → Device

Registers a user with both a card number and a PIN — two entries in the Template array.

Request

{
  "Add": {
    "User": { "UserID": "100", "FirstName": "Manu", "LastName": "Mona", "UserType": "USER" },
    "Template": [
      { "Type": "Card",     "UserID": "100", "Data": "102836" },
      { "Type": "Password", "UserID": "100", "Data": "123456" }
    ]
  },
  "OperationID": "1jxpjeoasu8wl",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-17 11:09:09 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "1jxpjeoasu8wl", "StatusCode": 0 }

#21

AddUserWithCardAndFingerPrint

RESTful APIServer → Device

Registers a user with a card number and one fingerprint template.

Request

{
  "Add": {
    "User": { "UserID": "100", "FirstName": "Manu", "LastName": "Mona", "UserType": "USER" },
    "Template": [
      { "Type": "Card",        "UserID": "100", "Data": "102836" },
      { "Type": "Fingerprint", "UserID": "100", "Size": "1176", "Index": "0", "Data": "TW9TUzIxAAAELC4E..." }
    ]
  },
  "OperationID": "1jxpjeoasu8wl",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-17 11:09:09 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "1jxpjeoasu8wl", "StatusCode": 0 }

#22

AddUserWithPalmAndFace

RESTful APIServer → Device

Registers a user with both a palm vein and a face template.

Request

{
  "Add": {
    "User": { "UserID": "100", "FirstName": "Manu", "LastName": "Mona", "UserType": "USER" },
    "Template": [
      { "Type": "Palm", "UserID": "100", "Index": "0", "Data": "apUBEOAHv98IAAwA..." },
      { "Type": "Face", "UserID": "100", "Size": "25072", "Index": "0", "Data": "/9j/4AAQSkZJRgAB..." }
    ]
  },
  "OperationID": "1jxpjeoasu8wl",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-17 11:09:09 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "1jxpjeoasu8wl", "StatusCode": 0 }

#23

AddUserWithCard_FingerPrintAndFace

RESTful APIServer → Device

Registers a user with card, fingerprint, and face — three templates.

Request

{
  "Add": {
    "User": { "UserID": "100", "FirstName": "Manu", "LastName": "Mona", "UserType": "USER" },
    "Template": [
      { "Type": "Card",        "UserID": "100", "Data": "102836" },
      { "Type": "Fingerprint", "UserID": "100", "Size": "1176", "Index": "0", "Data": "TW9TUzIxAAAELC4E..." },
      { "Type": "Face",        "UserID": "100", "Size": "25072", "Index": "0", "Data": "/9j/4AAQSkZJRgAB..." }
    ]
  },
  "OperationID": "1jxpjeoasu8wl",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-17 11:09:09 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "1jxpjeoasu8wl", "StatusCode": 0 }

#24

AddUserWithCard_PalmAndUserPhoto

RESTful APIServer → Device

Registers a user with card, palm vein, and profile photo — three templates.

Request

{
  "Add": {
    "User": { "UserID": "100", "FirstName": "Manu", "LastName": "Mona", "UserType": "USER" },
    "Template": [
      { "Type": "Card",      "UserID": "100", "Data": "102836" },
      { "Type": "Palm",      "UserID": "100", "Index": "0", "Data": "apUBEOAHv98IAAwA..." },
      { "Type": "UserPhoto", "UserID": "100", "Data": "/9j/4AAQSkZJRgAB..." }
    ]
  },
  "OperationID": "1jxpjeoasu8wl",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-17 11:09:09 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "1jxpjeoasu8wl", "StatusCode": 0 }

#25

AddUserWithCard_Password_FingerPrintAndFace

RESTful APIServer → Device

Registers a user with card, password, fingerprint, and face — four templates.

Request

{
  "Add": {
    "User": { "UserID": "100", "FirstName": "Manu", "LastName": "Mona", "UserType": "USER" },
    "Template": [
      { "Type": "Card",        "UserID": "100", "Data": "102836" },
      { "Type": "Password",    "UserID": "100", "Data": "123456" },
      { "Type": "Fingerprint", "UserID": "100", "Size": "1176", "Index": "0", "Data": "TW9TUzIxAAAELC4E..." },
      { "Type": "Face",        "UserID": "100", "Size": "25072", "Index": "0", "Data": "/9j/4AAQSkZJRgAB..." }
    ]
  },
  "OperationID": "1jxpjeoasu8wl",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-17 11:09:09 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "1jxpjeoasu8wl", "StatusCode": 0 }

#26

AddUserWithCard_Password_PalmAndUserPhoto

RESTful APIServer → Device

Registers a user with card, password, palm vein, and profile photo — four templates.

Request

{
  "Add": {
    "User": { "UserID": "100", "FirstName": "Manu", "LastName": "Mona", "UserType": "USER" },
    "Template": [
      { "Type": "Card",      "UserID": "100", "Data": "102836" },
      { "Type": "Password",  "UserID": "100", "Data": "123456" },
      { "Type": "Palm",      "UserID": "100", "Index": "0", "Data": "apUBEOAHv98IAAwA..." },
      { "Type": "UserPhoto", "UserID": "100", "Data": "/9j/4AAQSkZJRgAB..." }
    ]
  },
  "OperationID": "1jxpjeoasu8wl",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-17 11:09:09 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "1jxpjeoasu8wl", "StatusCode": 0 }

#27

AddUserWithCard_FingerPrint_Password_Face_PalmAndUserPhoto

RESTful APIServer → Device

Registers a user with all six credential types — card, fingerprint, password, face, palm, and profile photo.

Request

{
  "Add": {
    "User": { "UserID": "100", "FirstName": "Manu", "LastName": "Mona", "UserType": "USER" },
    "Template": [
      { "Type": "Card",        "UserID": "100", "Data": "102836" },
      { "Type": "Password",    "UserID": "100", "Data": "123456" },
      { "Type": "Fingerprint", "UserID": "100", "Size": "1176", "Index": "0", "Data": "TW9TUzIxAAAELC4E..." },
      { "Type": "Face",        "UserID": "100", "Size": "25072", "Index": "0", "Data": "/9j/4AAQSkZJRgAB..." },
      { "Type": "Palm",        "UserID": "100", "Index": "0",    "Data": "apUBEOAHv98IAAwA..." },
      { "Type": "UserPhoto",   "UserID": "100", "Data": "/9j/4AAQSkZJRgAB..." }
    ]
  },
  "OperationID": "1jxpjeoasu8wl",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-17 11:09:09 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "1jxpjeoasu8wl", "StatusCode": 0 }

#28

AddUserWithoutTemplate

RESTful APIServer → Device

Creates a user record on the device with no biometric data. Useful to pre-register before enrolling templates separately.

Request

{
  "Add": {
    "User": { "UserID": "1", "FirstName": "Manu", "LastName": "Mona", "UserType": "User" }
  },
  "OperationID": "1jxpjeoasu8wl",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-17 11:09:09 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "1jxpjeoasu8wl", "StatusCode": 0 }

#29

DeleteUser

RESTful APIServer → Device

Deletes a specific user and all their biometric templates from the device.

Request

{
  "Delete": { "User": { "UserID": "User123" } },
  "OperationID": "1jxpjeoasu8wl",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-11 16:15:31 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "1jxpjeoasu8wl", "StatusCode": 0 }

#30

DeleteAllUser

RESTful APIServer → Device

Deletes all users and their biometric templates from the device. Irreversible.

Destructive. All enrolled users and templates will be permanently erased from the device.

Request

{
  "Delete": { "User": "All" },
  "OperationID": "j95xfejt3vr1",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-17 12:01:33 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "j95xfejt3vr1", "StatusCode": 0 }

#31

DeleteLogAll

RESTful APIServer → Device

Clears all attendance punch logs from the device. User records and templates are not affected.

Request

{
  "Delete": { "Log": "All" },
  "OperationID": "j95xfejt3vr1",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-17 12:01:33 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "j95xfejt3vr1", "StatusCode": 0 }

#32

DeleteAttendancePhoto

RESTful APIServer → Device

Deletes all punch photos stored on the device. Applies to devices with photo capture capability.

Request

{
  "Delete": { "PunchPhoto": "All" },
  "OperationID": "j95xfejt3vr1",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-17 12:01:33 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "j95xfejt3vr1", "StatusCode": 0 }

#33

ResendAttendance

RESTful APIServer → Device

Instructs the device to re-push attendance logs within a time range to your server via Callback. Useful for recovering missed records.

Request

{
  "OperationID": "j95xfejt3vr1",
  "Resend": {
    "PunchLog": {
      "Filter": {
        "StartTime": "2020-09-17 15:49:33 GMT +0530",
        "EndTime": "2020-09-17 16:20:33 GMT +0530"
      }
    }
  },
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-17 12:01:33 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "j95xfejt3vr1", "StatusCode": 0 }

#34

ResendAllUser

RESTful APIServer → Device

Instructs the device to re-push all registered user data (profiles and templates) to your server via Callback.

Request

{
  "OperationID": "j95xfejt3vr1",
  "Resend": { "User": "All" },
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-17 12:01:33 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "j95xfejt3vr1", "StatusCode": 0 }

#35

EnrollFingerPrint

RESTful APIServer → Device

Triggers the device to start an on-device fingerprint enrollment session. The user must be physically present at the device.

Request

{
  "Enroll": {
    "User": { "UserID": "3", "Type": "Fingerprint", "FirstName": "Rajesh", "LastName": "Ragavendhar" }
  },
  "OperationID": "1jxpjeoasu8wl",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2025-09-25 11:09:09 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "1jxpjeoasu8wl", "StatusCode": 0 }

#36

UpdateAccessTime

RESTful APIServer → Device

Sets a time-bound access window for a user. The user can only authenticate within the specified start–end range.

Request

{
  "Update": {
    "AccessTime": { "UserID": "20", "Start": "2022-07-11 00:00:00", "End": "2022-07-11 23:59:59" }
  },
  "OperationID": "1jxpjeoasu8wl",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-11 16:39:29 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "1jxpjeoasu8wl", "StatusCode": 0 }

#37

EnableUser

RESTful APIServer → Device

Re-enables a previously disabled user, restoring their ability to authenticate on the device.

Request

{
  "Update": { "User": { "UserID": "1", "Access": "enable" } },
  "OperationID": "1jxpjeoasu8wl",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-17 11:09:09 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "1jxpjeoasu8wl", "StatusCode": 0 }

#38

DisableUser

RESTful APIServer → Device

Disables a user without deleting them. Record and templates are kept but authentication is blocked until re-enabled.

Request

{
  "Update": { "User": { "UserID": "1", "Access": "disable" } },
  "OperationID": "1jxpjeoasu8wl",
  "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
  "Time": "2020-09-17 11:09:09 GMT +0530"
}

Response

{ "Status": "done", "OperationID": "1jxpjeoasu8wl", "StatusCode": 0 }

Additional Information

Ports Supported

To receive real-time attendance information, your server must expose an HTTP(S) endpoint that the Cams Protocol Engine can reach.

Port	Protocol	Usage
`80`	HTTP	Production. Bind your callback URL to port 80. Configured in the API Monitor and called automatically on punches.
`443`	HTTPS	Production (secure). HTTPS with valid SSL certificate. Recommended for production.
`8123`	HTTP	Testing only. Non-standard port temporarily available during development.

HTTPS recommended. Use HTTPS with a valid SSL certificate for production. Ensure auto-renewal without server restart.

Additional Information

Sample Data

Sample request and response payloads for all 38 operations are documented above in each operation section. For a consolidated view:

This pageEvery operation section above includes copy-ready request and response JSON with sample data.

Legacy sample pagebiometric-web-api-sample-request-response.html — dropdown selector for each operation.

Additional Information

Encryption

Optional AES-256 encryption can be enabled for all data exchanged between the Cams Protocol Engine and your server.

AlgorithmAES-256 in ECB mode with PKCS5 padding (AES/ECB/PKCS5PADDING).

Key configurationSet your key as the Security Key in the API Monitor. When configured, all raw JSON payloads are encrypted.

EncodingEncrypted payloads are Base64-encoded for safe HTTP transport.

Java Example

Encrypt / Decrypt (Java)

// Encryption
Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5PADDING");
SecretKeySpec keySpec = new SecretKeySpec(securityKey.getBytes("UTF-8"), "AES");
cipher.init(Cipher.ENCRYPT_MODE, keySpec);
String encrypted = Base64.getEncoder().encodeToString(cipher.doFinal(rawJson.getBytes("UTF-8")));

// Decryption
cipher.init(Cipher.DECRYPT_MODE, keySpec);
byte[] decoded = Base64.getDecoder().decode(encryptedPayload);
String decrypted = new String(cipher.doFinal(decoded), "UTF-8");

Important: When encryption is enabled, decrypt inbound Callback payloads and encrypt outbound RESTful request bodies using the same key.

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	INR	Notes
Native Push — Cams & Verified Devices
API Activation	$120	₹5,750	One-time per machine.
Yearly API License	$60 – $120	₹3,000 – ₹6,000	Annual renewal required.
Protocol Update (non-Cams)	$120 – $280	₹3,000 – ₹6,000	One-time. Enables Cams protocol on non-Cams devices.
Hybrid Push — ZKTeco, eSSL & All Third-Party Brands
API Activation	$150	₹7,500	One-time per machine.
Yearly API License	$90 – $150	₹4,500 – ₹7,500	Annual renewal required.
Hybrid Connector (non-verified)	$150 – $300	₹7,500 – ₹15,000	One-time. Required for non-verified devices using Hybrid Push.
Hardware & Other
Hardware	$220 – $720	₹9,000 – ₹60,000	Varies by model.

Protocol Engine Lite (on-premise) — For LAN-only or self-hosted environments. Cost: $500–$10,000. Contact sales for details.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

Q: What must my server respond with?
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.

Q: How do I handle duplicate punches?
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 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.

Q: Does the Callback include temperature and mask detection?
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.

Q: Where do I find my RESTful endpoint URL?
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).

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.

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.

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

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.

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.

Q: How do I validate that a callback is genuinely from Cams?
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 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.

Data & Design Considerations

Q: What data format does the API 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").

Q: How do I determine IN/OUT when a user has multiple devices?
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.

Q: How are biometric templates stored and transmitted?
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.

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.

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.

Additional Information

AI-Powered Code Generator Prompts

Download a prompt file for your server language, paste it into any AI assistant (Claude, ChatGPT, Copilot, etc.), and get a complete working implementation — callback receiver, REST client, and HTML test interface — in a single file.

🐘

PHP

Pure PHP · SQLite · No Composer

🟢

Node.js

Express · JSON file store

🐍

Python

Flask · SQLite · stdlib only

🔷

C# (.NET 8)

Minimal API · No MVC

☕

Java

Built-in HttpServer · No deps

🔵

Go

net/http · stdlib only

💎

Ruby

Sinatra · SQLite

Download the prompt file

Click your language above to download the .txt file.

Paste into an AI assistant

Open Claude, ChatGPT, or any AI coding tool. Paste the entire prompt content.

Get a complete working file

The AI generates a single file with: Callback receiver, REST client for all 27 operations, and a fully functional HTML test interface. Just set your config values and run.

Each generated file includes: Callback handler with AuthToken validation and logging, REST client functions for all 27 outbound operations, and a browser-based test UI with an operation dropdown, JSON editor, and response viewer.

Additional Information

Testing Locally (Without Deploying to a Server)

To test your callback integration from your local development machine — without deploying to a production server — you need to make your local machine reachable from the internet so the Cams Protocol Engine can POST callback data to it.

Option A: Public IP + Port Forwarding

If your internet connection has a public (static) IP address, you can forward an external port to your local application.

Find your public IP

Visit whatismyip.com or run curl ifconfig.me in your terminal. Note your public IP address.

Set up port forwarding on your router

Log in to your router admin panel. Forward an external port (e.g. 8080) to your local machine's internal IP and the port your application is running on (e.g. 3000, 5000, 8080).

Configure the Callback URL

In the API Monitor, set your Callback URL to:
http://YOUR_PUBLIC_IP:8080/callback

Test

Trigger a punch on the biometric device. The Cams Protocol Engine will POST the callback data to your public IP, which your router forwards to your local application.

Option B: Tunneling Tools (No Public IP Required)

If you don't have a public IP or can't configure port forwarding, use a tunneling service to expose your local server to the internet.

Tool	Command	Notes
ngrok	`ngrok http 3000`	Free tier available. Gives you a public HTTPS URL instantly.
Cloudflare Tunnel	`cloudflared tunnel --url localhost:3000`	Free. No account needed for quick tunnels.
localhost.run	`ssh -R 80:localhost:3000 ssh.localhost.run`	No installation. Works via SSH.

Start your local application

Run your callback server locally (e.g. php -S localhost:8080 or node server.js or python app.py).

Start the tunnel

Run the tunneling tool. It will output a public URL like https://abc123.ngrok-free.app.

Configure the Callback URL

In the API Monitor, set the Callback URL to the tunnel URL:
https://abc123.ngrok-free.app/callback

Test

Trigger a punch. Callbacks will flow through the tunnel to your local machine in real time.

Important: Tunnel URLs are temporary and change each time you restart the tool (unless you use a paid plan with reserved domains). Update the Callback URL in API Monitor each time you get a new tunnel URL.

RESTful API testing does not require this setup. You can call the RESTful endpoint directly from your local machine using Postman or your code — no port forwarding or tunneling needed. Only the Callback API (inbound from Cams to your server) requires your machine to be reachable from the internet.

Additional Information

Demo with PHP Program

A simple PHP example -- create the table, deploy the script, and start receiving attendance data.

Step 1 — Create the MySQL Table

cams_db_setup.sql

CREATE DATABASE IF NOT EXISTS cams_biometric;
USE cams_biometric;

CREATE TABLE IF NOT EXISTS attendance_logs (
    id            INT AUTO_INCREMENT PRIMARY KEY,
    user_id       VARCHAR(50)  NOT NULL,
    log_time      DATETIME     NOT NULL,
    punch_type    VARCHAR(20)  DEFAULT NULL,
    input_type    VARCHAR(20)  DEFAULT NULL,
    temperature   DECIMAL(4,1) DEFAULT NULL,
    face_mask     TINYINT(1)   DEFAULT NULL,
    serial_number VARCHAR(50)  DEFAULT NULL,
    label_name    VARCHAR(100) DEFAULT NULL,
    raw_json      TEXT         DEFAULT NULL,
    created_at    TIMESTAMP    DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY (user_id, log_time)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Step 2 — PHP Callback Handler

cams-callback.php

<?php
// Database config
$pdo = new PDO("mysql:host=localhost;dbname=cams_biometric;charset=utf8mb4", "root", "");

// Read incoming JSON
$rawInput = file_get_contents("php://input");
$data     = json_decode($rawInput, true);

// Parse PunchLog and insert
if (isset($data['RealTime']['PunchLog'])) {
    $log = $data['RealTime']['PunchLog'];
    $stmt = $pdo->prepare("
        INSERT INTO attendance_logs
            (user_id, log_time, punch_type, input_type, temperature, face_mask, serial_number, label_name, raw_json)
        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
        ON DUPLICATE KEY UPDATE punch_type=VALUES(punch_type), input_type=VALUES(input_type)
    ");
    $stmt->execute([
        $log['UserId']       ?? '',
        date('Y-m-d H:i:s', strtotime($log['LogTime'] ?? 'now')),
        $log['Type']         ?? null,
        $log['InputType']    ?? null,
        $log['Temperature']  ?? null,
        isset($log['FaceMask']) ? ($log['FaceMask'] ? 1 : 0) : null,
        $data['RealTime']['SerialNumber'] ?? null,
        $data['RealTime']['LabelName']    ?? null,
        $rawInput
    ]);
}

// Always respond with this
header("Content-Type: application/json");
echo '{"status":"done"}';
?>

Step 3 — Deploy & Test

Create the table

Run: mysql -u root -p < cams_db_setup.sql

Upload the PHP file

Edit DB credentials if needed, upload to your server.

Set Callback URL

In API Monitor, set: https://yourserver.com/cams-callback.php

Punch & verify

Punch on the device, then check: SELECT * FROM attendance_logs;

Additional Information

URL Testing

Before going live, verify your endpoints using Postman. We provide a ready-made collection with all 27 RESTful operations pre-configured.

Postman Collection

Download and import into Postman. Set your base_url, stgid, and auth_token variables — then start testing instantly.

📥 Download Postman Collection

Import the collection

Open Postman → Import → drag and drop the downloaded .json file. All 27 RESTful operations appear grouped by category.

Set your variables

Go to the collection's Variables tab and set:
base_url = your RESTful endpoint URL (from API Monitor)
stgid = your device's Service Tag ID
auth_token = your device's AuthToken

Send requests

Select any operation, edit the JSON body with your values, and hit Send. Verify the response matches the expected format documented above.

Postman Example

Below is a screenshot showing a sample API request configured in Postman. Set the method to POST, paste your RESTful endpoint URL with ?stgid=, and use raw JSON body.

Postman screenshot showing Cams API request configuration

Test your Callback endpoint too. POST a sample RealTimePunchLog JSON (see Op #11) to your Callback URL and verify your server returns {"status":"done"} with HTTP 200.

Additional Information

Contact Us

For API support, device compatibility, or sales enquiries:

Sales & Support

Emailsales@camsbiometrics.com

WhatsApp+91-98-409-21006 (Support)

Sales+91-98-409-41006

Developer Resources

Forumforum.camsbiometrics.com

Devicesdeveloper.camsbiometrics.com

Productscamsbiometrics.com/product

Cams Biometrics (Dheeram Innovations Pvt Ltd) — No: 2/98D, 2nd Floor, Cams Biometrics Building, Opposite to Satyabama University, Semmancheri, OMR, Chennai – 600119, India.