Docs
API referenceAttendance

List attendance events

Preview· P9
GET/attendance/events

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.

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

Authorization

AuthorizationBearer <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.

In: header

Scope: attendance:read

Query Parameters

limit?integer

How many items to return, from 1 to 100.

Range1 <= value <= 100
Default25
cursor?string

The next_cursor from the previous page. Leave it out for the first page.

Lengthlength <= 512
person_id?string

Only events for this person.

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

Only events at this site.

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

Only clock-ins or only clock-outs.

Value in

  • "clock_in"
  • "clock_out"
method?string

Only events recorded with this method.

Value in

  • "qr"
  • "rotating_qr"
  • "pin"
  • "nfc"
  • "face"
  • "geofence"
  • "terminal"
  • "assisted"
face_check?string

Only events with this face check: not_verified lists punches made after a failed face match.

Value in

  • "matched"
  • "not_verified"
review_status?string

Only events with this review status. pending is the review queue.

Value in

  • "pending"
  • "accepted"
  • "rejected"
occurred_after?string

Only events that happened at or after this time.

Formatdate-time
occurred_before?string

Only events that happened before this time.

Formatdate-time

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X GET "https://example.com/attendance/events?limit=25&occurred_after=2026-10-14T00%3A00%3A00Z&occurred_before=2026-10-15T00%3A00%3A00Z"
{  "data": [    {      "id": "clock_01m4xnzdsreh7a3gbm0xtrx108",      "person_id": "person_01kjw4mg80efgb5aqbsqnxhtbh",      "site_id": "site_01kjpt3yw0fz0v414608h9x65s",      "kind": "clock_out",      "method": "qr",      "occurred_at": "2026-10-14T17:04:51Z",      "recorded_at": "2026-10-14T17:04:52Z",      "device_id": "dev_01kjywram0esxva8np5wzj6fre",      "terminal_reference": null,      "shift_id": "shift_01kn6pqfm0fmasbh61jnr3syze",      "late_minutes": null,      "offline": false    },    {      "id": "clock_01m4wq6yw0ez5srdzr46tftpah",      "person_id": "person_01kjw4mg80efgb5aqbsqnxhtbh",      "site_id": "site_01kjpt3yw0fz0v414608h9x65s",      "kind": "clock_in",      "method": "face",      "occurred_at": "2026-10-14T08:07:12Z",      "recorded_at": "2026-10-14T08:07:12Z",      "device_id": "dev_01kjywram0esxva8np5wzj6fre",      "terminal_reference": null,      "shift_id": "shift_01kn6pqfm0fmasbh61jnr3syze",      "late_minutes": 7,      "offline": false,      "face_check": "matched"    }  ],  "next_cursor": null,  "has_more": false}

Decline a booking POST

Declines a `pending` booking, frees its slot and fires `booking.declined`. Agoo tells the attendee their request wasn't accepted. The `reason` is kept on the booking for your organisation; the attendee sees it only if you set `share_reason_with_attendee`. Returns `invalid_state` if the booking isn't `pending`. To call off a booking that is already confirmed, cancel it with `POST /bookings/{booking_id}/cancel`. **Scope:** `bookings:write` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.

Record a clock-in or clock-out POST

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`. - 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.