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
| 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 |
Common Fields
All requests — both Callback and RESTful — share these top-level fields.
"j95xfejt3vr1"). RESTful responses echo the same OperationID so you can match requests to responses.YYYY-MM-DD HH:mm:ss GMT +0000. Device-local timestamps within the payload may use a different timezone offset.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:
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 0Never 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 |
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. |
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. |
Sample Data
Sample request and response payloads for all 38 operations are documented above in each operation section. For a consolidated view:
Encryption
Optional AES-256 encryption can be enabled for all data exchanged between the Cams Protocol Engine and your server.
AES/ECB/PKCS5PADDING).Java Example
// 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");