Confirm column mapping overrides for a matched audience

POST

/v1/audiences/{id}/mappings

curl --request POST \
  --url https://dev-api.infiniteaudience.ai/v1/audiences/example/mappings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "column_mappings": { "additionalProperty": "example" } }'

• Development API Server

Stores confirmed column mapping overrides for this audience’s matched member 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.

If the underlying segment was refreshed with hitl: true, the upload is still staged — 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/audiences/{id}/mappings/cancel instead to abort a staged upload without confirming. Requires ‘purchase’ scope.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string

Audience document ID.

Request Body^required

Media typeapplication/json

object

column_mappings

required

Map of source column name → standard identity attribute name. Use "(skip)" as the value to explicitly exclude a column.

object

key

additional properties

string

Example^generated

{
  "column_mappings": {
    "additionalProperty": "example"
  }
}

Responses

200

Mappings saved.

Media typeapplication/json

object

ok

required

boolean

column_mappings

required

object

key

additional properties

string

Example^generated

{
  "ok": true,
  "column_mappings": {
    "additionalProperty": "example"
  }
}

400

Invalid request — malformed body, missing required attribute, or failed validation. See error and message for details.

Media typeapplication/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

Examplevalidation_error

{
  "error": "Bad Request",
  "code": "MISSING_SEGMENTS",
  "message": "segment_ids is required for filter audiences."
}

401

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

Media typeapplication/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

{
  "error": "Unauthorized: Missing or invalid Authorization header"
}

{
  "error": "Unauthorized",
  "code": "TOKEN_EXPIRED",
  "message": "Your session has expired. Please sign in again."
}

403

Token is valid but lacks the required scope for this endpoint. Check the endpoint description for the required scope (discovery, purchase, or account).

Media typeapplication/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

Examplemissing_scope

{
  "error": "SCOPE_REQUIRED",
  "message": "This endpoint requires the purchase scope."
}

404

Resource not found or not accessible to the calling org.

Media typeapplication/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

Examplenot_found

{
  "error": "Audience not found"
}

500

STAGING_COPY_FAILED — moving a staged (hitl: true) upload into place failed; the segment is unchanged, retry the call.

Media typeapplication/json

object

error

required

string

code

required

string

Allowed values: STAGING_COPY_FAILED

message

required

string

Example

{
  "code": "STAGING_COPY_FAILED"
}