Docs
API referenceAttendance

Record a punch

Preview· P9
POST
/attendance/events

Records a clock-in or clock-out from your own terminal, such as a turnstile or a biometric reader you already run. The event's method is always terminal.

  • Where break punches are on at the site, break_start and break_end record a break inside a clock-in, with break_type rest (the default) or nursing (only while the person's nursing breaks are on). A break punch returns invalid_state when the person isn't clocked in, is already on a break, or isn't on one to end, and validation_failed at kind when break punches are off at the site. It fires attendance.break_started or attendance.break_ended.

  • Your terminal can send evidence your organisation has switched on at the site: selfie_file_id (a selfie file), location (with latitude and longitude only when your organisation keeps coordinates) and wifi (with ssid and bssid only when it keeps them). Evidence that's off returns validation_failed at that field. In consent mode, evidence for someone who hasn't consented returns consent_required.

  • Terminal punches must be switched on at the site (they are by default).

  • Send the time it happened as occurred_at. You can send punches late, for example after a network cut; Agoo places them by occurred_at. It can't be in the future.

  • Fires attendance.clocked_in or attendance.clocked_out, and attendance.late when a clock-in is later than the person's shift start plus its grace period.

  • The person must be active and on attendance (tracks_attendance: true); otherwise you get invalid_state.

Scope: attendance:write · Plan: Pro and Enterprise in live mode; every plan in test mode.

Authorization

headerAuthorizationBearer <token>

Send Authorization: Bearer <token> on every request. The token is one of:

PrefixWhat it isWhere it may be used
agoo_sk_live_Secret key, live modeYour servers only
agoo_sk_test_Secret key, test modeYour servers only
agoo_pk_live_Publishable key, live modeBrowsers and apps: create pre-registrations and bookings, read public booking types (with their intake questions) and their free slots, read the visit types open for pre-registration with their public forms. Never lists people.
agoo_pk_test_Publishable key, test modeAs above, in test mode

Admins create keys in Console → Developers → API keys and choose each key's scopes. A key is shown once. Never put a secret key in a URL, a browser or a mobile app.

Scope: attendance:write

Header Parameters

Idempotency-Key*string

A UUID you generate for this operation. If you retry with the same key within 24 hours, Agoo returns the original response instead of acting twice. While the first request is still running, a retry returns conflict. Reusing a key with a different request returns idempotency_key_reused. Responses with rate_limited, internal_error or unavailable aren't stored, so retry those with the same key.

Formatuuid

Request Body

application/json
  1. body
person_id*PersonId

A person ID (TypeID with the person prefix).

Match^person_[0-7][0-9a-hjkmnp-tv-z]{25}$
Example"person_01kjsesxm0e4zbyvkr7bcfxbfg"
site_id*SiteId

A site ID (TypeID with the site prefix).

Match^site_[0-7][0-9a-hjkmnp-tv-z]{25}$
Example"site_01kjpt3yw0fz0v414608h9x65s"
kind*AttendanceKind

clock_in and clock_out; and, where your organisation has break punches on, break_start and break_end: a break inside a clock-in, which never ends the stretch it sits in.

Value in"clock_in""clock_out""break_start""break_end"
break_type?string

With break_start: rest (the default) or nursing. With break_end it follows the break being ended. Only on break punches.

Value in"rest""nursing"
occurred_at*string

When the punch happened. Can't be in the future.

Formatdate-time
terminal_reference?string

Your terminal's identifier, kept for your records.

Lengthlength <= 100
selfie_file_id?string

A selfie taken with the punch: a file of kind selfie from POST /files. Only when selfie evidence is on at the site.

Match^file_[0-7][0-9a-hjkmnp-tv-z]{25}$
location?

Your terminal's location check. Only when phone clock-in (location evidence) is on at the site; latitude and longitude only when your organisation keeps coordinates.

wifi?

Your terminal's Wi-Fi check. Only when the Wi-Fi check is on; ssid and bssid only when your organisation keeps them.

Response Body

The recorded event.

application/json
  1. response

One punch: a clock-in or clock-out, or a break punch where break punches are on.

id*AttendanceEventId

An attendance event ID (TypeID with the clock prefix).

Match^clock_[0-7][0-9a-hjkmnp-tv-z]{25}$
Example"clock_01m4wq6yw0ez5srdzr46tftpah"
person_id*PersonId

A person ID (TypeID with the person prefix).

Match^person_[0-7][0-9a-hjkmnp-tv-z]{25}$
Example"person_01kjsesxm0e4zbyvkr7bcfxbfg"
site_id*SiteId

A site ID (TypeID with the site prefix).

Match^site_[0-7][0-9a-hjkmnp-tv-z]{25}$
Example"site_01kjpt3yw0fz0v414608h9x65s"
kind*AttendanceKind

clock_in and clock_out; and, where your organisation has break punches on, break_start and break_end: a break inside a clock-in, which never ends the stretch it sits in.

Value in"clock_in""clock_out""break_start""break_end"
break_type?string

On break punches only: rest (a break, paid or unpaid as your organisation's rules say) or nursing (the paid nursing hour, never deducted).

Value in"rest""nursing"
method*AttendanceMethod

How the punch was made: qr (the kiosk scanned a staff QR badge), phone_badge (the kiosk scanned the staff badge on the person's phone, in the Workspace app), rotating_qr (a phone scanned the kiosk's code, which changes every 30 seconds), pin, nfc (card or tag), face (face match on a kiosk), geofence (a phone inside the site's area, or on its Wi-Fi), terminal (your own system, through the API) or assisted (after a failed face match, a supervisor at the kiosk confirmed who it was; always face_check: not_verified) or manual (added in the Console by a manager for a punch the person missed, or to correct a punch's time, always with a reason: see added).

Value in"qr""phone_badge""rotating_qr""pin""nfc""face""geofence""terminal""assisted""manual"
occurred_at*string

When the punch happened.

Formatdate-time
recorded_at*string

When Agoo received it.

Formatdate-time
device_id*|

The kiosk used, if any.

Match^dev_[0-7][0-9a-hjkmnp-tv-z]{25}$
terminal_reference*|

Your terminal's identifier, for terminal punches.

shift_id*|

The shift this punch counts towards.

Match^shift_[0-7][0-9a-hjkmnp-tv-z]{25}$
late_minutes*|

For a late clock-in, minutes after the shift start. Otherwise null.

Range0 <= value
offline*boolean

true if the punch was made offline and synced later.

selfie_file_id?string

The selfie taken with the punch (a selfie file). Only on punches that have one.

Match^file_[0-7][0-9a-hjkmnp-tv-z]{25}$
location?

A phone's location check against the site's geofence. latitude and longitude appear only when your organisation keeps coordinates, and only until its coordinate retention clears them; the result and accuracy stay with the punch.

wifi?

The Wi-Fi check: whether the phone was on one of the site's networks. ssid and bssid appear only when your organisation keeps them.

face_check?string

matched on face punches (the kiosk's match). not_verified on a fallback after a failed face match (PIN, QR, NFC or assisted). Only on those punches. Agoo never receives face images or templates.

Value in"matched""not_verified"
review?

A supervisor's review of a punch made after a failed face match.

added?

Who added the punch in the Console, and why. Only on manual punches.

voided?

Why the punch stopped counting. Only in attendance.voided events: lists and other events never include voided punches.

curl -X POST 'https://api.agoohq.com/v1/attendance/events' \  -H 'Idempotency-Key: 3f6b2a1e-8c4d-4f7a-9b2e-5d1c0a7e9f64' \  -H 'Content-Type: application/json' \  -d '{  "person_id": "person_01kjw4mg80efgb5aqbsqnxhtbh",  "site_id": "site_01kjpt3yw0fz0v414608h9x65s",  "kind": "clock_in",  "occurred_at": "2026-10-15T07:55:30Z",  "terminal_reference": "RIDGE-TURNSTILE-02"}'
{  "id": "clock_01m4wphhage7y9rzdsw3x2xsxt",  "person_id": "person_01kjw4mg80efgb5aqbsqnxhtbh",  "site_id": "site_01kjpt3yw0fz0v414608h9x65s",  "kind": "clock_in",  "method": "terminal",  "occurred_at": "2026-10-15T07:55:30Z",  "recorded_at": "2026-10-15T07:55:31Z",  "device_id": null,  "terminal_reference": "RIDGE-TURNSTILE-02",  "shift_id": "shift_01kn6pqfm0fmasbh61jnr3syze",  "late_minutes": null,  "offline": false}

List attendance events GET

Returns clock-ins and clock-outs, most recent first by `occurred_at`. Events recorded offline (during a network or power cut) appear once the kiosk or phone syncs, with their original time and `offline: true`. Where your organisation has break punches on, people also punch Start break and End break. Those (`break_start`, `break_end`) are returned only when you ask: with `include_breaks=true`, or a `kind` that names one, so an integration built for clock-ins and clock-outs never meets a kind it doesn't expect. **Scope:** `attendance:read` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.

Get an attendance summary GET

Counts, for each day in a range, how many people on attendance were present, late, on leave, absent or not in yet. Each person counts once per day, in at most one of the five. Someone is absent only once their rostered shift has ended with no clock-in, and never on approved leave or a public holiday your organisation observes; until the shift ends they're `not_in_yet`. Days are whole days in the site's time zone (or your organisation's, without `site_id`). The range can span up to 31 days. **Scope:** `attendance:read` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.