Docs
API referenceVisitors

List visitors

Preview· P9
GET/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.

Authorization

AuthorizationBearer <token>

Send Authorization: Bearer <token> on every request. The token is one of:

PrefixWhat it isWhere it may be used
agoo_sk_live_Secret key, live modeYour servers only
agoo_sk_test_Secret key, test modeYour servers only
agoo_pk_live_Publishable key, live modeBrowsers 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 modeAs 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: visitors:read

Query Parameters

limit?integer

How many items to return, from 1 to 100.

Range1 <= value <= 100
Default25
cursor?string

The next_cursor from the previous page. Leave it out for the first page.

Lengthlength <= 512
q?string

Matches the start of any word in the visitor's name or company. Case-insensitive.

Length2 <= length <= 100
phone?string

Exact phone number in E.164 format. Encode the + as %2B in the query string.

Match^\+[1-9][0-9]{7,14}$
Example"+233241234567"
email?string

Exact email address, case-insensitive.

Formatemail
created_after?string

Only items created at or after this time.

Formatdate-time
created_before?string

Only items created before this time.

Formatdate-time

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X GET "https://example.com/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": {        "type": "ghana_card",        "last4": "7253"      },      "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}

Resend a visitor's pass POST

Sends the visitor their QR pass again, for example after they lose the message or you change the visit's times. Only `expected` visits have a pass to resend; any other status returns `invalid_state`. - Leave `channels` out to use the channels the pass was last sent on. - Fires `pass.sent`. Each message counts towards your SMS and WhatsApp allowance. - In test mode, messages go to the console's test outbox. **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.