Create an audience
const url = 'https://api.infiniteaudience.ai/v1/audiences';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"West Coast Adults 25-44","segment_refs":[{"segment_id":"seg_abc123","role":"include"},{"segment_id":"seg_def456","role":"include"},{"segment_id":"seg_sup789","role":"exclude"}],"set_logic":"union"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.infiniteaudience.ai/v1/audiences \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "West Coast Adults 25-44", "segment_refs": [ { "segment_id": "seg_abc123", "role": "include" }, { "segment_id": "seg_def456", "role": "include" }, { "segment_id": "seg_sup789", "role": "exclude" } ], "set_logic": "union" }'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 (includeorexclude) explicitly. -
Use
segment_ids/excluded_segment_ids(convenience shorthand) as a flat list when all included segments share the same include role. -
Use
set_logicto control how multiple include-role segments are combined:union(default) — a record matches ANY included segment (OR) — orintersection— 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.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
Display name for the audience.
Preferred composition format. Each entry specifies a segment and its role. Supersedes segment_ids / excluded_segment_ids if provided.
object
Convenience shorthand: IDs of segments to include (role: include). Use segment_refs for mixed include/exclude compositions.
Convenience shorthand: IDs of segments to exclude from the composition.
How to combine the include-role segments. Exclusions always apply as AND NOT.
Org (default) — visible to all members of the org. private — visible only to the creating user.
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.
Examples
Audience with explicit segment roles
{ "name": "West Coast Adults 25-44", "segment_refs": [ { "segment_id": "seg_abc123", "role": "include" }, { "segment_id": "seg_def456", "role": "include" }, { "segment_id": "seg_sup789", "role": "exclude" } ], "set_logic": "union"}Audience using shorthand segment_ids
{ "name": "Q3 CRM Audience", "segment_ids": [ "seg_abc123", "seg_def456" ], "set_logic": "union"}Audience linked to a campaign
{ "name": "Q3 West Coast Adults", "segment_ids": [ "seg_abc123" ], "campaign_id": "camp_abc123"}Responses
Section titled “Responses”Audience created.
object
Delivered IAG refresh version. Independent of license status. Null provenance means unknown; a newer refresh-major can prompt a refresh through existing workflows. Active licenses and existing identity IDs support free refresh; normal charges may apply otherwise.
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.
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.
Constituent segment summary and saved filter definition. Audiences may combine multiple segment subtypes; there is no primary segment or audience subtype.
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.
A group of Filter conditions. All filters within a single group are always ANDed together — there is no per-group intra-operator. The combinator attribute is an inter-group operator: it controls how this group is joined to the immediately preceding group in the array. The combinator on the first group (index 0) is always ignored.
Example — (city = "NYC" AND state = "NY") OR (state = "CA"):
{ "id": "g1", "filters": [{"field":"city","op":"=","value":"NYC"},
{"field":"state","op":"=","value":"NY"}],
"combinator": "AND" },
{ "id": "g2", "filters": [{"field":"state","op":"=","value":"CA"}],
"combinator": "OR" }
] ```
Group g1's `combinator` is irrelevant (it is the first group). Group g2's `combinator: "OR"` means the result is `(g1) OR (g2)`.object
Stable identifier (UUID or NanoID). Used to track groups across edits.
One or more filter conditions. All conditions in this array are combined with AND. Provide at least one filter per group.
A single filter condition for audience discovery or job execution
object
Canonical catalog field_name (e.g. age or state). ZIP5 also accepts zip, zip_code, or postal_code as input aliases; saved responses use zip5.
Comparison operator
Optional STRING comparison mode for =, !=, IN, NOT IN, and LIKE, or ARRAY
Optionally trim leading and trailing whitespace on both sides of a STRING or ARRAY
Inter-group operator. Joins this group to the previous group in the array. AND narrows the result; OR broadens it. Ignored on the first group (index 0) — that group has no predecessor to join.
Expanded summaries of the exclude-role segments, in excluded_segment_ids order. Same expansion semantics as segments.
Constituent segment summary and saved filter definition. Audiences may combine multiple segment subtypes; there is no primary segment or audience subtype.
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.
A group of Filter conditions. All filters within a single group are always ANDed together — there is no per-group intra-operator. The combinator attribute is an inter-group operator: it controls how this group is joined to the immediately preceding group in the array. The combinator on the first group (index 0) is always ignored.
Example — (city = "NYC" AND state = "NY") OR (state = "CA"):
{ "id": "g1", "filters": [{"field":"city","op":"=","value":"NYC"},
{"field":"state","op":"=","value":"NY"}],
"combinator": "AND" },
{ "id": "g2", "filters": [{"field":"state","op":"=","value":"CA"}],
"combinator": "OR" }
] ```
Group g1's `combinator` is irrelevant (it is the first group). Group g2's `combinator: "OR"` means the result is `(g1) OR (g2)`.object
Stable identifier (UUID or NanoID). Used to track groups across edits.
One or more filter conditions. All conditions in this array are combined with AND. Provide at least one filter per group.
A single filter condition for audience discovery or job execution
object
Canonical catalog field_name (e.g. age or state). ZIP5 also accepts zip, zip_code, or postal_code as input aliases; saved responses use zip5.
Comparison operator
Optional STRING comparison mode for =, !=, IN, NOT IN, and LIKE, or ARRAY
Optionally trim leading and trailing whitespace on both sides of a STRING or ARRAY
Inter-group operator. Joins this group to the previous group in the array. AND narrows the result; OR broadens it. Ignored on the first group (index 0) — that group has no predecessor to join.
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.
The one campaign this audience belongs to, or null.
Examples
Audience created
{ "audience_id": "aud_abc123", "name": "West Coast Adults 25-44", "campaign_id": "camp_abc123", "status": "active", "version": 1, "record_count": null, "expires_at": "2026-09-27", "visibility": "org", "segment_refs": [ { "segment_id": "seg_abc123", "role": "include" }, { "segment_id": "seg_def456", "role": "include" } ], "segment_ids": [ "seg_abc123", "seg_def456" ], "excluded_segment_ids": [], "segments": [ { "id": "seg_abc123", "name": "West Coast States", "record_count": 1204331, "subtype": "filter", "input_record_count": null, "match_count": null }, { "id": "seg_def456", "name": "Adults 25-44", "record_count": 8443210, "subtype": "filter", "input_record_count": null, "match_count": null } ], "excluded_segments": [], "set_logic": "union", "created_at": "2026-06-22T18:00:00Z", "updated_at": "2026-06-22T18:00:00Z"}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.
Public action for correcting the request or retrying later.
object
JSON path to the invalid filter field or value.
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.
Public action for correcting the request or retrying later.
object
JSON path to the invalid filter field or value.
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.
Public action for correcting the request or retrying later.
object
JSON path to the invalid filter field or value.
Examples
{ "error": "SCOPE_REQUIRED", "message": "This endpoint requires the creator scope."}