Events API v3

The Events API v3 splits the events query into four route-fixed tiers. The URL you call fixes both the billing tier and the identity fields you can get back, so the price of a call is legible from the route. Pick the tier that matches the enrichment you need.

Pick the route, and you pick the price

There is no bare /api/v3/events query route: you always call a tier. Start with web_event to confirm data is flowing, then move up only to the tier whose identity or profile fields you actually need.

Discover the fields before you query

• GET /api/v3/events_schema returns the full field metadata (non-billable).
• GET /api/v3/events/{tier}/schema returns only the fields allowed at that tier, for example GET /api/v3/events/web_event/schema.

Selecting a field above your route's tier is rejected, so the schema endpoint tells you exactly what each tier can return.

Authenticate and scope

Send your API key on every request, and scope the call to a project:

X-Api-Key: dlvr_xxxxxxxx
X-Api-Secret: <your secret>

Pass the project as ?project_id=<project-uuid> (or the X-Project-Id header). Create your key in the dashboard under Organization settings, API Keys. All calls are served from https://api.delivr.ai. The apiv2.delivr.ai and apiv3.delivr.ai hostnames are legacy aliases of the same backend, so the path selects the version, not the host.

A project-scoped key reads only its own project: a request scoped to the organization returns that project's events, and another project's project_id, pixel or campaign returns 404.

Query

curl -s "https://api.delivr.ai/api/v3/events/web_event?project_id=<project-uuid>&limit=100" \
  -H "X-Api-Key: dlvr_xxxxxxxx" \
  -H "X-Api-Secret: <your secret>"

The response is { "rows": [ ... ], "meta": { ... } }; the columns present depend on the tier route and the fields you select.

Move up a tier to get resolved identity:

curl -s "https://api.delivr.ai/api/v3/events/resolution_hem?project_id=<project-uuid>&limit=100" \
  -H "X-Api-Key: dlvr_xxxxxxxx" \
  -H "X-Api-Secret: <your secret>"

List the visitors behind the events

The tier routes return one row per event. When you want who visited rather than what they did, call a tier's /visitors route. It returns one row per person, or per company, over a window, deduplicated across the project's pixels.

curl -s "https://api.delivr.ai/api/v3/events/resolution_full_profile/visitors?project_id=<project-uuid>&kind=buyers&start_ms=1790121600000&end_ms=1790726400000&limit=500" \
  -H "X-Api-Key: dlvr_xxxxxxxx" \
  -H "X-Api-Secret: <your secret>"

The response is { "visitors": [ ... ], "count": 500, "has_partial_data": false }.

• Buyers or accounts. kind=buyers returns one row per person, deduplicated on hem. kind=accounts returns one row per company, deduplicated on company_domain. Only resolution_full_profile carries the company domain, so accounts are available on that tier alone.
• The tier is the price. Visitors are available on resolution_hem, resolution_hem_pte and resolution_full_profile. Each visitor returned counts once at that tier's price, whatever columns you select. Selecting fewer columns makes the answer smaller, not cheaper. web_event has no visitors route, because it carries no identity to deduplicate on.
• Scope. Name project_id to read every pixel in the project, or pixel_id for one. Add include_dsp=true to include visitors from the project's DelivrDSP campaigns as well. Campaigns are read only for a project_id: with pixel_id alone, include_dsp adds nothing, so name the project too.
• Window and limit. start_ms, end_ms and limit are required, and limit goes up to 50,000. Visitors come most recent first, and limit keeps the most recent. There is no paging: when more visitors match than you asked for, narrow the window to reach earlier ones.
• Partial answers. has_partial_data: true means part of the window could not be read, so visitors may be missing. Only the visitors returned count. Ask again, or narrow the window.

Filters, field selection, and time windows

The tier routes share the same query parameters as the rest of the events API: field selection, filters, ordering, paging, and the time window. See Pixel and DSP Event Fields for the full field catalog and query-parameter reference.

Which endpoint should I use?

The per-tier routes make cost predictable and bound the returned fields to the tier you called. Start at web_event to confirm data is flowing, then move up only to the tier whose identity or profile fields you actually need.