Audiences

Create an audience

Creates a named audience — a subtype-agnostic composition wrapper that references one or more segments (include or exclude role) for delivery.

Audiences are always status: active immediately on creation. The underlying segments determine data readiness — only deliver an audience after all its include-role segments are active.

Composition options:

  • Use segment_refs (preferred) to specify each segment and its role (include or exclude) explicitly.

  • Use segment_ids / excluded_segment_ids (convenience shorthand) as a flat list when all included segments share the same include role.

  • Use set_logic to control how multiple include-role segments are combined: union (default) — a record matches ANY included segment (OR) — or intersection — a record must match EVERY included segment (AND).

  • Excluded segments are always subtracted from the composed include result (AND NOT), regardless of set_logic: result = (included segments combined by set_logic) MINUS (excluded segments).

To create matched, similarity, or propensity segments, use POST /v1/segments. An unknown campaign_id returns 400 INVALID_CAMPAIGN_ID and nothing is created. Requires 'creator' scope.

post/v1/audiences

Request

  • Base URL: https://api.infiniteaudience.ai
  • URL: https://api.infiniteaudience.ai/v1/audiences
  • Auth: HTTP bearer

Request body

namestring required

Display name for the audience.

segment_idsstring[]

Convenience shorthand: IDs of segments to include (role: include). Use segment_refs for mixed include/exclude compositions.

excluded_segment_idsstring[]

Convenience shorthand: IDs of segments to exclude from the composition.

set_logic'union' | 'intersection'

How to combine the include-role segments. Exclusions always apply as AND NOT.

visibility'org' | 'private'

org (default) — visible to all members of the org. private — visible only to the creating user.

campaign_idstring

Optional. If provided, the created audience is automatically linked to this campaign. The audience can belong to at most one campaign at a time. Omit if you are not using campaign workspaces. Must name an existing campaign in your organisation; an unknown id returns 400 INVALID_CAMPAIGN_ID and nothing is created.

Response

Audience created.

audience_idstring required
namestring required
status'active' | 'archived' | 'expired' required

active = ready for delivery; archived = soft-deleted via PATCH status:archived (excluded from list by default); expired = past 90-day TTL. Note: pending/failed statuses belong on segments, not audiences.

versioninteger required
quote_idstring nullable

ID of the most recent delivery quote for this audience.

quote_total_centsinteger nullable

Total cost in cents from the most recent delivery quote.

parent_audience_idstring nullable

ID of the audience this was forked from (null if not a fork).

forked_from_snapshot_versioninteger nullable

Snapshot version of the parent audience at the time of forking.

record_countinteger nullable

Total resolved records across all composed segments.

matched_record_countinteger nullable

Records contributed by matched-subtype segments in this audience's composition. Present only when the composition includes at least one included matched segment; null for pure-filter or non-matched compositions.

match_countinteger nullable

Records resolved to a known identity, for an audience created via the direct file-upload flow (POST /v1/match/file). Populated when that upload's matching pipeline completes; null before then or for audiences not created that way — use matched_record_count for a composition-level matched count instead.

input_record_countinteger nullable

Rows in the originally uploaded identity file, for an audience created via POST /v1/match/file. Same population conditions as match_count.

match_ratenumber nullable

match_count / input_record_count, rounded to 4 decimal places. Null unless both match_count and input_record_count are present.

expires_atstring required

ISO date — 90-day hard expiry from creation

version_created_atstring nullable
visibility'org' | 'private' required

org (default) — visible to all members of the org. private — visible only to the creating user.

segment_idsstring[]

Cache of include-role segment IDs (denormalized from segment_refs for query efficiency).

excluded_segment_idsstring[]

Cache of exclude-role segment IDs (denormalized from segment_refs for query efficiency).

set_logic'union' | 'intersection'

How the include-role segments are combined: union = a record matches ANY included segment (OR); intersection = a record must match EVERY included segment (AND). Segments in excluded_segment_ids are always subtracted from that result (AND NOT), regardless of set_logic.

created_atstring date-time required
updated_atstring date-time required
campaign_idstring nullable required

The one campaign this audience belongs to, or null.

Changes

No recorded changes to this operation across all 1 revision of this API.