Create audience

post

https://api.delivr.ai/api/v1/audiences

Create a new audience with the specified type and parameters.

Type-specific requirements:

intents: Requires filter with topic-based intent criteria.
contact: Requires filter with contact-database criteria. elixir is the former name for this type and is still accepted on create; audiences created before the rename may still report elixir until they are migrated.
list: Requires source_list_id and source_list_mode, and still requires filter like every other type. Send an empty object ("filter": {}) -- a list audience's population comes from the uploaded list, so there is nothing to filter on, but omitting the field is rejected with {"field": "Filter", "constraint": "required"}. Setting source_list_id is what makes the server treat the audience as type list. Availability: rolling out. You can create a list audience today, but build output is not yet available for this type.
pixel: A website visitor audience, built from the people your pixels recognized on your site. Requires source_pixel_ids. filter is optional narrowing: send {} to take every visitor who qualifies. record_limit is not supported on this type, and the filter cannot carry intent topics, uploaded lists, or website visitor conditions. Defaults to a daily refresh. A pixel that is not one of the project's pixels returns 400 with code pixel_not_in_project. Availability: behind a feature flag; not yet enabled for all projects.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

project_id

uuid

Project ID (UUID). Every audience operation except GET /api/v1/audiences/schema is scoped to a project: send this parameter or the X-Project-Id header. Without either the request returns 400 with project_id is required.

Body Params

audience_name

string

required

Audience name.

audience_description

string

Description of the audience.

type

string

enum

required

Audience type. contact builds the audience by filtering the contact database; elixir is the former name for contact and is still accepted, so existing integrations do not need to change. Setting source_list_id treats the audience as type list regardless of the value sent here. See source_list_id, source_list_mode, and source_list_path below for list-sourced audiences. pixel builds a website visitor audience from your pixels; see the source_pixel_* fields below.

Allowed:

segmentation_type

string

enum

required

Segmentation type.

Allowed:

organization_id

uuid

required

Organization ID.

project_id

uuid

required

Project ID.

filter

object

required

A group of filter rules joined by a logical operator. Groups can be nested to create complex expressions (e.g., AND of ORs).

The values in in, not in, include and exclude rules count together across the whole filter, and a filter holds at most 50,000 of them. Past that, create, update and estimate return 400. For larger value sets, upload a list and filter on it instead of passing the values inline.

source_list_id

uuid

ID of an uploaded list to use as the audience population, instead of building the population from filter. Required when creating a list audience; setting this field is what makes the server treat the audience as type list. See the Lists & Campaigns reference for how to create and upload a list.

Availability: rolling out. list audiences can be created, but build output is not yet available for this type.

source_list_mode

string

enum

How to build the audience population from the list referenced by source_list_id. Required when source_list_id is set.

values: use the list's raw values as-is, including any values that are not found in our contact database.
matched: match each list value against our contact database and expand matched people to their full set of hashed emails and other identifiers. Every list value is kept in the audience; unmatched values are never dropped.

Allowed:

source_list_path

string

The materialized data file path for the list referenced by source_list_id, supplied by the list itself (see file_path on the list object in the Lists & Campaigns reference). Pass through the value provided by the list rather than constructing it yourself.

source_pixel_ids

array of strings

length between 1 and 20

Pixel IDs to build the audience from. Required when type is pixel, and refused on any other type. Each must be a pixel in this project; an ID from another project, or one that does not exist, returns 400 with code pixel_not_in_project.

source_pixel_ids

source_pixel_window_days

integer

1 to 90

Defaults to 30

Lookback window in days (UTC), counted back from today. pixel audiences only.

source_pixel_include_urls

array of strings

length ≤ 20

Page patterns. A person qualifies only if they viewed at least one page whose URL contains at least one of these strings. Matching is a case-insensitive substring match on the full page URL, so /pricing matches https://example.com/Pricing?plan=pro. Empty or omitted means any page counts. pixel audiences only.

source_pixel_include_urls

source_pixel_exclude_urls

array of strings

length ≤ 20

Page patterns. A person is dropped if they viewed any page whose URL contains any of these strings, even if they also match source_pixel_include_urls. Same matching as source_pixel_include_urls. pixel audiences only.

source_pixel_exclude_urls

source_pixel_min_visit_days

integer

1 to 90

Defaults to 1

Minimum number of distinct days a person was seen. Cannot exceed source_pixel_window_days. pixel audiences only.

source_pixel_output

string

enum

Defaults to all

all returns everyone who qualifies. new returns only people who were not in the previous completed build, so each refresh yields just the people who newly qualified. The first build has no earlier build to compare with and returns everyone who qualifies. pixel audiences only.

Allowed:

tier

string

enum

Defaults to intent

Intents audiences only. intent (the default) delivers intent records without trend columns and bills as Intent Signals. predictive_signals adds intent_trend and active_days_14d to every record and bills as Predictive Signals, twice the Intent Signals rate. Trend columns are included automatically at predictive_signals. Naming a trend column in select at intent returns 400 (intent_trend is a Predictive Signals field. Set tier to predictive_signals to include trends (billed as Predictive Signals).), and predictive_signals on a non-intents audience returns 400. Filtering on trend fields is allowed at either tier. Changing the tier rebuilds the audience.

Allowed:

select

string

Column projection for the unload output, applied as a SQL SELECT clause. Defaults to *, which emits the full field-catalog schema (contact and firmographic fields alongside hem, profile_pid_all, perc_score, and ts). On an intents audience * resolves to the columns of its tier: trend columns are included only at predictive_signals. Set a comma-separated column list to narrow the output, for example hem,linkedin_url,current_business_email.

unload

string

enum

preview to get a size estimate, unload to write output files. Defaults to preview.

This matters if you intend to download the audience. A preview audience is built count-only, so the first download has to rebuild it at full width before it can serve data. Passing unload at create time builds it once, correctly, and avoids that second build.

There is no unload field on the update endpoint, so switching an existing preview audience to unload means creating a new audience.

Allowed:

renew_frequency

string

enum

Schedule for automatic refresh.

daily: refreshes every day at 09:00 UTC.
weekly: refreshes every Saturday at 18:00 UTC (weekend afternoon UTC, so the weekly batch doesn't compete with daily intent refreshes at 09:00 UTC).
manual: no automatic refresh; the audience only refreshes when a caller hits POST /audiences/{id}/refresh or re-runs an unload manually.

When omitted, the default depends on type:

intents: defaults to daily (intent data is produced fresh every day).
contact (and its former name elixir): defaults to weekly (contact source data refreshes weekly/monthly; daily renewal would re-run unloads against unchanged data). Both spellings name the same type and get the same default.
list: defaults to weekly. A list changes only when you edit it, not on the daily intent cadence.
pixel: defaults to daily, because new site traffic arrives every day.

Customers who really want daily refresh on a contact audience can opt in by passing daily explicitly.

Allowed:

row_grain

string

enum

What one output row should represent. Only applicable to intents audiences.

person_topic: one row per person per topic, keeping every topic a person matched.
person: one row per person, keeping their highest-scoring topic only.

When omitted, the grain is derived from the date range for backwards compatibility: a 1-day window or a pinned range yields person_topic, a multi-day window yields person. That derivation is why widening a window used to change the row shape. Set this explicitly if the shape matters to you, and read row_grain on the audience to confirm what you got.

Allowed:

intent_start_date

string

Start of a fixed historical date range to build over (YYYYMMDD, inclusive).

Must be supplied together with intent_end_date, cannot be combined with intent_window_days, and the range may span at most 14 days. Every day in the range must have intent data available: a partially available range is rejected and the response names the missing days, rather than quietly building over the days that happen to be present.

Use this to backfill specific past days. intent_window_days is always relative to the most recent day of intent data we hold, so it cannot reach a particular date, and narrowing it to 1 still returns the latest day rather than the day you are missing.

intent_end_date

string

End of the fixed historical date range (YYYYMMDD, inclusive). Required when intent_start_date is set. See intent_start_date.

intent_window_days

integer

1 to 14

Number of recent days of intent data to include (1-14). Only applicable to intents audiences. Default: 1. Cannot be combined with intent_start_date/intent_end_date.

Note this also determines the default row_grain when that field is omitted, so changing the window changes the row shape unless you set row_grain explicitly.

record_limit

integer

0 to 10000000

Cap the audience at this many records, from 0 to 10,000,000; 0 means no cap. Supported on intents, contact and list audiences; pixel audiences do not support it. With a cap set, downloads and exports bill at most this many records.

status

string

Initial status.

Headers

X-Project-Id

uuid

Project ID (UUID). Equivalent to the project_id query parameter; send one or the other.

Responses

401

Missing or invalid authentication.

403

Forbidden. Also returned when a filter or select uses a partner data field from a dataset that is not enabled for the project.

500

Internal server error.

201Audience created.

400Invalid request body, or a filter with more than 50,000 inline values (filter contains N inline values (max 50000); use file-based filters for large lists).

409partner_price_not_accepted: a partner data field's dataset has no accepted price. partners lists the datasets to accept.

413The request body is larger than the 8 MiB (8,388,608 byte) limit. For large value lists, upload a list and filter on it instead of sending the values inline.