List 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.
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.
AuthorizationBearer <token>Send Authorization: Bearer <token> on every request. The token is one of:
| Prefix | What it is | Where it may be used |
|---|---|---|
agoo_sk_live_ | Secret key, live mode | Your servers only |
agoo_sk_test_ | Secret key, test mode | Your servers only |
agoo_pk_live_ | Publishable key, live mode | Browsers 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 mode | As 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:read
limit?integerHow many items to return, from 1 to 100.
1 <= value <= 10025cursor?stringThe next_cursor from the previous page. Leave it out for the first page.
length <= 512person_id?stringOnly events for this person.
^person_[0-7][0-9a-hjkmnp-tv-z]{25}$"person_01kjsesxm0e4zbyvkr7bcfxbfg"site_id?stringOnly events at this site.
^site_[0-7][0-9a-hjkmnp-tv-z]{25}$"site_01kjpt3yw0fz0v414608h9x65s"kind?stringOnly punches of this kind. break_start or break_end lists break punches.
"clock_in""clock_out""break_start""break_end"include_breaks?booleanInclude break punches (break_start and break_end) beside clock-ins and clock-outs. false by default.
falsemethod?stringOnly events recorded with this method: manual lists the punches managers added or corrected in the Console.
"qr""phone_badge""rotating_qr""pin""nfc""face""geofence""terminal""assisted""manual"face_check?stringOnly events with this face check: not_verified lists punches made after a failed face match.
"matched""not_verified"review_status?stringOnly events with this review status. pending is the review queue.
"pending""accepted""rejected"occurred_after?stringOnly events that happened at or after this time.
date-timeoccurred_before?stringOnly events that happened before this time.
date-timeA page of attendance events.
application/json- response
data*array<>next_cursor*|Pass this as cursor to get the next page. null on the last page.
"b3BhcXVlLWN1cnNvcg"has_more*booleancurl -X GET 'https://api.agoohq.com/v1/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 punch 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`. - 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.