EntryLuma integration API
Developer guide 1.1 · checked against EntryLuma server 2.2.14 source · 4 November 2026
Build a manufacturer-specific adapter that turns confirmed biometric/access authentication into EntryLuma's normalised events. The cloud receiver is not tied to Hikvision. EntryLuma manages organisations, branches, People, recipients, message layouts and downstream delivery. This guide describes the existing API; it does not add new endpoints or certify another manufacturer's hardware.
1. Architecture and responsibilities
Reader / vendor platform → vendor adapter or local connector → HTTPS EntryLuma event receiver → attendance record → eligible notification jobs → delivery workers → recipients.
The adapter owns vendor SDK/API authentication, successful-event mapping, real reader identity checks, clock conversion, event/photo correlation, a durable local outbox and reconnect/retry behaviour. EntryLuma owns tenant/branch assignment, person lookup, recipient settings, templates, cooldowns, queues, reports and security/health alerts. A vendor cloud service can implement the adapter remotely if its API permits; a local PC is needed only when the reader can be reached or monitored only on the premises. Do not expose a LAN reader directly to the internet.
The supplied Python connector is a working Hikvision reference, not a generic SDK for every brand. Reuse its transport/outbox ideas or write your own service in any language. Vendor-specific access may use HTTP push, event stream, polling, a licensed SDK or a vendor cloud webhook. Support depends on the exact model/firmware and the vendor's actual API.
2. Onboarding checklist
- Obtain authorisation from the organisation and the API/operator contact.
- Create the organisation, branch and device in EntryLuma. Register the actual reader serial and, when available, reader MAC. Allocate one device credential per reader; do not share one across branches.
- Create/import People in the portal under that branch. Store the vendor's person identifier as a string, preserving leading zeros. Names and recipient phone/email/channel come from these portal records.
- Retrieve the DEVICE upload credential from the device upload configuration using the authorised portal account. It is 64 lowercase hexadecimal characters. Keep it in protected storage. It is NOT a portal password, reader password or messaging API key.
- Configure branch recipient switches, event types and delivery channels. Configure the organisation messaging integration and/or SMTP. Workers must run for outbound delivery.
- Commission one real successful scan on a test person with known recipients, then test duplicate/retry, offline recovery, health and optional photos before rollout.
A device credential maps to one registered device and therefore one branch/organisation. Do not send tenant_id or branch_id to choose a customer. A different branch needs a separately registered device/credential. Notification numbers cannot be selected by adding them to an event.
3. API location and authentication
Production base URL:
https://www.entryluma.com/api/v1/attendanceUse the final HTTPS www URL directly. Do not depend on HTTP→HTTPS, www or path redirects for credential-bearing requests. Clients should refuse redirects and validate TLS certificates. New attendance integrations use /api/v1/attendance/. Use the configured endpoint on private or staging deployments. The dashboard remains the portal, and policy-provided logo URLs may still point there.
X-Device-Token: <64-lowercase-hex-device-credential>
Content-Type: application/json
Accept: application/jsonThe header is the supported choice for new integrations. A legacy query-key option exists on the event receiver only; do not use it in new clients because URLs are readily logged. Heartbeat, policy and logo requests require the header. Browser/portal session cookies are not required. These endpoints are intended for trusted backend/connector clients; no browser CORS contract is provided.
4. Submit an attendance event
POST /api/v1/attendance/webhook.phpBody limit: 131072 bytes (128 KiB). One event per request; no bulk-array or direct multipart-image input.
{
"event_id": "8a3b9a1ce16a3e8ae2390b6e936f40bfca289c5dbe00884d8db7b3b50b32aa11",
"device_serial": "ACME-READER-001",
"macAddress": "02:00:00:00:00:01",
"person_id": "00000001",
"occurred_at": "2026-10-27T10:00:00+08:00",
"event_type": "check_in",
"method": "fingerprint",
"verified": true
}Canonical integrator fields
| Field | Contract |
|---|---|
| event_id | Use a stable 64-character lowercase SHA-256 identifier for every physical authentication event. Derive it from reader identity + vendor's stable event identifier/epoch. Never generate a new ID on retry. The photo flow specifically requires 64 lowercase hex characters. |
| device_serial | Exact registered reader serial; mandatory for the integrator profile and for heartbeat/photo policy. The current legacy event parser tolerates an omitted serial, but that is not a compliant new integration. |
| macAddress | Optional actual reader MAC. If registered and supplied, it must match (case-insensitive). This is not the connector PC MAC. |
| person_id | Nonempty string, max 80 characters; must match an active Person in the credential's branch. "1" and "00000001" are different IDs. |
| occurred_at | Original scan time, ISO 8601 with timezone, e.g. +08:00 or Z. Fractional seconds are accepted; storage normalises to UTC whole seconds. Do not replace it with upload/retry time. |
| event_type | check_in, check_out, break_in, break_out, overtime_in or overtime_out. Bare "ot" is not recognised. Map vendor attendance states deliberately. |
| method | Report the confirmed method, e.g. fingerprint, face, card or pin. Current text-event parsing accepts other strings, but the current captured-photo policy only enables face/fingerprint. |
| verified | JSON boolean true only after the vendor confirms successful person authentication. The string "true" and integer 1 do not count. A generic door opening, alarm or failed scan is not a successful person event. |
| photo_receipt | Optional opaque receipt from the photo workflow, attached to the same immutable event before first attendance submission. Do not send an enrolment photo, arbitrary photo URL or image base64 here. |
The OpenAPI file expresses this recommended canonical profile, which is deliberately stricter than the legacy parser. Legacy Hikvision/XML aliases remain in the server but other manufacturers should use the flat JSON fields above. Unknown fields do not become recipient/message settings. Do not send fingerprint templates, facial feature vectors, reader passwords or enrolment biometric data.
Response and its meaning
{"accepted": true, "status": "recorded", "event_id": 123}The response event_id is the server's numeric record ID, NOT the submitted event_id. Store the submitted identifier separately. On duplicate, no server ID is returned by the current implementation.
| HTTP / status | Meaning / client action |
|---|---|
| 200 recorded | Attendance was recorded. Eligible jobs may have been created. Not a messaging-service or recipient-delivery confirmation. |
| 200 duplicate | Same event already received; stop retrying. No additional attendance/notification is created for this retry. |
| 200 historical | A recognised event is older than configured notification_max_age_hours (default 24h). It is logged without outbound notification. |
| 200 unknown_person | No active matching Person in the branch. Preserve for review/correct portal records; do not retry forever. |
| 200 unverified | verified was not the boolean true. Logged without attendance notification. Correct vendor success mapping. |
| 200 unknown_type | Unsupported event type. Correct mapping; do not assume "recorded" from accepted=true. |
| 200 future_clock | Scan is over five minutes ahead of server time. Correct reader/adapter clock. |
| 200 needs_adapter | Body/type could not be normalised; only inbound request logged. Response contains inbound_id. Investigate Logs; this is NOT successful attendance. |
| 409 identity_mismatch | Supplied serial/MAC conflicts with credential's reader. Stop uploads and review registration/credential. A security email may be queued. |
| 409 branch_archived | Branch became inactive during processing. Correct portal state; normally an inactive branch is rejected during credential lookup with 401. |
| 401 | Invalid token format/credential or disabled device/branch/organisation. Do not loop aggressively; fix credentials/configuration. |
| 405 | Wrong HTTP method. Use POST. |
| 413 | Request exceeds 128 KiB. Do not embed pictures. |
| 500 | Temporary receiver failure. Persist and retry the SAME event with bounded backoff. |
For unknown statuses, malformed/HTML responses or redirects: preserve the event for review instead of treating it as delivered. If a proxy returns 429, respect Retry-After and back off. No universal 300/min or other ingestion rate entitlement is defined by this release. Start conservatively and agree throughput with the operator; messaging-provider rate limits are a separate service contract.
Deduplication and immutable retries
With a nonempty event_id, the server deduplication key is derived from registered device ID + submitted event_id + UTC timestamp (normalised to seconds). Therefore IDs must be unique to the real reader event, and its time, person and content must remain stable on retries. Do not reuse a vendor sequence after a reader reset without adding a stable boot/sequence epoch. Never change IDs to force notification resending.
Without an event ID, the legacy parser falls back to person/time/type/method; new integrations should always provide one. The notification cooldown (default 60 seconds for the same person/type/branch) is separate: distinct scans can be recorded while repeat messages are suppressed. Sending several recipients creates separate delivery jobs.
5. Connector heartbeat
POST /api/v1/attendance/heartbeat.phpBody limit: 8192 bytes. Send approximately every 30–60 seconds even when there are no new scans, provided forwarding is enabled. Do not fake a connected state when the reader cannot be reached. The supplied connector uses a 30-second interval. No heartbeat request sends attendance or a parent notification itself.
{
"device_serial": "ACME-READER-001",
"connector_version": "acme-1.0.0",
"reader_state": "connected",
"pending": 0,
"blocked": 0,
"review": 0,
"oldest_pending_age": 0,
"installation_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}- device_serial: exact registered serial, required.
- connector_version: 1–30 ASCII letters, numbers, dot, underscore or hyphen.
- reader_state: checking, connected, disconnected or authentication_error.
- pending, blocked, review, oldest_pending_age: required JSON integers from 0 to 31536000; oldest_pending_age is seconds (0 when no pending event).
- installation_id: optional persistent random 64 lowercase hex characters. Generate once per installation, not every heartbeat. It enables advisory identifier-change alerts after baseline; it is not an activation secret or proof of hardware identity. Copies can carry the same ID.
Success: 200 {"accepted":true}. Errors: 400 invalid JSON/identity/state/statistics, 401 invalid credential, 405 wrong method, 413 too large, 415 non-JSON content type, 503 storage unavailable. Unknown installation_id values are ignored unless they match the expected optional format. Snapshots are throttled to at most one update every five seconds; do not flood.
The current portal marks the connector offline after 180 seconds without a heartbeat. Reader/queue conditions have their own monitoring grace. Server health-monitor cron and enabled alert delivery must be configured; heartbeat alone does not send alerts. In capture-only/test mode, follow the supplied connector's no-portal-traffic behaviour unless a separate operator-approved diagnostics mode is used.
6. Optional authentication photos
This is a separate workflow, not a JPEG posted to webhook.php. Text-only and fingerprint-only integrations can omit it completely. The server photo bridge/media service must be configured, and branch/recipient/template policy must permit the image.
Order of operations
- Capture a confirmed authentication event and the photo belonging to THAT event. Persist the event and image locally while pending. Never substitute an enrolment portrait or the most recent unrelated photo.
- POST the normalised event to photo-policy.php using X-Device-Token (body max 16384 bytes). This does not record attendance.
- If enabled=false, continue with the normal attendance POST without photo_receipt. The reason may be generic: bridge disabled, branch mode, unsupported method, old event, missing Person, paused integration or recipients.
- If enabled=true, use its mode, upload_url, opaque grant and optional logo_url. The event must have a 64-hex ID, exact device serial, face/fingerprint method, verified=true, and a timestamp within 24 hours. Portal checks are policy, not hardware attestation.
- For capture_logo and an available logo_url, GET it with X-Device-Token. Validate the logo URL has the SAME HTTPS origin as the portal before sending the device credential. If it does not match (including www), or cannot be fetched/decoded, keep the captured photo without a logo.
- Compose a single JPEG. The reference layout preserves the capture and places a larger, aspect-preserved logo in a white header ABOVE the photo. No PC-side manually configured logo is needed. Strip metadata, bound pixel count/bytes and use only a decodable JPEG output. Reference client accepts JPEG/PNG source captures but uploads JPEG.
- POST raw JPEG bytes to the policy's upload_url with Content-Type: image/jpeg and Authorization: Bearer <grant>. On EntryLuma-hosted deployments this is /api/v1/attendance/photo-upload.php. Use the policy-provided URL for your deployment and do not send X-Device-Token with the JPEG. Treat the grant as opaque: do not decrypt or log it. Only trust a media endpoint approved in your deployment configuration; refuse redirects/TLS downgrade. Do not hard-code a vendor messaging URL.
- Require a success=true response with an opaque receipt, and persist it BEFORE submitting attendance. Add photo_receipt to the original event and POST that event to webhook.php.
- Retain the same receipt for uncertain attendance retries; do not upload/charge again just to retry an event. If photo preparation fails, follow the reference text fallback for attendance. Clean up local captures with bounded retention after the attempted upload; never delete all unsent jobs to clean disk.
Enabled policy response shape:
{
"enabled": true,
"mode": "capture_logo",
"retention_limit": 100,
"upload_url": "https://www.entryluma.com/api/v1/attendance/photo-upload.php",
"grant": "OPAQUE_SHORT_LIVED_GRANT",
"logo_url": "https://www.entryluma.com/dashboard/connector-logo.php"
}Disabled response: 200 {"enabled":false,"reason":"Photos disabled; attendance continues without a captured image."}. Invalid policy requests/credentials use 400 with enabled=false; too large uses 413 and wrong method 405. Policy expiry is approximately five minutes in current code; get a fresh policy if it expires BEFORE upload. Do not change the event ID/person to obtain another grant. Media upload accepts decodable JPEG up to 2097152 bytes (2 MiB), current maximum 1920 pixels on either side and 3 million total pixels; success returns {"success":true,"receipt":"OPAQUE_RECEIPT"}. The EntryLuma upload endpoint returns 413 above 2 MiB, 405 for non-POST requests, or 400 for invalid grants or images. Treat the returned receipt as a bearer-like sensitive reference; keep it out of public logs.
The receipt is bound to organisation/device/event/person. An invalid or mismatched receipt is ignored for attendance-photo purposes; attendance can still be recorded with text fallback. First submitting text attendance and then retrying with a photo does NOT upgrade the existing notification: the retry is a duplicate. Complete the photo workflow first when an image is available.
Image storage is bounded by organisation retention (default 100 completed captures) and expiry rules; it is not a permanent photo archive. EntryLuma-hosted captures use private storage and expiring receipts. Recipient copies have independent retention. Branches can enable embedded pictures in eligible attendance emails independently of the WhatsApp layout. Eligible email can request a capture even when WhatsApp is paused or text only. Approved Meta image-header and fallback text templates must be configured by the portal account; the connector does not choose templates, senders or arbitrary recipients. Oversized captions can also force a text fallback (reference personal-media caption cap 1024 characters).
7. Reference connector design
- Separate vendor adapter from EntryLuma transport. Map only documented successful person events, not all alarms; determine check-in/out with operator policy when the reader does not report direction.
- Read and verify actual serial/MAC from the vendor API at connection/reconnection. A stable DHCP reservation is preferred; authenticate reader rediscovery by identity, not just its IP/name.
- Persist the exact event, source ID and original timestamp atomically before acknowledging a vendor push. Use a durable SQLite or equivalent outbox, with bounded pending capacity and rotated diagnostics.
- Transmit events serially or with an operator-approved bounded concurrency. Retry network/5xx/429 errors with jitter and a cap on retry frequency; halt for operator review on identity/auth/configuration errors. Review accepted-but-not-recorded statuses, not endless resubmission.
- Recover safely after power loss, reader restart or long outage. Old events may be logged as historical; do not replace timestamps to generate late alerts.
- Use one active instance per reader by default. OS boot service needs the same Python/SDK runtime and protected secrets as the foreground test. Windows Task Scheduler and Linux systemd setup are deployment details, not the HTTP protocol.
- Heartbeat reflects reader and local outbox health independently of downstream WhatsApp delivery. Keep secrets and biometric data out of ordinary logs. Trace vendor event ID → submitted event ID → numeric server record → portal notification job.
8. Security and scope boundaries
Current transport uses a bearer DEVICE credential over TLS. It is not a signed-event or TPM-attested protocol. Reader serial/MAC and installation ID checks help identify mismatches but can be imitated by modified software holding a copied credential. Do not claim this API proves physical presence or ownership of an enrolled fingerprint. Enrolment must be staff-controlled. Rotate/revoke compromised tokens through the portal.
No public API in this release creates organisations, branches, devices or People; changes to recipients use authorised portal/import workflows. No documented device-token API fetches the full People list, changes thresholds, checks account credits, selects notification numbers, or reads WhatsApp delivery receipts. A separate future partner-management API would need scoped credentials/permissions. Do not automate dashboard forms as a substitute for a promised REST API.
Account login lockouts and new-browser alerts concern PORTAL accounts, not successful biometric events. Per-organisation usage-warning thresholds send emails and do not stop uploads. Event-volume counts include stored event records awaiting review, not only successful check-ins; duplicate retries and needs_adapter-only inbound logs do not create a new event record. Do not interpret a warning threshold as an API request allowance or billing cap.
9. Quick-start examples
examples/event.json is a fictional format example; replace serial/person/source/time with a real authorised test event. Old fixed dates will become historical. examples/submit_event.py is dry-run by default and has no dependencies beyond Python 3.11+. It generates a deterministic event ID and refuses redirects, but is NOT a production outbox/heartbeat/photo adapter.
python3 examples/submit_event.py --serial ACME-READER-001 --person-id 00000001 --source-event-id vendor-sequence-991 --occurred-at 2026-10-27T10:00:00+08:00For a real authorised test, set ENTRYLUMA_DEVICE_TOKEN privately, add --send --confirmed-success, and use the ORIGINAL current scan time. It can queue real outbound messages. Never commit the token. The Postman collection has an empty device_token variable by default; use a local secret value, do not export/share a filled collection. All event/sample data is fictional.
A manual HTTP request, after privately setting ENTRYLUMA_DEVICE_TOKEN:
curl --max-time 20 --request POST \
'https://www.entryluma.com/api/v1/attendance/webhook.php' \
--header "X-Device-Token: $ENTRYLUMA_DEVICE_TOKEN" \
--header 'Content-Type: application/json' \
--data-binary @examples/event.jsonDo not add -L or -k. curl examples are Unix shell syntax; in PowerShell use curl.exe and $env:ENTRYLUMA_DEVICE_TOKEN. Avoid putting literal tokens in shell history/process commands. Read full JSON status, then review portal attendance and delivery logs.
10. Integrator acceptance checklist
- Right credential maps to the authorised branch; wrong/rotated credential is rejected.
- Known Person ID with leading zeros matches; unknown Person is reviewed, not silently discarded.
- Door open/failure/alarm is filtered; check-in/check-out and method mapping are confirmed with real hardware.
- Duplicate SAME ID/time creates no second attendance or notification. Reader sequence resets cannot collide.
- Offline/reboot recovery preserves exact payload/timestamp; old backlog does not create fresh alerts.
- Clock offsets/future events and invalid JSON/type/oversized input are handled.
- Heartbeats update the expected device and show disconnection/authentication failure honestly.
- Photo is linked to that authentication, not enrolment; capture-only, capture+logo and no-photo fallback work.
- Notification recipient switches, cooldowns, templates and workers are verified; receiving 200 recorded is not the final delivery test.
- No credentials, face templates or production personal data are in exported diagnostics/examples.
Downloads and next steps
Download the OpenAPI definition, Postman collection, Markdown guide or EntryLuma developer kit. Portal provisioning requires an authorised account. Commission integrations against a test branch and confirm final notification delivery. For a compatibility discussion, contact the EntryLuma team.
