Add a watchlist entry
Adds 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.
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: watchlist:write
Idempotency-Key*stringA 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.
uuidapplication/json- body
A new watchlist entry. Give a phone number, an ID number or both, as well as the name.
name*string1 <= length <= 120phone?PhoneNumberA phone number in E.164 format.
^\+[1-9][0-9]{7,14}$"+233241234567"id_number?stringAn ID document number, such as a Ghana Card number. Agoo stores only a secure hash for matching and never returns it.
length <= 40reason*string1 <= length <= 500site_ids?array<>[]expires_at?stringWhen the entry stops matching. Leave it out for no end.
date-timeThe new watchlist entry.
application/json- response
A person your security team wants to be alerted about.
id*WatchlistEntryIdA watchlist entry ID (TypeID with the watch prefix).
^watch_[0-7][0-9a-hjkmnp-tv-z]{25}$"watch_01m0fqhdr0e31ray1qxa2x5vtk"name*string"Kojo Badu"phone*|^\+[1-9][0-9]{7,14}$has_id_number*booleanWhether the entry includes an ID number. The number itself is stored only as a secure hash and is never returned.
reason*stringWhy the person is on the watchlist. Only staff with watchlist access see it.
site_ids*array<>The sites the entry applies to. Empty means every site.
expires_at*|When the entry stops matching. null for no end.
date-timecreated_by*|The person who added it. null when added with an API key.
^person_[0-7][0-9a-hjkmnp-tv-z]{25}$created_at*stringdate-timecurl -X POST 'https://api.agoohq.com/v1/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.