Docs
API referenceAttendance

Record a clock-in or clock-out

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.

  • 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

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: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

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://example.com/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`. **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 or absent. Each person counts once per day, in exactly one of the four. 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.