Add a watchlist entry
/watchlistAdds a person to your watchlist. Give a name and a phone number, an ID number or both. When a visit is created
for, or someone checks in as, a person matching an entry (on name, allowing for spelling differences, phone
number or ID number), Agoo holds the visit, alerts your security team silently and fires watchlist.matched.
The visitor, the host and the kiosk aren't told why. Every watchlist read and change is in the audit trail.
Leave site_ids empty to watch for the person at every site.
Scope: watchlist:write · 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: watchlist:write
Header Parameters
A UUID you generate for this operation. If you retry with the same key within 24 hours, Agoo returns the
original response instead of acting twice. While the first request is still running, a retry returns
conflict. Reusing a key with a different request returns idempotency_key_reused. Responses with
rate_limited, internal_error or unavailable aren't stored, so retry those with the same key.
uuidRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
A new watchlist entry. Give a phone number, an ID number or both, as well as the name.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X POST "https://example.com/watchlist" \ -H "Idempotency-Key: 3f6b2a1e-8c4d-4f7a-9b2e-5d1c0a7e9f64" \ -H "Content-Type: application/json" \ -d '{ "name": "Kojo Badu", "id_number": "GHA-000000000-0", "reason": "Former employee. Site access withdrawn on 20 August.", "site_ids": [] }'{ "id": "watch_01m0fqhdr0e31ray1qxa2x5vtk", "name": "Kojo Badu", "phone": null, "has_id_number": true, "reason": "Former employee. Site access withdrawn on 20 August.", "site_ids": [], "expires_at": null, "created_by": null, "created_at": "2026-08-20T14:00:00Z"}List watchlist entries GET
Returns your watchlist entries, newest first. Expired entries aren't returned. **Scope:** `watchlist:read` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.
Remove a watchlist entry DELETE
Removes an entry from your watchlist. Check-ins stop matching it straight away, and the entry's personal data (name, phone number, ID number hash, reason) is erased. Past matches stay in the audit trail, without them. **Scope:** `watchlist:write` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.