Create a segment
const url = 'https://dev-api.infiniteaudience.ai/v1/segments';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"West Coast Adults 25-44","subtype":"filter","filter_groups":[{"id":"g1","filters":[{"field":"state","op":"IN","value":["CA","OR","WA"]}],"combinator":"AND"}],"create_audience":true}'};
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://dev-api.infiniteaudience.ai/v1/segments \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "West Coast Adults 25-44", "subtype": "filter", "filter_groups": [ { "id": "g1", "filters": [ { "field": "state", "op": "IN", "value": [ "CA", "OR", "WA" ] } ], "combinator": "AND" } ], "create_audience": true }'Creates a typed cohort definition (segment). The subtype attribute controls which additional parameters are required and what the platform does next.
Subtypes:
-
filter (default) — Saves a named filter expression. Returns
status: activeimmediately. Usefilters/filter_groupsfor the criteria. Passcreate_audience: trueto also create a thin audience wrapper referencing this segment. Default:false— the segment is saved for later composition into an audience once iterative refinement is complete. -
matched — Upload your own customer list for identity resolution. Returns
status: pending+upload_url(30-min presigned GCS PUT URL) — orupload_urls(an array, one per shard) whenshard_count> 1, in which caseupload_urlis absent. Input may be raw or gzip. Withhitlunset/false (default): upload your file(s) and the platform runs column mapping and identity resolution automatically once every declared shard has been uploaded, transitioning tostatus: activewhen complete — no further calls required. Withhitl: true: the upload is staged instead of resolving automatically — see thehitlfield description below for the full preview/confirm/cancel sequence. Whencreate_audience: true(default for matched), a thin audience wrapper is also created automatically. -
similarity — Lookalike modelling. Provide
seed_description(natural language ICP persona) orseed_segment_id(an existing segment) — not both — to launch a new workflow. Returnsstatus: pending+workflow_run_id. Alternatively, providegeneration_metadata_id(an existingicp_id) with no seed fields to attach that already-completed ICP run directly — no workflow is launched,status: activeimmediately. Defaultcreate_audience: false. -
propensity — ML propensity scoring. Provide
positive_class_segment_id(an existing segment whose members are the positive training class) to launch a new workflow. Returnsstatus: pending+workflow_run_id. Alternatively, providegeneration_metadata_id(an existingmodel_id) with nopositive_class_segment_idto attach that already-completed model run directly — no workflow is launched,status: activeimmediately. Defaultcreate_audience: false.
Poll GET /v1/segments/{id} for status, or configure a webhook to receive segment.ready / segment.failed events.
Requires ‘purchase’ scope.
For filter subtype: filters/filter_groups are validated against the live Field Catalog before the segment is created — an unknown field, a disallowed operator for that field, or an invalid enum value returns 400 INVALID_FILTER. If the Field Catalog itself is temporarily unreachable, returns 502 FILTER_CATALOG_UNAVAILABLE rather than creating an unvalidated segment.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
Display name for the segment.
Segment subtype. Determines which additional attributes are required.
When true, automatically creates a thin audience wrapper referencing this segment. Defaults: filter=true, matched=true, similarity=false, propensity=false.
Filter subtype only. Flat filter array (legacy). Prefer filter_groups.
A single filter condition for audience discovery or job execution
Filter subtype only. Grouped filter conditions.
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
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. csv (default) treats every column as a single scalar value — multi-value/array attributes are not supported in csv. avro, json, and jsonl support native array columns for attributes that require them — json and jsonl are both parsed as newline-delimited JSON (one record object per line), not a single top-level JSON array.
Matched subtype only. gzip means the complete underlying format file is a gzip stream. Upload raw gzip bytes using the underlying format’s Content-Type and no Content-Encoding. gzip is not supported with file_format=avro (avro is already internally compressed) — rejected with 400 UNSUPPORTED_INPUT_COMPRESSION.
Matched subtype only. Set > 1 for same-format shards. Every CSV shard must include the same header row, and all shards must share schema and compression. Returns upload_urls instead of upload_url.
Similarity subtype only. Natural language description of the target ICP persona. Provide either seed_description or seed_segment_id, not both.
Similarity subtype only. ID of an existing segment to use as the lookalike seed. Provide either seed_description or seed_segment_id, not both.
Propensity subtype only. ID of an existing segment whose members represent the positive training class for ML model training.
Similarity subtype: an existing icp_id. propensity subtype: an existing model_id. When provided without seed_description/seed_segment_id (similarity) or positive_class_segment_id (propensity), attaches that already-completed run to a new segment instead of launching a new workflow — status: active immediately, no workflow_run_id.
Org (default) — visible to all org members. private — visible only to creator.
Requires an explicit confirmation step before the automated pipeline proceeds. For similarity/propensity, the workflow pauses at a human-in-the-loop review gate. For matched, the uploaded file is staged instead of landing at the path that triggers automatic identity resolution — call POST /v1/match/{id}/analyze to preview column mappings against the staged file, then POST /v1/segments/{id}/mappings to confirm (moves the file into place and starts resolution) or POST /v1/segments/{id}/mappings/cancel to abort (the segment is left completely untouched). Defaults to false — omit for the existing automatic-resolution behavior.
Optional. If provided and create_audience is true, the created audience is automatically linked to this campaign.
Optional HTTPS URL to receive segment.ready or segment.failed events. Overrides the org-level webhook URL for this request only.
Filter subtype only. When true, creates a scratch/free/auto-expiring segment with a short, hour-granular TTL instead of the standard 90-day expiry. Excluded from GET /v1/segments by default (see include_ephemeral there). Promote it to persistent later via PATCH /v1/segments/{id} {ephemeral: false}, or implicitly by composing it into an audience. Defaults to false (persistent, today’s behavior).
Examples
Filter segment
{ "name": "West Coast Adults 25-44", "subtype": "filter", "filter_groups": [ { "id": "g1", "filters": [ { "field": "state", "op": "IN", "value": [ "CA", "OR", "WA" ] } ], "combinator": "AND" } ], "create_audience": true}Matched segment (customer CSV upload)
{ "name": "Q3 CRM Upload", "subtype": "matched", "file_format": "csv", "create_audience": true}Similarity segment (lookalike)
{ "name": "Lookalike of best customers", "subtype": "similarity", "seed_description": "Homeowners aged 35-55 with household income above $80k", "hitl": false}Propensity segment (ML scoring)
{ "name": "High-Intent Refinance Prospects", "subtype": "propensity", "positive_class_segment_id": "seg_abc123"}Responses
Section titled “Responses”Segment created.
object
Date-only ISO string (90-day expiry) for a persistent segment; a full ISO datetime (short, hour-granular TTL) while ephemeral is true.
True for a scratch/auto-expiring filter-subtype segment. Absent/false reads as persistent.
Matched subtype only. 30-min presigned GCS PUT URL. Present when shard_count was 1 (the default) — absent when sharded, use upload_urls instead.
Matched subtype only. N presigned GCS PUT URLs (index-ordered). Present only when shard_count > 1 was requested — upload_url is absent. Every CSV shard must include the same header row.
Matched subtype only. Input artifact compression.
Matched subtype only. Expiry of upload_url/upload_urls.
Similarity/propensity subtypes. Workflow run ID for progress monitoring.
If create_audience was true, the ID of the auto-created audience wrapper. Null otherwise.
Examples
Filter segment created
{ "segment_id": "seg_abc123", "name": "West Coast Adults 25-44", "subtype": "filter", "status": "active", "record_count": null, "expires_at": "2026-09-27", "ephemeral": false, "audience_id": "aud_abc123", "created_at": "2026-06-22T18:00:00Z", "updated_at": "2026-06-22T18:00:00Z"}Matched segment created — ready for file upload
{ "segment_id": "seg_m789", "name": "Q3 CRM Upload", "subtype": "matched", "status": "pending", "record_count": null, "expires_at": "2026-09-27", "ephemeral": false, "upload_url": "https://storage.googleapis.com/cf-uploads/enrichment-uploads/org_x/seg_m789/input.csv?X-Goog-Signature=...", "upload_expires_at": "2026-06-22T19:30:00.000Z", "audience_id": "aud_m789", "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.
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."}Field Catalog temporarily unreachable — filters could not be validated (code FILTER_CATALOG_UNAVAILABLE).