Get a leave request
Returns one leave request. A private type comes back as away.
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
leave_id*stringThe leave request's ID.
^leave_[0-7][0-9a-hjkmnp-tv-z]{25}$"leave_01m4z0q2k8fv7tqz3x9c1nbe5d"The leave request.
application/json- response
A leave request. A private type (sick and maternity by default) comes back as kind: away, without its type, reason or note.
id*LeaveRequestIdA leave request ID (TypeID with the leave prefix).
^leave_[0-7][0-9a-hjkmnp-tv-z]{25}$"leave_01m4z0q2k8fv7tqz3x9c1nbe5d"person_id*PersonIdA person ID (TypeID with the person prefix).
^person_[0-7][0-9a-hjkmnp-tv-z]{25}$"person_01kjsesxm0e4zbyvkr7bcfxbfg"type_id*|null for a private type.
^ltype_[0-7][0-9a-hjkmnp-tv-z]{25}$type_name*string"Annual leave""Away"kind*string"annual""sick""maternity""paternity""compassionate""study""unpaid""other""away"private*booleanstatus*string"pending""approved""declined""cancelled"starts_on*stringdateends_on*stringThe last day of leave.
datehalf_day*booleanhalf_day_part*|"morning""afternoon"nulldays*numberWhat it counts, in unit.
3unit*string"working_days""calendar_days"paid*booleanreason*|The person's note; null for a private type.
decision_note*|The approver's note; null for a private type.
decided_at*|date-timedecided_by*|Who decided it; null when recorded, decided through the API or approved at once.
^person_[0-7][0-9a-hjkmnp-tv-z]{25}$approval*|The approval's state; null when it needed none.
cancelled_at*|date-timecreated_at*stringdate-timeupdated_at*stringdate-timecurl -X GET 'https://api.agoo.ardent.africa/v1/leave-requests/leave_01m4z0q2k8fv7tqz3x9c1nbe5d'{ "id": "leave_01m4z0q2k8fv7tqz3x9c1nbe5d", "person_id": "person_01kjw4mg80efgb5aqbsqnxhtbh", "type_id": "ltype_01m4y8r6t0e9k2b7c5d3f1g0hj", "type_name": "Annual leave", "kind": "annual", "private": false, "status": "pending", "starts_on": "2026-11-16", "ends_on": "2026-11-18", "half_day": false, "half_day_part": null, "days": 3, "unit": "working_days", "paid": true, "reason": "Family visit in Ho", "decision_note": null, "decided_at": null, "decided_by": null, "approval": { "status": "pending", "step": 1, "of": 2 }, "cancelled_at": null, "created_at": "2026-10-14T09:12:00Z", "updated_at": "2026-10-14T09:12:00Z"}Record leave POST
Records leave from another system (an HR system, a paper form), approved at once, by the rules HR follows in the Console: within the balance and the type's negative allowance, never on days the person already has leave, and with `over_reason` when it's more than a per-occasion type allows. Working days never count public holidays, closed days or days the person doesn't work (Labour Act s.22). Its days come off the balance and `leave.approved` fires. **Scope:** `attendance:manage` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.
Approve or decline a leave request POST
Approves or declines a request waiting for a decision, all its approval steps at once (your organisation's approvers decide step by step in Agoo Workspace and the Console). A decline needs a `note` the person sees; a type that can't be declined (maternity: the dates are agreed, Labour Act s.57) can only be approved; approving stays within the balance. A request that isn't waiting returns `invalid_state`. `leave.approved` or `leave.declined` fires. **Scope:** `attendance:manage` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.