Creates a matched segment by uploading a customer list for identity resolution. Equivalent to POST /v1/segments with subtype: matched.

Upload csv, newline-delimited json/jsonl, or Avro records to the Infinite Audience identity graph and receive an enriched file back. Each format may be raw or gzip. Useful for CRM onboarding, suppression list resolution, contact data hygiene, and data co-op workflows.

File structure: there is no fixed column schema — column names are inferred via AI (POST /v1/match/{segment_id}/analyze reports the mapping, a confidence score per column, and any warnings). For the best match quality, name your columns (or use names that closely resemble) the standard identity attributes: email, phone, full_name (or separately, first_name, middle_name, last_name, name_suffix), address_1, address_2, city, state, zip, dob, iag_person_id (a re-upload of an id previously returned by this platform — format CLIENTCODE_TIER_HASH — resolved server-side before matching). Only map a column to full_name when the file has a single combined-name column — if separate first/last name columns exist, map those instead. A valid tier 01 ID previously issued to this organization by a real match or a licensed audience delivery can go directly to refresh. A prior real match qualifies when its level is included in this file's match_level filter (all five levels by default); a settled record license also qualifies. Include I for direct ID lookup because the engine classifies that path as I. Delivered direct-Refresh rows report the latest real level within that filter, or null if none exists, rather than the engine's fixed ID-lookup label I. Derived tier 02–05 IDs cannot authorize direct Refresh; derived IDs are continuity labels for unmatched rows, not resolved identities; submit the row's identity signals again if you want to attempt resolution. A column that can't be confidently mapped is excluded from identity resolution — if a critical attribute (email, phone, last_name) ends up unmapped, match accuracy drops or the segment may fail to resolve at all.

Pre-hashed identity columns: for clients whose own systems never expose raw email/phone values, map a column to email_sha256 or phone_sha256 (lowercase-hex SHA-256 digests) instead of the raw email/phone target — the platform passes these through without re-hashing. Do not map an already-hashed column to the raw email/phone target (it would be hashed a second time and never match), and do not map a raw email/phone column to email_sha256/phone_sha256 just because of its name — the mapper trusts sample-value shape over column name. avro/json/ jsonl uploads (which support array columns) may also supply emails, phones, addresses, emails_sha256, and phones_sha256 as extra match permutations beyond the primary identity fields. Column mapping covers only top-level columns: the keys inside each addresses entry are read by exact name and are never AI-mapped. Use address_1, address_2, city, state, and zip (zip5, postal_code, and zip_code are accepted as ZIP aliases). Any other key, such as street or postal, is ignored. This is the same shape as the MatchAddress schema used by POST /v1/match. If your upload includes row_id, every value must be unique across all shards. When it is absent, the platform assigns stable row_0, row_1, ... values. Duplicate ids or collisions with generated values fail the match before its result can be delivered.

Billing: Upload, analysis, and matching completion emit no billable usage. The first successful POST /v1/audiences/{id}/deliveries or POST /v1/match/{id}/deliveries involving the current run emits its one aggregate platform_match usage set together with audience, destination, and enrichment usage. Retries, duplicates, and later deliveries do not emit that file-match usage again. File workflows for one organization may run concurrently. At delivery, license coverage is checked per distinct identity against confirmed canonical history. A simultaneous purchase of the same identity can be charged by both workflows before either confirmation is visible.

Workflow (hitl unset/false — default, upload resolves automatically):

1. POST /v1/match/file — receive a segment_id and a 30-minute presigned upload_url. Pass file_format to specify your file type (default csv). When create_audience: true (default), also receives an audience_id.

2. Upload your file — PUT to upload_url with the underlying format's Content-Type. For gzip, send raw gzip bytes and do not set Content-Encoding. No Authorization header is needed.

3. (Optional) POST /v1/match/{segment_id}/analyze — preview column mapping. Note that by the time this can return real data, the upload has already triggered automatic resolution — this step does not pause anything.

4. Automatic column analysis — the platform always runs column analysis as part of the match workflow. If no usable identity attributes can be resolved, the segment transitions to failed and error_message describes the issue.

   Standard column names for best results: email, phone, full_name, first_name, middle_name, last_name, name_suffix, address_1, address_2, city, state, zip, dob, iag_person_id. Pre-hashed email_sha256/phone_sha256 are also supported — see below.

5. Poll GET /v1/match/file/{match_id} until matching_status: completed (or use a segment.ready webhook).

6. POST /v1/match/{match_id}/deliveries — export the already resolved result. Poll GET /v1/match/{match_id}/deliveries for status; it takes the match id directly and needs no audience id — if you only want matching/enrichment and don't need audience-building concepts, this and step 1's segment_id/match_id are the only ids you need to track end to end. (The audience-scoped POST /v1/audiences/{audience_id}/deliveries also works and is what this endpoint forwards to internally, but requires the audience id from step 1.)

Workflow (hitl: true — requires an explicit confirm before resolution runs):

1. POST /v1/match/file {"hitl": true} — receive a segment_id and upload_url.

2. Upload your file — lands at a staging location, NOT the path that triggers automatic resolution.

3. POST /v1/match/{segment_id}/analyze — reads the staged file; safe to call any time after upload, since nothing has started yet.

4. POST /v1/segments/{segment_id}/mappings to confirm (moves the file into place and starts resolution) or POST /v1/segments/{segment_id}/mappings/cancel to abort (nothing ever ran).

5. Poll GET /v1/match/file/{match_id} until matching_status: completed, then POST /v1/match/{match_id}/deliveries — same match-namespaced export and polling as the default flow above (see step 6 there).

Sharded uploads: set shard_count > 1 for same-format files. The response returns index-ordered upload_urls; upload every declared shard. Every CSV shard must include the same header row, and all shards must share schema and compression. Analysis samples shard 0; a later mismatch fails the job explicitly.

Retries: pass an Idempotency-Key header to make a retried create call safe to repeat: the same key with an identical body returns the original segment/audience (and freshly re-signed upload URL(s), if the originals already expired) instead of creating a duplicate. Unlike POST /v1/match, this endpoint isn't billed at creation, so a duplicate without this header is an orphan Library entry, not a double charge — recommended for any client that may retry.

When create_audience is true, an unknown campaign_id returns 400 INVALID_CAMPAIGN_ID and nothing is created. Requires 'creator' scope.