List a person's documents
Returns a person's standard HR documents (contracts, letters, certificates, licences) as metadata, newest
first: the latest version of each document, or every version with versions=true. A document is checking
until its virus scan passes, then current (or expired past its date), and superseded once a newer
version is in force.
Identity documents, disciplinary letters and health documents (medical certificates, police reports) are never returned to an API key: they stay inside Agoo.
Scope: documents: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: documents:read
person_id*stringThe person's ID.
^person_[0-7][0-9a-hjkmnp-tv-z]{25}$"person_01kjsesxm0e4zbyvkr7bcfxbfg"versions?booleantrue: every version, not only the latest of each document.
falseThe person's documents.
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/people/person_01kjsesxm0e4zbyvkr7bcfxbfg/documents'{ "data": [ { "id": "hrdoc_01m6k2a4c6e8g0j2r4n6q8s0tv", "object": "hr_document", "person_id": "person_01kjw4mg80efgb5aqbsqnxhtbh", "type": { "id": "hrdoctype_01m6k1z8b0d2f4h6k8m0p2r4tw", "name": "Professional licence", "category": "licence" }, "title": "Medical and Dental Council licence", "version": 2, "supersedes_id": "hrdoc_01m3f8c0e2g4j6r8n0q2s4v6wy", "status": "current", "visibility": "standard", "issued_on": "2026-01-02", "expires_on": "2026-12-31", "content_type": "application/pdf", "byte_size": 176004, "sha256": "9f2c0b8e4d1a7c3e5b6f8a0d2c4e6f8a1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a", "created_at": "2026-01-04T09:12:00Z", "updated_at": "2026-01-04T09:14:00Z" } ], "next_cursor": null, "has_more": false}Change a person's job POST
Changes the person's job from a date: applied at once when `effective_on` is today or earlier (up to 90 days back), otherwise `scheduled` and applied on that day (up to a year ahead). Send at least one field; `null` clears one that's optional. - Each field becomes a line of employment history, dated `effective_on`. - `position_id` puts them in a position nobody holds that isn't frozen or closed (and out of the one they held); `null` takes them out of theirs. Positions are part of Growth, Pro and Enterprise. - `manager_id` must be an active person in your directory, never the person themselves. - Fires `person.job_changed` when it's applied: at once, or on its date. **Scope:** `hr:write` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.
Add a document POST
Adds a standard document to a person's record. Send the file as the request body (a PDF, or a photo as JPEG, PNG or WebP, up to 20 MB) and its type and details in the query. Agoo checks the file by its bytes, removes a photo's camera details and location, encrypts it with a key of its own and scans it for viruses; the document is `checking` until the scan passes. Send `replaces` to add the next version of a current document (a renewed licence): the older one is kept as `superseded`. - A type that expires needs `expires_on`; Agoo reminds the person, their manager and HR before it expires, as the type says, and fires `hr_document.expiring`. - A copy of a Ghana Card is refused (L.I. 2523 forbids relying on a photocopy, scan or image of one to verify identity): record the Ghana Card PIN on the HR record instead. - HEIC photos and Word files are refused: send a JPEG or a PDF. **Scope:** `documents:write` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.