Analyze matched segment column mapping

POST

/v1/match/{id}/analyze

const url = 'https://dev-api.infiniteaudience.ai/v1/match/example/analyze';
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

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/match/example/analyze \
  --header 'Authorization: Bearer <token>'

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.

Authorizations

bearerAuth

Parameters

Path Parameters

required

string

The segment_id of the matched segment (from POST /v1/match/file).

Responses

200

Column mapping analysis.

application/json

object

segment_id

required

string

analysis

required

object

columns

required

Array<object>

object

source_column

required

string

mapped_to

required

string | null

inferred_type

required

string

confidence

required

number

warning

required

string | null

unmapped_columns

required

Array<string>

recommendations

required

Array<string>

Example

{
  "segment_id": "seg_abc123",
  "analysis": {
    "columns": [
      {
        "source_column": "Email Address",
        "mapped_to": "email",
        "inferred_type": "STRING",
        "confidence": 0.98,
        "warning": null
      },
      {
        "source_column": "Mobile",
        "mapped_to": "phone",
        "inferred_type": "STRING",
        "confidence": 0.84,
        "warning": "Phone numbers lack country codes — US assumed"
      }
    ],
    "unmapped_columns": [],
    "recommendations": [
      "Add country codes to phone numbers for higher match rates"
    ]
  }
}

400

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

application/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

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

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

application/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

missing_scope

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

404

Resource not found or not accessible to the calling org.

application/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

not_found

{
  "error": "Audience not found"
}

409

Resource state conflicts with the request. For upload analysis this includes FILE_NOT_YET_UPLOADED.

application/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

Example^generated

{
  "error": "example",
  "message": "example",
  "code": "example",
  "request_id": "example"
}

422

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.

application/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": "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."
}

500

Unexpected server failure.

application/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

Example^generated

{
  "error": "example",
  "message": "example",
  "code": "example",
  "request_id": "example"
}

Analyze matched segment column mapping

Authorizations

Parameters

Path Parameters

Responses

200

Example

400

Examples

401

Examples

403

Examples

404

Examples

409

Examplegenerated

422

Examples

500

Examplegenerated

Example^generated

Example^generated