Changelog
Back to All
Added

API Updates - October 2026

11 days ago

Audiences

You can now read audiences as JSON records and build them from the people who visit your website.

Audience Records

Read an audience's rows as JSON, one page at a time, so you don't have to download and parse files.

GET /api/v1/audiences/{id}/records

Build the audience first with GET /api/v1/audiences/{id}/download and poll it until its status is ready. Then keep requesting records, passing each page's next_cursor as cursor, until you get a page with no next_cursor.

Response:

  • next_cursor (string) - Cursor for the next page. It is missing on the last page.

Example:

curl -X GET "https://api.delivr.ai/api/v1/audiences/{id}/records" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -H "X-Project-Id: YOUR_PROJECT_ID"

Website Visitor Audiences

Build an audience from the people your pixels identified.

POST /api/v1/audiences

Parameters:

  • type (string) - Set to pixel to build a website visitor audience.
  • source_pixel_ids (array) - The pixels whose identified visitors make up the audience. Each must be a pixel in this project.

Example:

curl -X POST https://api.delivr.ai/api/v1/audiences \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -H "X-Project-Id: YOUR_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{"audience_name": "Website visitors", "type": "pixel", "segmentation_type": "Audience", "organization_id": "YOUR_ORG_ID", "project_id": "YOUR_PROJECT_ID", "filter": {}, "source_pixel_ids": ["YOUR_PIXEL_ID"]}'

Intent audiences and people-based contact audiences now accept a WEBSITE_VISITORS condition with the in or not in operator. Use it to include or exclude the people in a website visitor audience from the same project once that audience has finished its first build.

Manage website visitor audiences with the existing endpoints:

PUT /api/v1/audiences/{id}
POST /api/v1/audiences/{id}/refresh

Events API

New v3 routes tell you who visited your site, not just which events happened. They can also break down a day's web events by field.

Website Visitors

GET /api/v3/events/{tier}/visitors

This endpoint returns one row per person instead of one row per resolution event. Use it to find out who visited during a time window without removing duplicate people yourself.

Parameters:

  • kind (string, query, required) - buyers for one row per person, or accounts for one row per company. accounts is only available when {tier} is resolution_full_profile.

Web Event Breakdowns

GET /api/v3/events/web_event/counts

Counts a project's website events for one window. The window can be up to 24 hours long and must start within the last 30 days.

  • Narrow the results to a single pixel.
  • Filter with the existing filter language.
  • Group results by up to two fields.

The endpoint returns counts only and is not billed.

Predictive Signals

New lookups return intent trends for each person.

People Signals Lookup and Batch

POST /api/v1/signals/people/lookup
POST /api/v1/signals/people/batch

These endpoints return a person's high and medium intent topics that have a 14-day trend. You don't need an audience. Batch takes up to 1,000 people per call. They work with an API key only, and each request must name a project. You're billed one Predictive Signals unit for each person who has at least one trend topic returned.

Parameters:

  • hem (string) - Look up a person by SHA-256 hashed email.
  • email (string) - Look up a person by email address.
  • dry_run (boolean) - When true, returns the cost without billing. Works without a payment method on file.

Example:

curl -X POST https://api.delivr.ai/api/v1/signals/people/lookup \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -H "X-Project-Id: YOUR_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "dry_run": true}'

Dry Runs Without a Payment Method

POST /api/v1/contact/query

Dry runs no longer need a payment method on file, and a reached budget doesn't block them. A dry run returns the cost of the request and is not billed.

Parameters:

  • dry_run (boolean) - When true, returns the cost without billing.

Intent

Person intent lookups now answer for the whole person, not just one address.

Person-Level Intent Matching

POST /api/v1/intent/lookup
POST /api/v1/intent/batch

These endpoints now resolve an email, hem or linkedin_url to the person who holds it. They return that person's topics across all of their addresses, so an address with no intent of its own can still match.

Parameters:

  • person_id (string) - A person_id from an earlier response. Reads that person's topics directly.

Response:

  • person_id (string) - Returned when the identifier resolves to a person.

POST /api/v1/intent/people now returns one row per person.

Email Identity

You can now get email tokens through the API and record email opens with the pixel.

Email Tokens API

POST /api/v1/email-tokens

Returns a dlvr_et token for each email address you send, in the same order, up to 10,000 per request. Authenticate with your organization API key (X-Api-Key and X-Api-Secret). If your code syncs contacts into an email platform, it can now get tokens directly.

Parameters:

  • project_id (string) - The project to generate tokens for. It must belong to your API key's organization.
  • emails (array of strings) - The contacts' email addresses.

Response:

  • response.tokens (array) - One entry per email, each with a token and a status of ok or invalid_email.

Email Open Tracking

GET /pixel/core/api/send-event/get

This endpoint now accepts event_type=email_open and responds with a 1x1 image. Add it to your emails and merge in each recipient's dlvr_et token to record which recipients opened them.

Parameters:

  • event_type (string, query) - Set to email_open.
  • dlvr_et (string, query) - The recipient's email token.

Integrations and Exports

You can now deliver exports to your own HTTPS endpoint.

Webhook Connections

Create a Webhook integration with type webhook, a name and an HTTPS url, in the project given by project_id.

POST /api/v1/integrations?project_id={project_id}

Delivr generates the signing secret and returns it only in this response, so store it when you create the integration. To rotate the secret, use:

POST /api/v1/integrations/{id}/webhook-secret

To use the webhook as an export destination, pass it to:

POST /api/v1/exports

A webhook destination can receive either of these:

  • An audience export that selects a Predictive Signals state with signalState.
  • A pixel's resolved website visitors, delivered every 5 minutes on the continuous schedule. The webhook must be the export's only destination and must set tier and delivery_mode.

Campaigns

Campaign reads now report more delivery detail, and campaign writes support more targeting options.

Campaign Insights

GET /api/v1/campaigns/{id}/insights

A new endpoint that shows why a campaign is or isn't delivering: the auction requests it was skipped or filtered on and why, and how it did by site, device, creative and size.

Bids, Win Rate and Viewability

GET /api/v1/campaigns/{id}/performance

The response now includes bids, win rate and viewability, both per day and in the summary.

Operating System and Browser Targeting

POST /api/v1/campaigns
PUT /api/v1/campaigns/{id}

Both endpoints now accept targeting.operating_systems and targeting.browsers, alongside device and connection types. For example, set browsers to ["CHROME"] to restrict a campaign to Chrome only.