Partially update an audience
const url = 'https://dev-api.infiniteaudience.ai/v1/audiences/example';const options = { method: 'PATCH', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"example","status":"archived","set_logic":"union","add_segment_id":"example","remove_segment_id":"example","add_excluded_segment_id":"example","remove_excluded_segment_id":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url https://dev-api.infiniteaudience.ai/v1/audiences/example \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "example", "status": "archived", "set_logic": "union", "add_segment_id": "example", "remove_segment_id": "example", "add_excluded_segment_id": "example", "remove_excluded_segment_id": "example" }'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 ‘purchase’ scope.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Request Bodyrequired
Section titled “Request Bodyrequired”object
Rename the audience.
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.
Append a single segment ID to the included list.
Remove a single segment ID from the included list.
Append a single segment ID to the excluded list.
Remove a single segment ID from the excluded list.
Responses
Section titled “Responses”Updated audience.
object
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.
ID of the most recent delivery quote for this audience.
Total cost in cents from the most recent delivery quote.
ID of the audience this was forked from (null if not a fork).
Snapshot version of the parent audience at the time of forking.
ID of the campaign this audience is linked to, if any.
Total resolved records across all composed segments.
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.
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.
Rows in the originally uploaded identity file, for an audience created via POST /v1/match/file. Same population conditions as match_count.
Match_count / input_record_count, rounded to 4 decimal places. Null unless both match_count and input_record_count are present.
ISO date — 90-day hard expiry from creation
Org (default) — visible to all members of the org. private — visible only to the creating user.
Composition of segments that define this audience. Each entry specifies a segment and its role (include or exclude) in the set operation.
object
ID of the referenced segment.
Whether the segment’s records are included in or excluded from the audience.
Cache of include-role segment IDs (denormalized from segment_refs for query efficiency).
Cache of exclude-role segment IDs (denormalized from segment_refs for query efficiency).
Expanded summaries of the include-role segments, in segment_ids order. Populated on both list and single-GET responses. Best-effort — missing or deleted segment docs are skipped, so this array may be shorter than segment_ids.
Lightweight summary of a constituent segment, expanded server-side from the audience’s composition. Returned on both list and single-GET audience responses. subtype is the segment’s own subtype — use the first entry of segments (the primary included segment) to derive subtype-specific presentation for the audience.
object
Segment document ID.
Segment display name.
Cached record count of the segment. Null if never counted.
Subtype of the constituent segment.
Matched subtype only. Count of records in the uploaded identity file. Null otherwise.
Matched subtype only. Count of records successfully matched. Null otherwise.
Expanded summaries of the exclude-role segments, in excluded_segment_ids order. Same expansion semantics as segments.
Lightweight summary of a constituent segment, expanded server-side from the audience’s composition. Returned on both list and single-GET audience responses. subtype is the segment’s own subtype — use the first entry of segments (the primary included segment) to derive subtype-specific presentation for the audience.
object
Segment document ID.
Segment display name.
Cached record count of the segment. Null if never counted.
Subtype of the constituent segment.
Matched subtype only. Count of records in the uploaded identity file. Null otherwise.
Matched subtype only. Count of records successfully matched. Null otherwise.
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.
Example
{ "status": "active", "visibility": "org", "segment_refs": [ { "role": "include" } ], "segments": [ { "subtype": "filter" } ], "excluded_segments": [ { "subtype": "filter" } ], "set_logic": "union"}Invalid request — malformed body, missing required attribute, or failed validation. See error and message for details.
object
Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.
Human-readable explanation of the error.
Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.
Opaque support/debug identifier when available.
Examples
{ "error": "Bad Request", "code": "MISSING_SEGMENTS", "message": "segment_ids is required for filter audiences."}Missing or invalid Bearer token. Obtain one via POST /v1/auth/token. When a token was supplied but rejected, code distinguishes TOKEN_EXPIRED (the token’s lifetime has passed — request a new one via POST /v1/auth/token and retry) from TOKEN_INVALID (malformed or revoked — re-authenticate).
object
Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.
Human-readable explanation of the error.
Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.
Opaque support/debug identifier when available.
Examples
{ "error": "Unauthorized: Missing or invalid Authorization header"}{ "error": "Unauthorized", "code": "TOKEN_EXPIRED", "message": "Your session has expired. Please sign in again."}Token is valid but lacks the required scope for this endpoint. Check the endpoint description for the required scope (discovery, purchase, or account).
object
Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.
Human-readable explanation of the error.
Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.
Opaque support/debug identifier when available.
Examples
{ "error": "SCOPE_REQUIRED", "message": "This endpoint requires the purchase scope."}Resource not found or not accessible to the calling org.
object
Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.
Human-readable explanation of the error.
Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.
Opaque support/debug identifier when available.
Examples
{ "error": "Audience not found"}