Biometric Device Integration

Connect any fingerprint or face-recognition attendance terminal to ZenoHosp People — no specific brand required.

How it works

ZenoHosp People is vendor-neutral. Your terminal (ZKTeco, eSSL, Matrix, Suprema, Realtime, or anything else) connects through one of three routes, and all three feed the same attendance system. Every punch becomes a sign-in / sign-out session; multiple sessions a day (lunch breaks, ward rounds) are added up automatically, flow into monthly summaries and payroll, and a live check-in shows the employee as checked in across all ZenoHosp apps.

Your situation	Route	Effort
Device (or its software) can push data to a web address	A. Direct push	Configure one URL on the device
Device is on your local network only (most common)	B. Connector agent	Run a small program on any PC on that network
You just want to upload the device's exported log files	C. File import	Upload a CSV whenever you like

You can start with C today and move to A or B later — nothing else changes.

Before you start: register the device

Log in to People as a hospital admin and go to HR → Devices → Register device.
Fill in the name/location, your vendor/model (free text), and the connection type.
Choose how the device identifies employees (see below).
Click Register device — a device key (starts with zdk_) is shown once. Copy and store it safely; use Rotate key if you ever lose it.

🔑 The device key is a password. Anyone holding it can submit attendance for your hospital. Don't share it by email; rotate it immediately if exposed.

How the device identifies employees

Option	How it works	When to choose it
Employee code (recommended)	When enrolling a fingerprint on the terminal, set the person's user ID to their ZenoHosp employee code	You control enrollment IDs on the device
Biometric enrollment ID	The terminal assigns its own numbers. Enter each employee's number in People: Employees → edit → Biometric enrollment ID	The device manages its own numbering

If a punch arrives with an unknown ID it is not lost — it is recorded as unresolved so you can fix the mapping and re-send.

Route A — Direct push

If your terminal supports an HTTP push / webhook / "cloud server" setting (for example ZKTeco ADMS, or your vendor's middleware), point it at:

POST https://api-people.zenohosp.com/api/device/attendance/punch
Header:  X-Device-Key: zdk_your_device_key
Header:  Content-Type: application/json

Request body — one or many punches per request:

{
  "punches": [
    {
      "identifier": "ABC-EMP-2026-0001",
      "timestamp": "2026-07-19T09:03:11+05:30",
      "direction": "in",
      "eventId": "terminal7-000123"
    }
  ]
}

Field	Required	Meaning
`identifier`	Yes	Employee code or enrollment ID (per the device's setting)
`timestamp`	Yes	Punch time, ISO-8601 with timezone offset. A bare time is treated as IST
`direction`	Optional	`"in"` or `"out"`. Omit if your device doesn't track direction — People infers it
`eventId`	Recommended	The terminal's own record ID — guarantees retries are never double-counted

The response reports what happened to each punch (applied, duplicate, unresolved, rejected). Retries are safe — if the network drops, send the same batch again and duplicates are skipped automatically.

Route B — Connector agent (LAN-only devices)

Most budget terminals sit on the hospital LAN and can't reach the internet. The connector agent is a small program you run on any always-on PC on the same network. It reads punches from the terminal and pushes them to the same address as Route A.

We provide a ready-made agent for the ZKTeco / eSSL family — ask ZenoHosp support for the attendance-agent package. The agent polls the terminal, buffers punches locally if the internet is down and re-sends them later (nothing lost, nothing double-counted), and can be set to start automatically with the PC. For other brands, any integrator can adapt it: it only has to read the terminal and POST the JSON shown in Route A.

Route C — File import (no networking at all)

Every terminal can export its punch log (usually CSV via USB or the vendor's PC software). Register a device of type CSV / log import and paste a column mapping that describes your file's layout. Example — for a file like:

employee_code,timestamp,direction
ABC-EMP-2026-0001,2026-07-19 09:31:00,IN
ABC-EMP-2026-0001,2026-07-19 17:37:00,OUT

use this mapping (columns counted from 0):

{
  "delimiter": ",",
  "hasHeader": true,
  "identifierColumn": 0,
  "timestampColumn": 1,
  "timestampFormat": "yyyy-MM-dd HH:mm:ss",
  "timezone": "Asia/Kolkata",
  "directionColumn": 2,
  "directionInValues": ["IN", "0"],
  "directionOutValues": ["OUT", "1"]
}

Adjust the column numbers, date format and IN/OUT words to match your device's export. If your file has no direction column, simply omit those three lines.

Then go to HR → Import Logs, choose the device and file, and click Import. Re-uploading the same file is harmless — already-imported punches are skipped — so a weekly "export everything, upload everything" routine works perfectly.

Verify it's working

Employee view — My Attendance shows today's session with in/out times; multiple sessions appear as a numbered list.
Admin view — HR → Attendance shows Present with a device (or imported) badge.
Hours — the day's hours equal the sum of all sessions and flow into payroll automatically.
Suite-wide status — after a live punch-in, the employee shows as checked in across all ZenoHosp apps.

Troubleshooting

Symptom	Meaning	Fix
`HTTP 401`	Wrong, missing, or deactivated device key	Check the `X-Device-Key` header; rotate the key if lost; check the device is Active
`unresolved`	The ID didn't match any employee	Check the device's "identifies by" setting; fill the employee's Biometric enrollment ID or enroll them by employee code, then re-send
`duplicate`	Punch already received earlier	Nothing to do — this is the double-count protection working
`rejected` — bad timestamp	Date format didn't parse	Send ISO-8601 (Routes A/B) or fix `timestampFormat` in the mapping (Route C)
`rejected` — future timestamp	Terminal clock is ahead	Set the terminal's date/time (punches over 5 min in the future are refused)
Employee forgot to punch out	Session left open	Closed automatically overnight (capped and flagged for review); admins can correct the day in HR → Attendance

Security

One key per terminal — a lost key affects only that device.
Rotate on staff change and whenever a key may have been exposed.
Instant revoke — deactivating a device blocks its key immediately.
A device key can only submit attendance for your own hospital — it grants no access to any other data.

Buying advice

Any terminal works, but these make setup easier: push/webhook or "cloud server" support (e.g. ZKTeco with ADMS) lets you use Route A with no extra software; Ethernet/Wi-Fi with a vendor SDK (ZKTeco/eSSL family) works with our ready-made agent; at minimum, CSV export means Route C always works. If in doubt, share the model you're considering with ZenoHosp support before purchasing and we'll confirm the best route.