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.

Quick answers

What are the two API flows?

The Callback API sends events from the device (via the Cams Biometric Gateway) to your server in real time. The RESTful API lets your server send commands to a device, and the response arrives in about 15 seconds. If your server is offline, the engine caches callbacks; REST commands are queued until the device reconnects.

What status codes does the RESTful API return?

A numeric StatusCode: 0 success, 1 invalid request data, 2 invalid Service Tag ID, 3 invalid request, 4 invalid encryption, 5 device offline, 6 operation timeout, 7 invalid auth token, 8 user already exists, 9 user not found, 10 template error, 11 device memory full, 13 invalid security key, 15 feature not supported, 999 unknown error. Callback responses always use {"status":"done"}.

What does status code 5 (Device Offline) mean?

The target device is not currently connected to the Biometric Gateway. See status code 5.

How do I authenticate requests?

Every request carries an AuthToken, a 32-character token that identifies one device and is set in the API Monitor portal. Validate it on every inbound callback. REST calls also pass the device as the stgid (Service Tag ID) query parameter. See Common Fields.

Which ports does my server need?

Port 80 (HTTP) or 443 (HTTPS) for production; HTTPS with a valid certificate is recommended. Port 8123 (HTTP) is for testing only. See Ports Supported.

How is the payload encrypted?

Encryption is optional. When enabled, payloads use AES-256 in ECB mode with PKCS5 padding (AES/ECB/PKCS5PADDING), keyed with the Security Key set in the API Monitor, and are Base64-encoded for HTTP transport. Decrypt inbound callbacks and encrypt outbound REST bodies with the same key. See Encryption.

How do I handle templates that arrive across several callbacks?

Merge them. Each callback carries only the templates that were added or changed. The unique key for a template is Type + Index, so upsert by that pair and never replace a user's whole template set. See Template Types.

Which template types exist?

Card, Password, Fingerprint, Face, Palm and UserPhoto. Fingerprint, Face and Palm templates are Base64-encoded, and the fingerprint index runs 0–9.

API Architecture

PropertyCallback APIRESTful API
InitiatorDevice / Biometric GatewayYour server
DirectionDevice → Your ServerYour Server → Device
LatencyReal-time (milliseconds)~15 seconds
TriggerBiometric event on deviceHTTP POST from your code
Your roleReceive & acknowledgeSend command & poll/wait for response
Response body{"status":"done"}{"Status":"done","OperationID":"…","StatusCode":0}
Offline behaviourCached by engine; delivered when server is back onlineQueued by engine; delivered when device reconnects

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.
TypeDescriptionKey extra fields
CardRFID / proximity card numberData (card number string)
PasswordNumeric PINData (PIN string)
FingerprintFingerprint template — Base64 encoded binaryIndex (finger index 0–9), Size, Data
FaceFace template — Base64 encoded JPEG or binaryIndex, Size, Data
PalmPalm vein template — Base64 encoded binaryIndex, Data
UserPhotoUser profile photo — Base64 encoded JPEGData

Response Status Codes

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

CodeStatusDescription
0SuccessOperation completed successfully.
1Invalid Request DataThe JSON body is malformed or contains invalid values.
2Invalid Service Tag IDThe stgid query parameter does not match any registered device.
3Invalid RequestRequest structure does not match the expected operation format.
4Invalid EncryptionPayload encryption (AES-256) could not be decrypted. Check your encryption key.
5Device OfflineThe target device is not currently connected to the Biometric Gateway.
6Operation TimeoutThe device did not acknowledge the command within the timeout window.
7Invalid Auth TokenThe AuthToken in the request does not match the device's configured token.
8User Already ExistsAn Add operation was attempted for a UserID that already exists on the device.
9User Not FoundThe specified UserID does not exist on the device.
10Template ErrorThe biometric template data is corrupt or in an unsupported format.
11Device Memory FullThe device has reached its maximum user or template capacity.
13Invalid Security KeyThe security key configured in the API Monitor does not match.
15Feature Not SupportedThe requested operation is not supported by this device model or communication mode.
999Unknown ErrorAn unexpected error occurred. Contact Cams support with the OperationID.

Ports Supported

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

PortProtocolUsage
80HTTPProduction. Bind your callback URL to port 80. Configured in the API Monitor and called automatically on punches.
443HTTPSProduction (secure). HTTPS with valid SSL certificate. Recommended for production.
8123HTTPTesting 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.

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.

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.