API reference: architecture, fields and status codes

The building blocks shared by every operation: request flow, common JSON fields, template types, status codes, ports and payload encryption.

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.

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.