Analyze matched segment column mapping

Streams a bounded schema sample from csv/json/jsonl/Avro input (raw or gzip), analyzes the column structure using AI inference, and returns a mapping of your source columns to standard identity attributes. Takes a segment_id (returned by POST /v1/match/file) — no audience wrapper required. Call this after uploading your file to preview how columns will be interpreted before the match runs.

Response attributes to watch:

• columns[].confidence: values below 0.6 indicate uncertain mappings that are worth verifying before the match runs.

• columns[].warning: an attribute-level concern flagged by the analyzer (e.g. ambiguous column name or missing country codes on phone numbers).

• unmapped_columns: columns that could not be mapped and will be excluded from identity resolution. If a critical identity attribute (email, phone, last_name) appears here, the match will have reduced accuracy or may fail entirely.

• recommendations: suggestions for improving match quality.

If mappings are incorrect: rename the affected columns in your file to match standard identity attribute names (email, phone, email_sha256, phone_sha256, first_name, middle_name, last_name, name_suffix, address_1, address_2, city, state, zip, dob, iag_person_id) and re-upload. The match workflow will re-analyze automatically.

Analysis gate: unless the segment was created/refreshed with hitl: true, the platform always runs its own column analysis automatically as part of the match workflow, and by the time this endpoint can return real data the upload has already triggered that automatic resolution — calling it does not pause or gate anything in that case, it's a read-only preview only. If no usable identity attributes can be resolved, the segment transitions to failed and error_message describes which columns could not be mapped.

With hitl: true: the segment's upload is staged rather than resolving automatically, so this endpoint reads the staged file and genuinely nothing has started yet — review the response, then call POST /v1/segments/{id}/mappings to confirm (starts resolution) or POST /v1/segments/{id}/mappings/cancel to abort. Requires 'discovery' scope.