List a person's leave balances
Returns this leave year's figures for each type with a yearly balance: entitled, carried over, taken,
adjusted, expired, the balance, booked (approved, not started) and pending (waiting for a decision).
Private types aren't listed.
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
person_id*stringThe person's ID.
^person_[0-7][0-9a-hjkmnp-tv-z]{25}$"person_01kjsesxm0e4zbyvkr7bcfxbfg"The person's balances.
application/json- response
person_id*PersonIdA person ID (TypeID with the person prefix).
^person_[0-7][0-9a-hjkmnp-tv-z]{25}$"person_01kjsesxm0e4zbyvkr7bcfxbfg"year_start*stringdateyear_end*stringdatedata*array<>curl -X GET 'https://api.agoohq.com/v1/people/person_01kjsesxm0e4zbyvkr7bcfxbfg/leave-balances'{ "person_id": "person_01kjw4mg80efgb5aqbsqnxhtbh", "year_start": "2026-01-01", "year_end": "2026-12-31", "data": [ { "type_id": "ltype_01m4y8r6t0e9k2b7c5d3f1g0hj", "type_name": "Annual leave", "kind": "annual", "unit": "working_days", "entitled": 15, "carried": 3, "taken": 4, "adjusted": 1, "expired": 0, "balance": 15, "booked": 2, "pending": 3 } ]}Cancel a leave request POST
Cancels a request waiting for a decision, or approved leave that hasn't started (its days come back to the balance). Leave that has started returns `invalid_state`: HR ends it early in the Console. `leave.cancelled` fires. **Scope:** `attendance:manage` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.
List timesheet periods GET
Returns your organisation's timesheet periods, newest first: each one's days, its payroll date and how many timesheets in it are open, waiting for the person to confirm, waiting for approval and approved. Periods follow your organisation's rules (weekly, fortnightly or monthly) and follow on from each other. Filter by `from` and `to` (periods overlapping them). **Scope:** `attendance:read` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.