Get a file match job

GET

/v1/match/file/{matchId}

const url = 'https://dev-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://dev-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

Responses

200

File match job details

application/json

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

object

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

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

created_at

required

string | null format: date-time

expires_at

required

string | null

Example

{
  "status": "pending",
  "matching_status": "pending",
  "file_format": "csv",
  "compression": "none",
  "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

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"
}