Integration Architecture
Octal HR supports two integration modes for biometric devices:
- Push mode: The device or a middleware agent on your network sends attendance punches to Octal HR's API endpoint in real time. Best for cloud-connected devices.
- Pull mode: Octal HR's scheduled sync agent connects to the device on your LAN and pulls attendance logs at configurable intervals (e.g., every 15 minutes). Best for offline or on-premises devices using ZKTeco SDK or ADMS protocol.
No internet on the device? Use the Octal HR On-Premise Sync Agent — a lightweight Windows service that bridges your biometric network to the cloud API. Download from Settings → Integrations → Biometric → Download Sync Agent.
Supported Devices
| Brand / Series | Protocol | Mode | Compatibility |
|---|---|---|---|
| ZKTeco (all models) | ADMS / ZK SDK | Push & Pull | Full |
| Suprema BioStation | HTTP / OSDP | Push | Full |
| Hikvision DS-K series | ISAPI | Push | Full |
| Dahua DHI-ASI series | HTTP Event | Push | Full |
| Anviz (CrossChex) | CrossChex SDK | Pull | Partial |
| eSSL (India/Pak market) | ADMS | Push & Pull | Full |
| Other ADMS-compatible | ADMS | Push | Partial |
For any device not listed, use the Generic Push API — any device that can POST JSON over HTTPS is compatible.
Device Setup
ZKTeco (widely used)
1
On the device, go to Comm → ADMS (or Cloud Settings).
2
Set Server Address to your tenant endpoint:
{tenant}.octalhr.com.3
Set Port to
443 and enable HTTPS.4
In Octal HR: Settings → Integrations → Biometric → + Add Device. Enter a device name and serial number.
5
Copy the Device API Key generated and enter it in the ZKTeco device's Server Key / Password field.
6
Restart the device network connection. Within 60 seconds you should see "Last Ping" update in Octal HR.
Push API (Device → Octal HR)
For devices or middleware that POST directly to Octal HR, use this endpoint:
// Endpoint POST https://{tenant}.octalhr.com/api/v1/attendance/punch // Headers Authorization: Bearer {device_api_key} Content-Type: application/json // Payload { "device_serial": "ZKBIO12345", "employee_biometric_id": "0042", // enrolled ID on device "punch_time": "2026-05-09T09:03:44+05:00", "punch_type": "check_in" // or "check_out" }
Octal HR maps the employee_biometric_id to an employee using the Biometric ID field on each employee profile. Ensure this is populated before enrolling on the device.
Pull API (Octal HR → Device)
For on-premises devices, the Sync Agent polls the device on the local network. Configure the pull interval in Settings → Integrations → Biometric → [Device Name] → Sync Settings:
- Sync interval: 5, 15, 30, or 60 minutes (default: 15 minutes).
- Lookback window: How many hours back to fetch on each sync (default: 24 hours — handles offline periods).
- Duplicate handling: Punch records with the same device serial + employee ID + timestamp are deduplicated automatically.
Troubleshooting
| Symptom | Likely Cause | Fix |
|---|---|---|
| Device shows "Last Ping: Never" | Device can't reach Octal HR server | Check network/firewall; verify ADMS server address and port 443 is open |
| Punches not appearing in attendance | Biometric ID not mapped to employee | Go to Employee Profile → Biometric ID and enter the enrolled ID |
| Punches arriving with wrong timezone | Device clock not set to PKT (UTC+5) | Set device timezone to +05:00; or enable timezone override in device settings |
| Duplicate attendance records | Device pushing and Sync Agent pulling simultaneously | Use only one mode per device — disable ADMS push on the device if using pull mode |
| Sync Agent offline | Windows service stopped | Restart "Octal HR Sync Agent" service in Windows Services; check agent logs at %ProgramData%\OctalHR\logs |
Real-time monitoring: Go to Settings → Integrations → Biometric → [Device Name] → Live Feed to see the last 50 punches received from the device with timestamps and employee names. Useful for confirming the connection is live.