List visitors
Returns visitor records, newest first. A visitor record holds one person's details across all their visits; Agoo matches returning visitors by phone number. ID document numbers are never returned in full.
In live mode, a visitor whose visits are all hidden by your plan's visitor history is left out. The record is kept, not deleted, and comes back if you move to a plan with a longer history.
Scope: visitors: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: visitors: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 visitor's name or company. Case-insensitive.
2 <= length <= 100phone?stringExact phone number in E.164 format. Encode the + as %2B in the query string.
^\+[1-9][0-9]{7,14}$"+233241234567"email?stringExact email address, case-insensitive.
emailcreated_after?stringOnly items created at or after this time.
date-timecreated_before?stringOnly items created before this time.
date-timeA page of visitors.
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/visitors?limit=25&q=Owusu&email=ama%40coastline.example&created_after=2026-10-01T00%3A00%3A00Z&created_before=2026-11-01T00%3A00%3A00Z'{ "data": [ { "id": "visitor_01krdtb870fxj8t6ntdtcxwdk5", "name": "Ama Owusu", "phone": "+233241234567", "email": "ama@coastline.example", "company": "Coastline Consult", "id_document": null, "visit_count": 6, "first_visit_at": "2026-05-12T10:05:00Z", "last_visit_at": "2026-10-14T09:31:02Z", "created_at": "2026-05-12T10:05:00Z", "updated_at": "2026-10-14T09:31:02Z" } ], "next_cursor": null, "has_more": false}Book a waiting visitor in for another time POST
Books the visitor in for another time and closes this visit, for a visitor who can't be seen today. With `expected_at`, Agoo makes a new invitation for the same visitor and visit type, for whoever this visit is for unless you name hosts or a team, and sends their pass. With `booking_id`, a booking you already made for them replaces the visit instead. This visit becomes `cancelled`, with `rescheduled_to` naming what replaced it, and its pass stops working. Only a visit that is `expected` or `awaiting_approval` can be booked in again. Fires `visit.created` for the new visit and `visit.cancelled` for this one; the new visit's hosts are told. **Scope:** `visits:write` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.
Get a visitor GET
Returns one visitor record. To see their visits, call `GET /visits?visitor_id=…`. In live mode, a visitor whose visits are all hidden by your plan's visitor history returns `plan_required`. **Scope:** `visitors:read` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.