Segments

Create a segment

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: active immediately. Use filters/filter_groups for the criteria. Pass create_audience: true to 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-minute signed upload URL) — or upload_urls (an array, one per shard) when shard_count > 1, in which case upload_url is absent. Input may be raw or gzip. With hitl unset/false (default): upload your file(s) and the platform runs column mapping and identity resolution automatically once every declared shard has been uploaded, transitioning to status: active when complete — no further calls required. With hitl: true: the upload is staged instead of resolving automatically — see the hitl field description below for the full preview/confirm/cancel sequence. When create_audience: true (default for matched), a thin audience wrapper is also created automatically.

  • similarity — Lookalike modelling. Provide seed_description (natural language ICP persona) or seed_segment_id (an existing segment) — not both — to launch a new workflow. Returns status: pending + workflow_run_id. Alternatively, provide generation_metadata_id (an existing icp_id) with no seed fields to attach that already-completed ICP run directly — no workflow is launched, status: active immediately. Default create_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. Returns status: pending + workflow_run_id. Alternatively, provide generation_metadata_id (an existing model_id) with no positive_class_segment_id to attach that already-completed model run directly — no workflow is launched, status: active immediately. Default create_audience: false.

Poll GET /v1/segments/{id} for status, or configure a webhook to receive segment.ready / segment.failed events. Requires 'creator' 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. record_limit on a non-filter subtype returns 400 RECORD_LIMIT_UNSUPPORTED. When create_audience is true, an unknown campaign_id returns 400 INVALID_CAMPAIGN_ID and nothing is created.

post/v1/segments

Request

  • Base URL: https://api.infiniteaudience.ai
  • URL: https://api.infiniteaudience.ai/v1/segments
  • Auth: HTTP bearer

Request body

namestring required

Display name for the segment.

subtype'filter' | 'matched' | 'similarity' | 'propensity'

Segment subtype. Determines which additional attributes are required.

create_audienceboolean

When true, automatically creates a thin audience wrapper referencing this segment. Defaults: filter=true, matched=true, similarity=false, propensity=false.

record_limitinteger

filter subtype only. Caps the segment at this many people. Requires a State, City, or ZIP Code filter that narrows every OR branch to at most 100 ZIP3 regions; otherwise returns 400 CAP_GEOGRAPHY_REQUIRED. Members are a stable, segment-seeded pseudo-random selection of the people matching the filters (the same people on every count, audience composition, quote, and delivery for a given data release). Audiences and deliveries built from the segment inherit the cap — there is no separate audience- or delivery-level cap. A delivery may export fewer rows than the cap after privacy suppression. When count_snapshot is supplied it is clamped to the cap.

file_format'csv' | 'avro' | 'json' | 'jsonl'

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.

compression'none' | 'gzip'

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.

match_levelstring[]

matched subtype only. Restricts identity resolution to the selected match levels. Defaults to all five levels.

spatial_mode'residential' | 'work' | 'auto'

matched subtype only. Phase 3 spatial trade-area profile; residential is the default, work selects workplace-oriented matching, and auto dynamically selects commuter expansion based on whether the input address is commercial.

shard_countinteger

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.

session_idstring

Optional chat session identifier used to reconnect progress for an asynchronously generated similarity or propensity segment.

seed_descriptionstring

similarity subtype only. Natural language description of the target ICP persona. Provide either seed_description or seed_segment_id, not both.

seed_segment_idstring

similarity subtype only. ID of an existing segment to use as the lookalike seed. Provide either seed_description or seed_segment_id, not both.

positive_class_segment_idstring

propensity subtype only. ID of an existing segment whose members represent the positive training class for ML model training.

model_type'BOOSTED_TREE_CLASSIFIER' | 'AUTOML_CLASSIFIER' | 'LOGISTIC_REG'

propensity subtype only. BQML classifier type.

excluded_columnsstring

propensity subtype only. Comma-prefixed feature columns excluded to prevent target leakage.

model_namestring

propensity subtype only. Human-readable model name.

generation_metadata_idstring

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.

visibility'org' | 'private'

org (default) — visible to all org members. private — visible only to creator.

hitlboolean

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.

campaign_idstring

Campaign this segment is built for. Recorded as the segment's origin_campaign_id and, with create_audience, links the wrapper audience to it. Optional — when omitted, a delegated chat/A2A session's campaign is used, otherwise the segment has no campaign. An unknown id is a 400 INVALID_CAMPAIGN_ID and nothing is created.

webhook_urlstring uri

Optional HTTPS URL to receive segment.ready or segment.failed events. Overrides the org-level webhook URL for this request only.

ephemeralboolean

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).

Response

Segment created.

segment_idstring required
namestring required
subtype'filter' | 'matched' | 'similarity' | 'propensity' required
status'pending' | 'active' | 'failed' | 'archived' | 'expired' required
record_countinteger nullable required
expires_atstring required

Date-only ISO string (90-day expiry) for a persistent segment; a full ISO datetime (short, hour-granular TTL) while ephemeral is true.

ephemeralboolean

True for a scratch/auto-expiring filter-subtype segment. Absent/false reads as persistent.

created_atstring date-time required
updated_atstring date-time required
upload_urlstring nullable

matched subtype only. 30-minute signed upload URL. Present when shard_count was 1 (the default) — absent when sharded, use upload_urls instead.

upload_urlsstring[] nullable

matched subtype only. N signed upload URLs (index-ordered). Present only when shard_count > 1 was requested — upload_url is absent. Every CSV shard must include the same header row.

compression'none' | 'gzip' | 'null' nullable

matched subtype only. Input artifact compression.

upload_expires_atstring date-time nullable

matched subtype only. Expiry of upload_url/upload_urls.

workflow_run_idstring nullable

similarity/propensity subtypes. Workflow run ID for progress monitoring.

audience_idstring nullable

If create_audience was true, the ID of the auto-created audience wrapper. Null otherwise.

Changes

No recorded changes to this operation across all 1 revision of this API.