Audiences

Partially update an audience

Applies a partial update to an audience. Accepts any subset of the attributes below — only provided attributes are updated. Use add_segment_id / remove_segment_id for incremental segment edits (preferred over replacing the full segment_ids array). Use name to rename.

Composition model: set_logic: union combines included segments with OR (match ANY); intersection combines them with AND (match EVERY). Excluded segments (add_excluded_segment_id) are always subtracted from that result (AND NOT), regardless of set_logic. Requires 'creator' scope.

patch/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

Rename the audience.

status'archived' | 'active'

Valid user-settable transitions: archived — soft-deletes the audience; excluded from list results by default. active — restores a previously archived audience back to active; rejected with 400 (INVALID_STATUS_TRANSITION) if the current status is not archived. System-managed statuses (pending, expired, failed) cannot be set via this endpoint and will be rejected with 400.

set_logic'union' | 'intersection'
add_segment_idstring

Append a single segment ID to the included list.

remove_segment_idstring

Remove a single segment ID from the included list.

add_excluded_segment_idstring

Append a single segment ID to the excluded list.

remove_excluded_segment_idstring

Remove a single segment ID from the excluded list.

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.