PunchDesk Attendance API

Connect HR software, dashboards and other systems using a separate API key for each integration.

1. Create a key

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.

2. Authenticate

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.

Contractual staffing dashboard

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.

3. Request attendance

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.

4. Current attendance and occupancy

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.

Limits and errors

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.

Download OpenAPI specification ยท Open API integrations