Bulk create segments
const url = 'https://api.infiniteaudience.ai/v1/segments/bulk-create';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"campaign_id":"example","segments":[{"name":"example","subtype":"filter","filters":[{"field":"example","op":"=","text_comparison":"exact","trim_whitespace":true,"value":["example"]}],"filter_groups":[{"id":"example","filters":[{"field":"example","op":"=","text_comparison":"exact","trim_whitespace":true,"value":["example"]}],"combinator":"AND"}],"count_snapshot":1,"record_limit":1,"create_audience":false}]}'};
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/segments/bulk-create \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "campaign_id": "example", "segments": [ { "name": "example", "subtype": "filter", "filters": [ { "field": "example", "op": "=", "text_comparison": "exact", "trim_whitespace": true, "value": [ "example" ] } ], "filter_groups": [ { "id": "example", "filters": [ { "field": "example", "op": "=", "text_comparison": "exact", "trim_whitespace": true, "value": [ "example" ] } ], "combinator": "AND" } ], "count_snapshot": 1, "record_limit": 1, "create_audience": false } ] }'Create up to 25 filter-subtype segments in one request. Each segment is created independently (own versions/1 snapshot); failures are reported per item in errors and do not roll back successful items. Returns 201 when at least one segment was created, 400 (same body shape) when every item failed. Use POST /v1/segments individually for matched/similarity/propensity segments.
Requires ‘creator’ scope.
Each item’s filters/filter_groups are validated against the live Field Catalog before it’s created — an unknown field, a disallowed operator, or an invalid enum value fails that item only, reported in errors (same as any other per-item failure). If the Field Catalog itself is temporarily unreachable, the entire request fails with 502 FILTER_CATALOG_UNAVAILABLE rather than creating some segments unvalidated.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
Campaign the whole batch is built for — every created segment’s origin_campaign_id, and the campaign each create_audience wrapper is linked to. Optional; same defaulting and 400 INVALID_CAMPAIGN_ID as POST /v1/segments.
object
Display name for the segment.
Only ‘filter’ is supported by bulk-create — any other value fails per-item with an entry in errors.
Legacy flat filter list.
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
Filter groups defining the segment criteria.
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.
Optional known record count to seed the segment with.
Caps this filter segment at this many people; see POST /v1/segments.
When true, auto-creates a thin audience wrapper for this segment (returned as audience_id on the created segment).
Responses
Section titled “Responses”At least one segment created. Check errors for partial failures.
Result of POST /v1/segments/bulk-create. Returned with 201 when at least one segment was created, and with 400 (same shape) when every item failed.
object
Number of segments successfully created.
Number of input items that could not be created.
Full segment documents for each successfully created segment.
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
object
Unique segment identifier
Display name of the segment
Segment subtype. Determines which additional attributes are present. filter = saved filter criteria; matched = customer list upload with identity resolution; similarity = lookalike model; propensity = ML scoring model.
Pending = computation in progress (matched/similarity/propensity during creation); active = fully ready; failed = workflow or enrichment error (see error_message); archived = hidden from the default segment catalog and new audience compositions, but otherwise fully functional — audiences that already reference an archived segment are unaffected, and it can be restored with PATCH status:active at any time. Distinct from DELETE, which is not reversible and does change referencing audiences’ composition; expired = past 90-day TTL.
Total matched/qualified records. Null while pending or if count has not been run.
Date-only ISO string (90-day hard expiry from creation) for a persistent segment; a full ISO datetime (short, hour-granular TTL) while ephemeral is true.
Org (default) — visible to all members of the org. private — visible only to the creating user.
Filter subtype only. Current version counter.
Filter subtype only — membership cap; null when uncapped (see POST /v1/segments)
Filter subtype only. Complete saved definition; a single AND group represents a flat input.
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.
Matched subtype only. Input file format.
Matched subtype only. Input artifact compression, normalized to none by current handlers.
Matched subtype only. Number of same-format input objects, normalized to 1 for unsharded uploads.
Matched subtype only. Source column name → standard identity attribute mappings. Populated after the analyze-and-store workflow gate runs.
Matched subtype only. True once column mappings have been confirmed.
Matched subtype only. Number of rows in the original upload.
Matched subtype only. Rows that resolved to a known identity after enrichment.
Matched subtype only. match_count / input_record_count.
Matched subtype only. 30-minute signed upload URL. Present on create and refresh responses only, when shard_count was 1 (the default) — absent when sharded, use upload_urls instead.
Matched subtype only. N signed upload URLs (index-ordered). Present on create and refresh responses only when shard_count > 1 was requested — upload_url is absent. Every CSV shard must include the same header row.
Matched subtype only. Expiry of upload_url/upload_urls.
Present when status is failed. Describes the reason for failure.
Matched subtype only. Opaque, read-only reference to stored match results when they are shared or versioned independently from the segment metadata. Null when no separate result reference is needed.
Similarity subtype only. Natural language ICP persona description used as seed.
Similarity subtype only. ID of an existing segment used as the lookalike seed.
Similarity and propensity subtypes. The workflow run ID. Poll GET /v1/workflows/{workflow_run_id} to monitor progress.
Propensity subtype only. ID of the segment whose members are the positive training class.
ID of the segment this was duplicated or derived from, if applicable.
Root ancestor segment ID. Stable across duplicate-of-duplicate chains — always points at the original segment, never an intermediate duplicate.
Version of the parent segment pinned at duplicate time (current_version for filter parents; snapshot_version otherwise). Null on segments that are not duplicates.
ID of the campaign whose chat session first produced this segment. Metadata only — does not restrict the segment to that campaign. Present only when the segment was created via POST /v1/segments with a campaign_id.
Cross-campaign usage stats. Only present on GET /v1/segments/{id} — not included on list responses. Useful for understanding impact before archiving.
object
Number of active audiences that reference this segment.
Number of distinct campaigns those audiences belong to.
Auto-created audience wrapper ID. Present only when the input item set create_audience: true.
Per-item failures. Empty when all items succeeded.
object
Zero-based position of the failed item in the input segments array.
The name from the failed input item.
Human-readable reason the segment could not be created.
Example
{ "segments": [ { "integration_collection_provenance": { "version": 1, "mode": "new_segment" }, "subtype": "filter", "status": "pending", "visibility": "org", "filter_groups": [ { "filters": [ { "op": "=", "text_comparison": "exact" } ], "combinator": "AND" } ], "file_format": "csv", "compression": "none" } ]}Every input item failed (created: 0) — same body shape as 201 with per-item reasons in errors — or the request body failed validation (standard error shape).
Result of POST /v1/segments/bulk-create. Returned with 201 when at least one segment was created, and with 400 (same shape) when every item failed.
object
Number of segments successfully created.
Number of input items that could not be created.
Full segment documents for each successfully created segment.
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
object
Unique segment identifier
Display name of the segment
Segment subtype. Determines which additional attributes are present. filter = saved filter criteria; matched = customer list upload with identity resolution; similarity = lookalike model; propensity = ML scoring model.
Pending = computation in progress (matched/similarity/propensity during creation); active = fully ready; failed = workflow or enrichment error (see error_message); archived = hidden from the default segment catalog and new audience compositions, but otherwise fully functional — audiences that already reference an archived segment are unaffected, and it can be restored with PATCH status:active at any time. Distinct from DELETE, which is not reversible and does change referencing audiences’ composition; expired = past 90-day TTL.
Total matched/qualified records. Null while pending or if count has not been run.
Date-only ISO string (90-day hard expiry from creation) for a persistent segment; a full ISO datetime (short, hour-granular TTL) while ephemeral is true.
Org (default) — visible to all members of the org. private — visible only to the creating user.
Filter subtype only. Current version counter.
Filter subtype only — membership cap; null when uncapped (see POST /v1/segments)
Filter subtype only. Complete saved definition; a single AND group represents a flat input.
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.
Matched subtype only. Input file format.
Matched subtype only. Input artifact compression, normalized to none by current handlers.
Matched subtype only. Number of same-format input objects, normalized to 1 for unsharded uploads.
Matched subtype only. Source column name → standard identity attribute mappings. Populated after the analyze-and-store workflow gate runs.
Matched subtype only. True once column mappings have been confirmed.
Matched subtype only. Number of rows in the original upload.
Matched subtype only. Rows that resolved to a known identity after enrichment.
Matched subtype only. match_count / input_record_count.
Matched subtype only. 30-minute signed upload URL. Present on create and refresh responses only, when shard_count was 1 (the default) — absent when sharded, use upload_urls instead.
Matched subtype only. N signed upload URLs (index-ordered). Present on create and refresh responses only when shard_count > 1 was requested — upload_url is absent. Every CSV shard must include the same header row.
Matched subtype only. Expiry of upload_url/upload_urls.
Present when status is failed. Describes the reason for failure.
Matched subtype only. Opaque, read-only reference to stored match results when they are shared or versioned independently from the segment metadata. Null when no separate result reference is needed.
Similarity subtype only. Natural language ICP persona description used as seed.
Similarity subtype only. ID of an existing segment used as the lookalike seed.
Similarity and propensity subtypes. The workflow run ID. Poll GET /v1/workflows/{workflow_run_id} to monitor progress.
Propensity subtype only. ID of the segment whose members are the positive training class.
ID of the segment this was duplicated or derived from, if applicable.
Root ancestor segment ID. Stable across duplicate-of-duplicate chains — always points at the original segment, never an intermediate duplicate.
Version of the parent segment pinned at duplicate time (current_version for filter parents; snapshot_version otherwise). Null on segments that are not duplicates.
ID of the campaign whose chat session first produced this segment. Metadata only — does not restrict the segment to that campaign. Present only when the segment was created via POST /v1/segments with a campaign_id.
Cross-campaign usage stats. Only present on GET /v1/segments/{id} — not included on list responses. Useful for understanding impact before archiving.
object
Number of active audiences that reference this segment.
Number of distinct campaigns those audiences belong to.
Auto-created audience wrapper ID. Present only when the input item set create_audience: true.
Per-item failures. Empty when all items succeeded.
object
Zero-based position of the failed item in the input segments array.
The name from the failed input item.
Human-readable reason the segment could not be created.
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.
Example
{ "segments": [ { "integration_collection_provenance": { "version": 1, "mode": "new_segment" }, "subtype": "filter", "status": "pending", "visibility": "org", "filter_groups": [ { "filters": [ { "op": "=", "text_comparison": "exact" } ], "combinator": "AND" } ], "file_format": "csv", "compression": "none" } ]}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."}Field Catalog temporarily unreachable — no items were validated or created (code FILTER_CATALOG_UNAVAILABLE).