Audiences

Update an audience

Fully replaces the audience's name, segment_ids, excluded_segment_ids, and set_logic with the provided values. Audiences are subtype-agnostic composition wrappers — to change which segments are composed, update the segment ID lists here.

Composition model: set_logic: union combines included segments with OR (match ANY); intersection combines them with AND (match EVERY). Segments in excluded_segment_ids are always subtracted from that result (AND NOT), regardless of set_logic.

Count invalidation: changing the segment composition clears the cached record_count. Call POST /v1/audiences/{id}/count after updating to recompute it. The record_count will be null until recomputed.

Versioning: the audience version is incremented on every successful PUT. Previously completed deliveries at prior versions remain accessible in delivery history.

The update itself emits no billable usage. Requires 'creator' scope.

put/v1/audiences/{id}

Request

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

Path parameters

idstring required

Request body

namestring
segment_idsstring[]

Full replacement list of included segment IDs.

excluded_segment_idsstring[]

Full replacement list of excluded segment IDs.

set_logic'union' | 'intersection'

Response

Updated audience.

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.