Connect HR software, dashboards and other systems using a separate API key for each integration.
Sign in as an unrestricted administrator, open API integrations, select Create API key, name the integration and select its allowed locations. Optionally set an expiry date. Save the one-time key in your server-side secret store. You can edit its locations, rotate it or revoke it here. Expiry dates end at 23:59:59 IST.
curl 'https://punchdesk.in/api/v1/locations' \ -H "Authorization: Bearer $PUNCHDESK_API_KEY"
Send the key in the Authorization header, never in a URL. These endpoints are read-only and do not accept browser session cookies. Call from your backend; cross-origin browser access is not enabled.
curl 'https://punchdesk.in/api/v1/contract-staffing?location_id=2' \ -H "Authorization: Bearer $PUNCHDESK_API_KEY"
The location directory includes contractual_enabled (0 or 1).
This endpoint returns enabled locations within the key's scope; omit
location_id for all permitted locations. Disabled locations
return an empty array. Unknown query parameters are rejected.
requirements lists every recurring role/shift and its active
status, scheduled start/end, coverage end, required headcount, estimated
present contributors and shortfall. required, covered
and shortfall sum active shifts; covered positions are capped per
shift. people counts distinct active-shift contributors.
attendance.present and attendance.absent list today's
active employees with or without attendance punches, including holidays and
leave. They are daily totals, separate from shift coverage. Each employee
includes roles, punch count and first/last punch. All timestamps are ISO 8601
UTC; shift clocks and the attendance day use IST. Refresh every 30 seconds.
Coverage uses the same rules as PunchDesk: 30-minute early-arrival and late-finish allowances, capped at the next same-role shift. Single-role workers do not carry over to another shift. Multi-role workers need a fresh punch for another shift. Requirements apply daily, including holidays. Undirected punches cannot confirm early departures or physical occupancy.
curl 'https://punchdesk.in/api/v1/attendance?from=2026-10-01&to=2026-10-25&page=1&page_size=100' \ -H "Authorization: Bearer $PUNCHDESK_API_KEY"
Dates are inclusive calendar dates in Asia/Kolkata. Maximum range: 366
days; maximum report: 200,000 employee-days. Add
location_id=123 to filter an allowed location, or omit it to
include all permitted locations. Unassigned locations return 403. Active
employees are included by default; add
include_inactive=true for current inactive employees.
The response contains data (daily records),
totals, by_date,
employees (per-employee summaries), and meta.
Iterate pages 1 through meta.total_pages; page_size defaults
to 100, maximum 500. Totals and employee summaries repeat on each page: do
not sum them again.
Each daily record includes employee ID/code/name, location ID/name, date, presence, exception/status, punch count, first_in, last_out, span_hours, leave_type and provisional. Times are ISO 8601 UTC, including Z; null means unavailable. Span measures first-to-last elapsed time, not paid working hours.
Totals are employee-days: one employee present over five dates contributes five. Presence categories follow PunchDesk reports: Holiday takes precedence, then Present, Leave, Upcoming and Absent. Punches on holidays remain visible but count as Holiday in historical totals. Approved leave must have been entered in PunchDesk. Today's absence means no punch yet, and is provisional. Future dates are Upcoming except scheduled holidays or recorded leave.
The roster uses current employee locations, active status and current weekly holiday settings. Employment start/end dates and historical location assignments are not available, so do not interpret earlier absent days as verified employment or payroll deductions.
curl 'https://punchdesk.in/api/v1/presence?page=1&page_size=100' \ -H "Authorization: Bearer $PUNCHDESK_API_KEY"
This endpoint uses today in IST and active employees. Optional location_id, page and page_size work as above. Counts cover all filtered employees, even when data is paginated.
| Field | Meaning |
|---|---|
| present_today | Employees with attendance punches today, including holidays |
| absent / on_leave / holiday | Today's attendance classification; absence is provisional |
| in_office / out | Latest unambiguous directional punch today is check-in / check-out |
| unknown | First/last inference or conflicting punch evidence cannot establish direction |
| no_punch | No attendance evidence today; this does not prove the employee is outside |
Rows contain office_status, last_punch_at and recorded_leave alongside attendance data. Attendance and occupancy counts overlap and should not be added together. Recorded leave with punches is flagged and remains Present.
First/last-punch locations always return unknown occupancy for punched
employees. A first/last pair is not evidence of a directional checkout.
Counts are based on today's uploaded punches: missing checkouts, overnight
work, clock skew or delayed device uploads can make occupancy inaccurate.
devices[].last_seen_at and
meta.generated_at provide freshness context; last-seen is
receiver activity, not proof all records have arrived.
60 requests/minute per API key and 120/minute per IP, per application process. Poll no faster than every 30 seconds and back off on 429. Responses include rate-limit headers. Revocation, rotation and scope edits apply to subsequent requests; in-flight responses may finish.
| Status | Meaning |
|---|---|
| 400 | Invalid dates, filters, pagination or report too large |
| 401 | Missing, invalid, expired or revoked key |
| 403 | Location not allowed or no remaining assigned locations |
| 404 / 405 | Unknown endpoint / unsupported method |
| 429 | Rate limit; respect Retry-After |
| 500 | Temporary server failure; retry with backoff |
Errors use {"error":"message"}. Keys cannot manage employees,
leave, devices, users or other keys. Raw device payloads, leave notes,
phone numbers and biometric images are not exposed.