Get a file match job

GET

/v1/match/file/{matchId}

const url = 'https://api.infiniteaudience.ai/v1/match/file/example';
const options = {method: 'GET', 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 GET \
  --url https://api.infiniteaudience.ai/v1/match/file/example \
  --header 'Authorization: Bearer <token>'

Get a single file match job by segment ID. Returns 404 if the segment does not exist or is not a matched-subtype segment. Requires ‘discovery’ scope.

Authorizations

bearerAuth

Parameters

Path Parameters

matchId

required

string

Header Parameters

X-Integration-Run-Id

string

/^ir_[A-Za-z0-9_-]{40}$/

Required for an OAuth partnership to access a private file job; the run must belong to the same active OAuth grant.

Responses

200

File match job details

application/json

A file-based match job (matched-subtype segment)

object

data_release

required

One of:

object
null

Delivered IAG refresh version. Independent of license status. Null provenance means unknown; a newer refresh-major can prompt a refresh through existing workflows. Active licenses and existing identity IDs support free refresh; normal charges may apply otherwise.

object

major

required

integer

>= 1

minor

required

integer

match_id

required

string

name

required

string

status

required

string

Allowed values: pending active failed archived expired

matching_status

required

string | null

Allowed values: pending processing completed failed

input_record_count

required

integer | null

match_count

required

integer | null

match_rate

required

number | null format: float

amount_charged

required

One-time file-match USD estimate accepted when this run first participates in a successful delivery. Null before first delivery; excludes the delivery’s separate audience/destination/field usage and is not a finalized invoice amount.

number | null

file_format

required

string | null

Allowed values: csv avro json jsonl

compression

required

Input artifact compression, normalized to none for legacy jobs.

string

Allowed values: none gzip

column_mappings

object | null

mapping_warnings

Warnings about how the uploaded file’s columns are used. analysis entries are the automatic column analysis’s warnings on low-confidence mappings (below 0.6) that feed matching, and appear only when that analysis produced column_mappings. A nested_addresses entry is recomputed on every matching run, whoever supplied the mappings, when the addresses column has unrecognized keys or is not an array of address objects (it is then ignored). null before the first run’s analysis step. Returned by the single-job lookup only.

Array<object> | null

object

source_column

required

The uploaded file’s column the warning is about.

string

code

required

analysis is the automatic column analysis’s warning on a low-confidence mapping; nested_addresses is the platform’s check of the addresses column.

string

Allowed values: analysis nested_addresses

warning

required

string

error_message

string | null

segment_id

required

string

audience_id

required

string | null

audience_status

required

Whether the linked audience (if any) is still active in Library. archived covers both an explicitly archived audience and a deleted one. null when there’s no audience_id, or its audience document no longer exists. This job’s own history is unaffected either way — it persists even after the underlying segment or audience is deleted from Library.

string | null

Allowed values: active archived

source_job_id

required

string | null

integration_run_id

Present only for an authorized private partnership workflow.

string

/^ir_[A-Za-z0-9_-]{40}$/

created_at

required

string | null format: date-time

expires_at

required

string | null

Example

{
  "status": "pending",
  "matching_status": "pending",
  "file_format": "csv",
  "compression": "none",
  "mapping_warnings": [
    {
      "code": "analysis"
    }
  ],
  "audience_status": "active"
}

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

next_step

Public action for correcting the request or retrying later.

string

issues

Array<object>

object

path

required

JSON path to the invalid filter field or value.

string

code

required

string

Allowed values: INVALID_FILTER_SHAPE UNKNOWN_FILTER_FIELD FIELD_NOT_FILTERABLE UNSUPPORTED_FILTER_OPERATOR UNSUPPORTED_TEXT_COMPARISON INVALID_FILTER_VALUE INVALID_ENUM_VALUE AMBIGUOUS_ENUM_VALUE

message

required

string

suggestions

Array<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

next_step

Public action for correcting the request or retrying later.

string

issues

Array<object>

object

path

required

JSON path to the invalid filter field or value.

string

code

required

string

Allowed values: INVALID_FILTER_SHAPE UNKNOWN_FILTER_FIELD FIELD_NOT_FILTERABLE UNSUPPORTED_FILTER_OPERATOR UNSUPPORTED_TEXT_COMPARISON INVALID_FILTER_VALUE INVALID_ENUM_VALUE AMBIGUOUS_ENUM_VALUE

message

required

string

suggestions

Array<string>

key

additional properties

any

Examples

missing_scope

{
  "error": "SCOPE_REQUIRED",
  "message": "This endpoint requires the creator 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

next_step

Public action for correcting the request or retrying later.

string

issues

Array<object>

object

path

required

JSON path to the invalid filter field or value.

string

code

required

string

Allowed values: INVALID_FILTER_SHAPE UNKNOWN_FILTER_FIELD FIELD_NOT_FILTERABLE UNSUPPORTED_FILTER_OPERATOR UNSUPPORTED_TEXT_COMPARISON INVALID_FILTER_VALUE INVALID_ENUM_VALUE AMBIGUOUS_ENUM_VALUE

message

required

string

suggestions

Array<string>

key

additional properties

any

Examples

not_found

{
  "error": "Audience not found"
}