Get a person
/people/{person_id}Returns one host or employee, including deactivated people.
Scope: people:read · Plan: Pro and Enterprise in live mode; every plan in test mode.
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.
In: header
Scope: people:read
Path Parameters
The person's ID.
^person_[0-7][0-9a-hjkmnp-tv-z]{25}$"person_01kjsesxm0e4zbyvkr7bcfxbfg"Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X GET "https://example.com/people/person_01kjsesxm0e4zbyvkr7bcfxbfg"{ "id": "person_01kjsesxm0e4zbyvkr7bcfxbfg", "name": "Kwame Mensah", "email": "kwame.mensah@voltabank.example", "phone": "+233205550142", "job_title": "Head of Treasury", "department": "Treasury", "employee_number": "VB-0142", "site_ids": [ "site_01kjpt3yw0fz0v414608h9x65s" ], "can_host": true, "tracks_attendance": true, "status": "active", "custom_fields": {}, "created_at": "2026-03-03T09:00:00Z", "updated_at": "2026-10-06T14:30:00Z", "deactivated_at": null}Create a person POST
Adds a host or employee to your directory. Give an email address or a phone number (or both) so Agoo can notify them when visitors arrive: with neither, the request returns `validation_failed` at `body.email` and `body.phone`. - Fires `person.created`. - Counts towards your plan's host and attendance limits. Going over a limit returns `plan_required`. - Returns `conflict` if another person already uses the email address. **Scope:** `people:write` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.
Update a person PATCH
Changes a person's details. Send only the fields you want to change; fields you leave out stay as they are. `custom_fields` are merged key by key, and a key set to `null` is removed. - Fires `person.updated`. - A deactivated person can't be updated (`invalid_state`). - Returns `conflict` if another person already uses the new email address. **Scope:** `people:write` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.