List people
Returns the hosts and employees in your directory, newest first. Filter by name, email, site or status,
for example to find the host_id for an invitation.
Scope: people: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: people:read
limit?integerHow many items to return, from 1 to 100.
1 <= value <= 10025cursor?stringThe next_cursor from the previous page. Leave it out for the first page.
length <= 512q?stringMatches the start of any word in the person's name, or their email address. Case-insensitive.
2 <= length <= 100email?stringExact email address, case-insensitive.
emailsite_id?stringOnly people assigned to this site.
^site_[0-7][0-9a-hjkmnp-tv-z]{25}$"site_01kjpt3yw0fz0v414608h9x65s"status?stringOnly people with this status. Defaults to active.
"active""deactivated"can_host?booleanOnly people who can (or can't) host visitors.
manager_id?stringOnly the people this person manages directly (whose manager_id it is).
^person_[0-7][0-9a-hjkmnp-tv-z]{25}$"person_01kjsesxm0e4zbyvkr7bcfxbfg"A page of people.
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?limit=25&q=Kwame&email=kwame.mensah%40voltabank.example&can_host=true'{ "data": [ { "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, "works_gate": false, "visitors_via": null, "kiosk_listed": true, "status": "active", "custom_fields": {}, "created_at": "2026-03-03T09:00:00Z", "updated_at": "2026-10-06T14:30:00Z", "deactivated_at": null, "manager_id": "person_01kjsf3c00ecxs9b3k1hw7wq2n", "started_on": "2021-06-14", "left_on": null, "employment_type": "permanent", "contracted_hours": null } ], "next_cursor": null, "has_more": false}Get a site GET
Returns one site with its address, time zone, gates and paired kiosks. The site's IANA time zone is the one Agoo uses for that site's days, shifts and summaries. **Scope:** `sites:read` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.
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.