Create Segment
create_segmentCreate a segment of the specified subtype. Segments are the typed cohort definitions — audiences are composition wrappers built from segments. filter: reusable filter definition — returns immediately with status active and an unset count unless count_snapshot is supplied. Call count_segment to calculate its saved count. similarity: provide seed_description (natural language) OR seed_segment_id — triggers async icp-segment workflow, returns status pending + workflow_run_id. Call wait_for_segment(segment_id) to block until active. propensity: provide positive_class_segment_id — triggers async ml-model workflow, returns status pending + workflow_run_id. Training can take 10–60 min. Call wait_for_segment(segment_id) to monitor. matched: upload a file — returns upload_url (30-min presigned), or upload_urls (an array, one per shard) when shard_count > 1. The upload is staged (not resolved automatically): PUT the raw file bytes to each returned URL with Content-Type matching file_format: csv=text/csv, avro=application/avro, json=application/json, jsonl=application/x-ndjson. Do not include the MCP bearer token in this upload. After uploading (all shards, if multiple), call analyze_audience_upload(segment_id) (analyzes the first shard only when sharded — all shards must share one schema), present the mappings to the user and wait for their response, then confirm_column_mappings(segment_id) to start resolution (or cancel_matched_upload(segment_id) if they decline) — only THEN call wait_for_segment(segment_id). Upload, analysis, and completed matched resolution emit no usage; the first successful delivery emits one aggregate platform_match usage set together with normal delivery usage. HITL: similarity and propensity default to hitl=false (auto-proceed through all gates). Set hitl=true to pause at review gates. Use file_format to specify csv (default), avro, json, or jsonl and compression=gzip for gzip bytes. Set shard_count > 1 for multiple same-format files; all shards must use the same compression and every CSV shard must include its own header row. Set create_audience=true to automatically wrap the new segment in an audience for immediate delivery. Optional campaign_id records the campaign the segment is built for and links that wrapper audience to it; omit it to leave both outside any campaign. Requires 'creator' scope.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| hitl | No | (similarity/propensity) Enable human-in-the-loop gates. Default false = auto-proceed through all gates. Set true for interactive review. | |
| name | Yes | Human-readable segment name | |
| filters | No | (filter) AND-combined conditions, reusable directly from discovery_count. Supply filters OR filter_groups, not both. | |
| subtype | Yes | Segment subtype | |
| campaign_id | No | Optional campaign this segment is built for (see list_campaigns). Stored as origin_campaign_id; with create_audience, the wrapper audience is linked to it. An unknown ID is rejected with INVALID_CAMPAIGN_ID and nothing is created. | |
| compression | No | (matched) Input transport compression. Use gzip for .csv.gz/.json.gz/.jsonl.gz bytes; object names remain based on file_format. gzip is NOT supported with file_format=avro (avro is already internally compressed) — the API rejects that combination with UNSUPPORTED_INPUT_COMPRESSION. | none |
| file_format | No | (matched) Input file format. csv (default): every column is a single scalar value — multi-value/array fields are not supported. avro/json/jsonl: native array columns supported. | |
| match_level | No | (matched) Restrict identity resolution to these match levels (Individual/Household/Digital/Spatial/Address). Omit to use the platform default (all levels). | |
| shard_count | No | (matched) Set > 1 for multiple same-format shards. All shards must use the same compression; every CSV shard must contain its own header row. | |
| webhook_url | No | (similarity/propensity/matched) URL to receive a POST notification when the segment becomes active | |
| record_limit | No | (filter) Cap the segment at this many people (e.g. "up to 1,000"). Requires State, City, or ZIP Code filters narrowing every OR branch to at most 100 three-digit ZIP prefixes. Audiences and deliveries inherit the cap. | |
| spatial_mode | No | (matched) Spatial trade-area mode. residential is the default; use work for workplace-oriented spatial matching, or auto for dynamic commercial workplace routing. | residential |
| filter_groups | No | (filter) Grouped conditions, reusable directly from discovery_count. Supply filters OR filter_groups, not both. | |
| count_snapshot | No | (filter) Existing verified count snapshot to store on the new segment; omit to leave the count unknown, then call count_segment for a fresh count | |
| create_audience | No | When true, automatically creates an audience wrapper around the new segment for immediate delivery use. Returns both segment_id and audience_id. | |
| seed_segment_id | No | (similarity) Existing segment ID to use as seed — provide either seed_description or seed_segment_id, not both | |
| seed_description | No | (similarity) Natural language ICP narrative describing the target segment persona | |
| positive_class_segment_id | No | (propensity) Segment ID whose members represent the positive class for ML training |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| status | Yes | ||
| subtype | Yes | ||
| guidance | No | Interpretation or recovery guidance for this result | |
| count_unit | No | ||
| page_count | No | Number of objects on this page, not the organization total | |
| segment_id | Yes | ||
| upload_url | No | ||
| audience_id | No | ||
| count_state | No | Unknown means no count; available does not guarantee freshness. Recount for a current value. | |
| upload_urls | No | ||
| next_actions | No | Suggested next calls using returned IDs and available scopes. Not executed and not user consent. | |
| record_count | No | Stored count; null means unknown. Call count_segment for a current count. | |
| record_limit | No | Maximum members; null means no explicit cap | |
| filter_groups | No | Complete saved filter definition; one AND group also represents a simple flat filter list | |
| money_display | No | Currency amounts formatted once from source paths ending in _cents. Use verbatim; do not divide again. Null/missing source amounts are omitted, not zero. | |
| current_version | No | ||
| workflow_run_id | No | ||
| population_input | No | Population input used for the preview; IDs refer to their current saved definitions | |
| upload_expires_at | No |