Attendance API

15 endpoints, generated from packages/core/openapi/v1.snapshot.json (OpenAPI 3.1.0, contract version 1.0). Conventions for lists, errors, money and authentication are on the API conventions page.

POST/api/v1/attendance/corrections

Add a missing punch to someone's timesheet, with a reason (audited)

Access

Permission attendance:update

Request body

application/json, object, required

• employeeIdstring (uuid)required
• kindenumrequired

  one of "in", "out"

• timestring (date-time)required
• reasonstringrequired

  min length 3 · max length 300

Responses

201 Success. object

• idstring (uuid)required
• employeeIdstring (uuid)required
• kindenumrequired

  one of "in", "out"

• sourceenumrequired

  one of "web", "mobile_web", "ios", "android", "correction"

• deviceTimestringrequired
• sentAtstringrequired
• serverTimestringrequired
• recordedAtstringrequired
• workDatestringrequired
• skewSecondsnumberrequired
• queuedbooleanrequired
• statusenumrequired

  one of "accepted", "flagged"

• flagsarray of enumrequired
• locationobject or nullrequired

  • latitudenumberrequired
  • longitudenumberrequired
  • accuracyMetresnumber | nullrequired
• reasonstring | nullrequired
• voidedbooleanrequired
• voidReasonstring | nullrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required, self_change_requires_approval
• 404 not_found

GET/api/v1/attendance/me

Clock-in status: today's punches, whether you are clocked in, and the location notice

Access

Any signed-in member (own data only)

Responses

200 Success. object

• employeeIdstring (uuid) or nullrequired
• serverTimestringrequired
• clockedInbooleanrequired
• lastPunchobject or nullrequired

  • idstring (uuid)required
  • employeeIdstring (uuid)required
  • kindenumrequired

    one of "in", "out"

  • sourceenumrequired

    one of "web", "mobile_web", "ios", "android", "correction"

  • deviceTimestringrequired
  • sentAtstringrequired
  • serverTimestringrequired
  • recordedAtstringrequired
  • workDatestringrequired
  • skewSecondsnumberrequired
  • queuedbooleanrequired
  • statusenumrequired

    one of "accepted", "flagged"

  • flagsarray of enumrequired
  • locationobject or nullrequired

    • latitudenumberrequired
    • longitudenumberrequired
    • accuracyMetresnumber | nullrequired
  • reasonstring | nullrequired
  • voidedbooleanrequired
  • voidReasonstring | nullrequired
• todayarray of objectrequired

  • idstring (uuid)required
  • employeeIdstring (uuid)required
  • kindenumrequired

    one of "in", "out"

  • sourceenumrequired

    one of "web", "mobile_web", "ios", "android", "correction"

  • deviceTimestringrequired
  • sentAtstringrequired
  • serverTimestringrequired
  • recordedAtstringrequired
  • workDatestringrequired
  • skewSecondsnumberrequired
  • queuedbooleanrequired
  • statusenumrequired

    one of "accepted", "flagged"

  • flagsarray of enumrequired
  • locationobject or nullrequired

    • latitudenumberrequired
    • longitudenumberrequired
    • accuracyMetresnumber | nullrequired
  • reasonstring | nullrequired
  • voidedbooleanrequired
  • voidReasonstring | nullrequired
• locationobjectrequired

  • modeenumrequired

    one of "off", "optional", "required"

  • pdpaNoticestring | nullrequired
  • officesarray of objectrequired

    • namestringrequired
    • radiusMetresnumberrequired
• networkRestrictedbooleanrequired

• 401 session_expired, session_revoked, unauthenticated
• 403 mfa_enrolment_required

GET/api/v1/attendance/overtime

List overtime claims you can see

Access

Permission attendance:read

Parameters

Name	In	Type	Required
employeeId	query	string (uuid)	no
from	query	string	no
to	query	string	no
status	query	enum	no

Responses

200 Success. object

• itemsarray of objectrequired

  • idstring (uuid)required
  • employeeobjectrequired

    • idstring (uuid)required
    • namestringrequired
  • datestringrequired
  • computedMinutesnumberrequired
  • claimedMinutesnumberrequired
  • approvedMinutesnumber | nullrequired
  • statutorybooleanrequired
  • reasonstring | nullrequired
  • statusenumrequired

    one of "pending", "approved", "rejected", "withdrawn"

  • approvalRequestIdstring (uuid) or nullrequired
  • createdAtstringrequired
  • decidedAtstring | nullrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required

POST/api/v1/attendance/overtime

Claim overtime for a day (up to the timesheet's OT; warns past 72 hours a month)

Access

Permission attendance:create

Request body

application/json, object, required

• employeeIdstring (uuid)
• datestringrequired
• minutesintegerrequired

  min 1 · max 1440

• reasonstring or null

  max length 300

Responses

201 Success. object

• claimobjectrequired

  • idstring (uuid)required
  • employeeobjectrequired

    • idstring (uuid)required
    • namestringrequired
  • datestringrequired
  • computedMinutesnumberrequired
  • claimedMinutesnumberrequired
  • approvedMinutesnumber | nullrequired
  • statutorybooleanrequired
  • reasonstring | nullrequired
  • statusenumrequired

    one of "pending", "approved", "rejected", "withdrawn"

  • approvalRequestIdstring (uuid) or nullrequired
  • createdAtstringrequired
  • decidedAtstring | nullrequired
• warningsarray of stringrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found
• 409 conflict

GET/api/v1/attendance/overtime/{id}

Get an overtime claim

Access

Permission attendance:read

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• idstring (uuid)required
• employeeobjectrequired

  • idstring (uuid)required
  • namestringrequired
• datestringrequired
• computedMinutesnumberrequired
• claimedMinutesnumberrequired
• approvedMinutesnumber | nullrequired
• statutorybooleanrequired
• reasonstring | nullrequired
• statusenumrequired

  one of "pending", "approved", "rejected", "withdrawn"

• approvalRequestIdstring (uuid) or nullrequired
• createdAtstringrequired
• decidedAtstring | nullrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required
• 404 not_found

POST/api/v1/attendance/overtime/{id}/withdraw

Withdraw a pending overtime claim

Access

Permission attendance:create

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• idstring (uuid)required
• employeeobjectrequired

  • idstring (uuid)required
  • namestringrequired
• datestringrequired
• computedMinutesnumberrequired
• claimedMinutesnumberrequired
• approvedMinutesnumber | nullrequired
• statutorybooleanrequired
• reasonstring | nullrequired
• statusenumrequired

  one of "pending", "approved", "rejected", "withdrawn"

• approvalRequestIdstring (uuid) or nullrequired
• createdAtstringrequired
• decidedAtstring | nullrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found
• 409 conflict

GET/api/v1/attendance/payroll-overtime

Approved overtime per claim for a pay period (payroll's OvertimeSource)

Access

Permission payroll:read

Parameters

Name	In	Type	Required
periodStart	query	string	yes
periodEnd	query	string	yes

Responses

200 Success. object

• itemsarray of objectrequired

  • sourceIdstring (uuid)required
  • employeeIdstring (uuid)required
  • minutesnumberrequired
  • periodStartstringrequired
  • periodEndstringrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required

POST/api/v1/attendance/punches

Clock in or out (idempotent: a retried key returns the original punch with 200)

Send `deviceTime` (the tap) and `sentAt` (device clock when sending). The server records its own time and the corrected time, and flags clock skew and late sync. Queued offline punches are sent in order with `queued: true`.

Access

Permission attendance:create

Request body

application/json, object, required

• kindenumrequired

  one of "in", "out"

• idempotencyKeystringrequired

  min length 8 · max length 100

• deviceTimestring (date-time)required
• sentAtstring (date-time)required
• queuedboolean

  default false

• sourceenum

  one of "web", "mobile_web", "ios", "android" · default "web"

• elapsedMsinteger

  Native apps: milliseconds between the tap and sending, from the device's monotonic clock. Leave out if the device restarted in between.

  min 0 · max 691200000

• locationobject or null

  • latitudenumberrequired

    min -90 · max 90

  • longitudenumberrequired

    min -180 · max 180

  • accuracyMetresnumber

    min 0 · max 100000

Responses

200 Success. object

• idstring (uuid)required
• employeeIdstring (uuid)required
• kindenumrequired

  one of "in", "out"

• sourceenumrequired

  one of "web", "mobile_web", "ios", "android", "correction"

• deviceTimestringrequired
• sentAtstringrequired
• serverTimestringrequired
• recordedAtstringrequired
• workDatestringrequired
• skewSecondsnumberrequired
• queuedbooleanrequired
• statusenumrequired

  one of "accepted", "flagged"

• flagsarray of enumrequired
• locationobject or nullrequired

  • latitudenumberrequired
  • longitudenumberrequired
  • accuracyMetresnumber | nullrequired
• reasonstring | nullrequired
• voidedbooleanrequired
• voidReasonstring | nullrequired
• replayedbooleanrequired

201 Success. object

• idstring (uuid)required
• employeeIdstring (uuid)required
• kindenumrequired

  one of "in", "out"

• sourceenumrequired

  one of "web", "mobile_web", "ios", "android", "correction"

• deviceTimestringrequired
• sentAtstringrequired
• serverTimestringrequired
• recordedAtstringrequired
• workDatestringrequired
• skewSecondsnumberrequired
• queuedbooleanrequired
• statusenumrequired

  one of "accepted", "flagged"

• flagsarray of enumrequired
• locationobject or nullrequired

  • latitudenumberrequired
  • longitudenumberrequired
  • accuracyMetresnumber | nullrequired
• reasonstring | nullrequired
• voidedbooleanrequired
• voidReasonstring | nullrequired
• replayedbooleanrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 422 ip_not_allowed, outside_location, punch_rejected

POST/api/v1/attendance/punches/{id}/void

Void a wrong punch, with a reason (the original is kept; audited)

Access

Permission attendance:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Request body

application/json, object, required

• reasonstringrequired

  min length 3 · max length 300

Responses

200 Success. object

• idstring (uuid)required
• employeeIdstring (uuid)required
• kindenumrequired

  one of "in", "out"

• sourceenumrequired

  one of "web", "mobile_web", "ios", "android", "correction"

• deviceTimestringrequired
• sentAtstringrequired
• serverTimestringrequired
• recordedAtstringrequired
• workDatestringrequired
• skewSecondsnumberrequired
• queuedbooleanrequired
• statusenumrequired

  one of "accepted", "flagged"

• flagsarray of enumrequired
• locationobject or nullrequired

  • latitudenumberrequired
  • longitudenumberrequired
  • accuracyMetresnumber | nullrequired
• reasonstring | nullrequired
• voidedbooleanrequired
• voidReasonstring | nullrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required, self_change_requires_approval
• 404 not_found
• 409 conflict

GET/api/v1/attendance/reports/summary

Attendance summary per employee for a period (up to 62 days)

Access

Permission reports_attendance:read

Parameters

Name	In	Type	Required
from	query	string	yes
to	query	string	yes

Responses

200 Success. object

• itemsarray of objectrequired

  • employeeIdstring (uuid)required
  • namestringrequired
  • daysWorkednumberrequired
  • workedMinutesnumberrequired
  • lateCountnumberrequired
  • lateMinutesnumberrequired
  • earlyOutCountnumberrequired
  • missingPunchesnumberrequired
  • computedOtMinutesnumberrequired
  • approvedOtMinutesnumberrequired
  • leaveDaysnumberrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required

GET/api/v1/attendance/reports/summary.csv

Attendance summary as CSV

Access

Permission reports_attendance:export

Parameters

Name	In	Type	Required
from	query	string	yes
to	query	string	yes

Responses

200 CSV file text/csv

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required

GET/api/v1/attendance/settings

Attendance settings (location, offices, IP ranges, start time, grace, OT rounding)

Access

Permission policies:read

Responses

200 Success. object

• locationModeenumrequired

  one of "off", "optional", "required"

• officesarray of objectrequired

  • idstringrequired
  • namestringrequired
  • latitudenumberrequired
  • longitudenumberrequired
  • radiusMetresnumberrequired
• locationEnforcementenumrequired

  one of "flag", "block"

• allowedIpsarray of stringrequired
• ipEnforcementenumrequired

  one of "flag", "block"

• pdpaNoticestring or nullrequired

  max length 2000

• defaultStartTimestringrequired
• scheduleStartTimesobjectrequired
• breakMinutesintegerrequired

  min 0 · max 240

• lateGraceMinutesintegerrequired

  min 0 · max 120

• earlyOutGraceMinutesintegerrequired

  min 0 · max 120

• skewThresholdSecondsintegerrequired

  min 10 · max 3600

• otBlockMinutesintegerrequired

  min 1 · max 60

• otMinimumMinutesintegerrequired

  min 0 · max 240

• effectivePdpaNoticestringrequired

• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required

PUT/api/v1/attendance/settings

Update attendance settings

Access

Permission policies:update

Request body

application/json, object, required

• locationModeenumrequired

  one of "off", "optional", "required"

• officesarray of objectrequired

  • idstring

    min length 1 · max length 64

  • namestringrequired

    min length 1 · max length 80

  • latitudenumberrequired

    min -90 · max 90

  • longitudenumberrequired

    min -180 · max 180

  • radiusMetresintegerrequired

    min 20 · max 5000

• locationEnforcementenumrequired

  one of "flag", "block"

• allowedIpsarray of stringrequired
• ipEnforcementenumrequired

  one of "flag", "block"

• pdpaNoticestring or nullrequired

  max length 2000

• defaultStartTimestringrequired
• scheduleStartTimesobjectrequired
• breakMinutesintegerrequired

  min 0 · max 240

• lateGraceMinutesintegerrequired

  min 0 · max 120

• earlyOutGraceMinutesintegerrequired

  min 0 · max 120

• skewThresholdSecondsintegerrequired

  min 10 · max 3600

• otBlockMinutesintegerrequired

  min 1 · max 60

• otMinimumMinutesintegerrequired

  min 0 · max 240

Responses

200 Success. object

• locationModeenumrequired

  one of "off", "optional", "required"

• officesarray of objectrequired

  • idstringrequired
  • namestringrequired
  • latitudenumberrequired
  • longitudenumberrequired
  • radiusMetresnumberrequired
• locationEnforcementenumrequired

  one of "flag", "block"

• allowedIpsarray of stringrequired
• ipEnforcementenumrequired

  one of "flag", "block"

• pdpaNoticestring or nullrequired

  max length 2000

• defaultStartTimestringrequired
• scheduleStartTimesobjectrequired
• breakMinutesintegerrequired

  min 0 · max 240

• lateGraceMinutesintegerrequired

  min 0 · max 120

• earlyOutGraceMinutesintegerrequired

  min 0 · max 120

• skewThresholdSecondsintegerrequired

  min 10 · max 3600

• otBlockMinutesintegerrequired

  min 1 · max 60

• otMinimumMinutesintegerrequired

  min 0 · max 240

• effectivePdpaNoticestringrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required

GET/api/v1/attendance/team

Timesheets of everyone you can see (your reports; everyone for admins) over up to 31 days

Access

Permission attendance:read

Parameters

Name	In	Type	Required
from	query	string	yes
to	query	string	yes

Responses

200 Success. object

• itemsarray of objectrequired

  • employeeobjectrequired

    • idstring (uuid)required
    • namestringrequired
  • daysarray of objectrequired

    • datestringrequired
    • dayTypeenumrequired

      one of "working", "half", "off", "rest", "public_holiday", "leave", "shift", "not_employed"

    • holidaystring | nullrequired
    • leaveobject or nullrequired

      • sessionenumrequired

        one of "full", "am", "pm"

      • labelstringrequired
    • scheduledMinutesnumberrequired
    • scheduledStartstring | nullrequired
    • firstInstring | nullrequired
    • lastOutstring | nullrequired
    • workedMinutesnumberrequired
    • breakMinutesnumberrequired
    • lateMinutesnumberrequired
    • earlyOutMinutesnumberrequired
    • missingPunchesnumberrequired
    • openbooleanrequired
    • flagsarray of enumrequired
    • otMinutesnumberrequired
    • punchesarray of objectrequired

      • idstring (uuid)required
      • employeeIdstring (uuid)required
      • kindenumrequired

        one of "in", "out"

      • sourceenumrequired

        one of "web", "mobile_web", "ios", "android", "correction"

      • deviceTimestringrequired
      • sentAtstringrequired
      • serverTimestringrequired
      • recordedAtstringrequired
      • workDatestringrequired
      • skewSecondsnumberrequired
      • queuedbooleanrequired
      • statusenumrequired

        one of "accepted", "flagged"

      • flagsarray of enumrequired
      • locationobject or nullrequired

        • latitudenumberrequired
        • longitudenumberrequired
        • accuracyMetresnumber | nullrequired
      • reasonstring | nullrequired
      • voidedbooleanrequired
      • voidReasonstring | nullrequired
    • otClaimobject or nullrequired

      • idstring (uuid)required
      • statusenumrequired

        one of "pending", "approved", "rejected", "withdrawn"

      • claimedMinutesnumberrequired
      • approvedMinutesnumber | nullrequired
  • totalsobjectrequired

    • daysWorkednumberrequired
    • workedMinutesnumberrequired
    • lateCountnumberrequired
    • lateMinutesnumberrequired
    • earlyOutCountnumberrequired
    • missingPunchesnumberrequired
    • otMinutesnumberrequired
    • leaveDaysnumberrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required

GET/api/v1/attendance/timesheet

Daily timesheet for an employee (default: yours) over up to 62 days

Access

Permission attendance:read

Parameters

Name	In	Type	Required
employeeId	query	string (uuid)	no
from	query	string	yes
to	query	string	yes

Responses

200 Success. object

• employeeobjectrequired

  • idstring (uuid)required
  • namestringrequired
• daysarray of objectrequired

  • datestringrequired
  • dayTypeenumrequired

    one of "working", "half", "off", "rest", "public_holiday", "leave", "shift", "not_employed"

  • holidaystring | nullrequired
  • leaveobject or nullrequired

    • sessionenumrequired

      one of "full", "am", "pm"

    • labelstringrequired
  • scheduledMinutesnumberrequired
  • scheduledStartstring | nullrequired
  • firstInstring | nullrequired
  • lastOutstring | nullrequired
  • workedMinutesnumberrequired
  • breakMinutesnumberrequired
  • lateMinutesnumberrequired
  • earlyOutMinutesnumberrequired
  • missingPunchesnumberrequired
  • openbooleanrequired
  • flagsarray of enumrequired
  • otMinutesnumberrequired
  • punchesarray of objectrequired

    • idstring (uuid)required
    • employeeIdstring (uuid)required
    • kindenumrequired

      one of "in", "out"

    • sourceenumrequired

      one of "web", "mobile_web", "ios", "android", "correction"

    • deviceTimestringrequired
    • sentAtstringrequired
    • serverTimestringrequired
    • recordedAtstringrequired
    • workDatestringrequired
    • skewSecondsnumberrequired
    • queuedbooleanrequired
    • statusenumrequired

      one of "accepted", "flagged"

    • flagsarray of enumrequired
    • locationobject or nullrequired

      • latitudenumberrequired
      • longitudenumberrequired
      • accuracyMetresnumber | nullrequired
    • reasonstring | nullrequired
    • voidedbooleanrequired
    • voidReasonstring | nullrequired
  • otClaimobject or nullrequired

    • idstring (uuid)required
    • statusenumrequired

      one of "pending", "approved", "rejected", "withdrawn"

    • claimedMinutesnumberrequired
    • approvedMinutesnumber | nullrequired
• totalsobjectrequired

  • daysWorkednumberrequired
  • workedMinutesnumberrequired
  • lateCountnumberrequired
  • lateMinutesnumberrequired
  • earlyOutCountnumberrequired
  • missingPunchesnumberrequired
  • otMinutesnumberrequired
  • leaveDaysnumberrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required