Confirm column mapping overrides for a matched segment
const url = 'https://dev-api.infiniteaudience.ai/v1/segments/example/mappings';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"column_mappings":{"additionalProperty":"example"}}'};
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/example/mappings \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "column_mappings": { "additionalProperty": "example" } }'Stores confirmed column mapping overrides for a matched-subtype segment. Call this after reviewing the POST /v1/match/{id}/analyze response to correct any incorrect predictions. Sets mapping_confirmed: true so the platform skips its own analysis and uses these mappings directly.
column_mappings may be omitted entirely — the platform then re-runs column analysis on the currently active upload itself and accepts its own suggested mapping as-is (the same behavior as reviewing POST /v1/match/{id}/analyze and confirming without edits, in one call). This can return 409 FILE_NOT_YET_UPLOADED if the file hasn’t finished uploading yet, or 422/400 on other analysis failures — pass column_mappings explicitly to skip re-analysis entirely.
If the segment was created or refreshed with hitl: true, the upload is still staged (not yet at the path that triggers automatic resolution) — this call also moves the staged file into place and starts identity resolution, which is why it can return 500 STAGING_COPY_FAILED if that move fails (the segment is left unchanged in that case; retry the call). Use POST /v1/segments/{id}/mappings/cancel instead to abort a staged upload without confirming.
Requires ‘purchase’ scope.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Segment document ID.
Request Body
Section titled “Request Body”object
Map of source column name → standard identity attribute name. Use "(skip)" as the value to explicitly exclude a column. Omit entirely (send {} or no body) to accept the platform’s own fresh column analysis of the active upload as-is.
object
Examplegenerated
{ "column_mappings": { "additionalProperty": "example" }}Responses
Section titled “Responses”Mappings saved.
object
object
Examplegenerated
{ "ok": true, "column_mappings": { "additionalProperty": "example" }}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."}Resource not found or not accessible to the calling org.
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": "Audience not found"}Resource state conflicts with the request. For upload analysis this includes FILE_NOT_YET_UPLOADED.
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.
Examplegenerated
{ "error": "example", "message": "example", "code": "example", "request_id": "example"}Request is structurally valid but the resource is in a state that prevents the operation (e.g. expired, pending, or not yet uploaded). See error and code for the specific reason.
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": "Audience expired", "code": "AUDIENCE_EXPIRED", "message": "This audience version expired. Run a refresh to create a new deliverable version."}{ "error": "Audience not ready", "code": "AUDIENCE_PENDING", "message": "This audience is still being processed. Poll GET /v1/audiences/{id} until status is active."}STAGING_COPY_FAILED — moving a staged (hitl: true) upload into place failed; the segment is unchanged, retry the call. ANALYSIS_FAILED — column_mappings was omitted and re-analysis failed unexpectedly.
object
Example
{ "code": "STAGING_COPY_FAILED"}