Visitors and external IDs

Get a visitor

A visitor is one browser on one device, within your project. It lists every externalId seen with it, which is how shared computers and multi accounts show up.

Shell

curl "https://api.zeno.id/visitors/q1yLOPpzvOstEQCFQQxE" \
	-H "Auth-API-Key: sk_..."

JSON

{
	"visitorId": "q1yLOPpzvOstEQCFQQxE",
	"externalIds": ["user-2077", "user-5120"],
	"detected": ["abusive-ip", "vpn"],
	"eventCount": 6,
	"firstSeenAt": "2026-10-14T08:12:03.000Z",
	"lastSeenAt": "2026-10-22T09:14:02.310Z",
	"recentEvents": [
		{
			"requestId": "1792660442310.Hb3sWq",
			"externalId": "user-5120",
			"createdAt": "2026-10-22T09:14:02.310Z",
			"ip": "198.51.100.7",
			"country": "NL",
			"detected": []
		},
		{
			"requestId": "1792578564800.yU4Ety",
			"externalId": "user-2077",
			"createdAt": "2026-10-21T12:58:49.476Z",
			"ip": "185.65.134.10",
			"country": "NL",
			"detected": ["vpn", "abusive-ip"]
		},
		{
			"requestId": "1792491023117.Qm7pZk",
			"externalId": "user-2077",
			"createdAt": "2026-10-20T10:10:23.117Z",
			"ip": "198.51.100.7",
			"country": "NL",
			"detected": []
		}
	]
}

This is the browser from the Events sample: user-2077 logs in on it, at home and through a VPN, and user-5120 signed up on it the next day. The same three ids run through Related.

Field	Description
`externalIds`	Every external ID seen with this visitor, sorted: passed to `get()` or attached later with `PATCH`.
`detected`	Every signal any of its events detected, ever (within the project's retention): a history, not the latest event's. Read the events for when.
`eventCount`	All its events.
`firstSeenAt`, `lastSeenAt`	Its first and latest event.
`recentEvents`	Its 20 latest events, newest first, each with `requestId`, `externalId` (when it had one), `createdAt`, `ip`, `country` and `detected`. Search with `visitorId` for older ones.

An unknown visitor ID, or another project's, answers 404 visitor_not_found; a malformed one (not 20 letters and digits) 400.

Two external IDs on one visitor, as here, can be one person with two accounts, or two people on one device: see Shared visitor ids.

Delete a visitor

Erases the visitor and all its events:

Shell

curl -X DELETE "https://api.zeno.id/visitors/q1yLOPpzvOstEQCFQQxE" \
	-H "Auth-API-Key: sk_..."

JSON

{ "visitorId": "q1yLOPpzvOstEQCFQQxE", "deletedEvents": 6 }

When one of your users asks to be forgotten, erase everything stored for their external ID. Its events go, and every visitor it was seen with is counted again from the events left: the external ID leaves its externalIds, and its eventCount, dates and detected no longer include the erased events. A visitor with no events left goes too. URL-encode the id in the path (user%2F42 for user/42).

Shell

curl -X DELETE "https://api.zeno.id/external-ids/user-2077" \
	-H "Auth-API-Key: sk_..."

JSON

{ "externalId": "user-2077", "deletedEvents": 5 }

Both deletes are idempotent: calling again answers 200 with deletedEvents: 0. Both also drop the external IDs' links; deleting a visitor keeps an IP you linked by hand with POST /fingerprints, since no event made it. The project's audit log records which secret key erased how many events, never the visitor or external ID it erased. Webhook deliveries of erased events stay in the deliveries log until they expire after 30 days.

Otherwise events are kept for the project's retention, and a visitor for that long after its last visit; with the retention set to indefinitely, both stay until deleted. What to tell your visitors, and what erasure leaves behind, is in Privacy and consent.

Get a visitor

Delete a visitor

Forget an external ID