Create audience

post

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

Create a new audience with the specified type and parameters.

Type-specific requirements:

events: Requires filter with filter rules for pixel event data.
intents: Requires filter with topic-based intent criteria.
elixir: Requires filter with Elixir dataset criteria.
list: Requires source_list_id and source_list_mode instead of filter. The audience population comes directly from an uploaded list. 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.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

audience_name

string

required

Audience name.

audience_description

string

Description of the audience.

type

string

enum

required

Audience type. 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.

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).

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.

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). 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.

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).
elixir: defaults to weekly (Elixir source data refreshes weekly/monthly; daily renewal would re-run unloads against unchanged data).

Customers who really want daily refresh on an elixir audience can opt in by passing daily explicitly.

Allowed:

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.

status

string

Initial status.

Responses

401

Missing or invalid authentication.

403

Forbidden.

500

Internal server error.

201Audience created.

400Invalid request body.