Deliver a file match job

POST

/v1/match/{id}/deliveries

curl --request POST \
  --url https://dev-api.infiniteaudience.ai/v1/match/example/deliveries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "template_id": "standard_iag" }'

• Development API Server

Convenience wrapper around POST /v1/audiences/{id}/deliveries for file-based match jobs. Always delivers to the download destination — the enriched file is exported to a time-limited signed URL. Omits DSP-only destinations (LiveRamp, Narrative) and their associated parameters.

Workflow (after POST /v1/match/file):

1. Upload your file to the upload_url returned by POST /v1/match/file. This upload is what triggers identity resolution to begin — not this endpoint.

2. (Recommended) POST /v1/match/{segment_id}/analyze — preview column mapping. Check unmapped_columns and confidence values. If mappings look wrong, rename columns in your file and re-upload before triggering delivery.

3. Poll GET /v1/match/{match_id} until matching_status is completed (or use a segment.ready webhook). Calling this endpoint before resolution finishes returns 422 AUDIENCE_PENDING.

4. POST /v1/match/{match_id}/deliveries (this endpoint) — export the already- resolved match to a signed download URL. Optionally supply template_id or field_list to choose which enriched attributes to include in the output — if neither is given, the Standard IAG attribute set is used.

5. Poll GET /v1/match/{match_id}/deliveries for status — it takes the match id directly, needs no audience id, and re-signs download_urls on every read. (The audience-scoped GET /v1/audiences/{audience_id}/deliveries/{delivery_id} also works but requires the audience id, which this wrapper is designed to let you avoid.) When status: completed, download_urls (array of signed URLs) is returned.

All billing, dedup, reservation, and usage-outbox logic is handled identically to POST /v1/audiences/{id}/deliveries. Re-running the exact same (match_id × version × template) is always free. Requires ‘purchase’ scope.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string

The match_id returned by POST /v1/match/file.

Request Body^required

Media typeapplication/json

object

include_unmatched

Include rows that did not resolve to a real graph match in the output file — these appear with null enrichment attributes and, in the exported iag_person_id column, a best-effort id deterministically derived from the row’s own identity signals (or null if none qualified) rather than a real platform match. Set to false to receive only matched records. Defaults to true. Every exported row (matched or not) also carries a row_id column matching your original upload, for correlating a delivered row back to its source input row regardless of match status. Matched rows additionally carry match_level (I/H/A/S/D), match_type (e.g. graph_name_email_match, vector_name_address_match, spatial_match), and match_confidence (0–1) — all null (not derived) on unmatched rows.

boolean

default: true

template_id

Enrichment template ID. Only standard_iag is valid (see templates[] in GET /v1/catalog/fields). Mutually exclusive with field_list. If neither is provided, the Standard IAG attribute set (all attributes with product_usage containing audience) is used.

string | null

field_list

Explicit list of attribute names to append — every attribute must be a valid audience attribute. Use GET /v1/catalog/fields to browse available attributes. Mutually exclusive with template_id. If neither is provided, the Standard IAG attribute set is used. Individual-level attributes come back null for a row whose match_level doesn’t qualify for individual-level data — this is expected, not an error. If iag_household_id is requested and available for a row, it is exported in the same org-scoped, non-reversible format as iag_person_id.

Array<string> | null

webhook_url

Optional HTTPS URL to receive delivery.completed or delivery.failed events for this delivery. Overrides the org-level webhook URL for this request only; if omitted, the org-configured URL is used as the fallback. If a signing secret is set in Settings, the dispatch includes X-CF-Signature: sha256=<hmac-hex> regardless of which URL is used. See the Webhooks tag for payload shapes and signing verification guidance.

string format: uri

output_format

Output file format. Omit to auto-detect from the uploaded file’s format (avro → avro, csv → csv, json → json, jsonl → jsonl). Avro exports preserve native column types including REPEATED/array attributes. CSV is the default when format cannot be determined.

string | null

Allowed values: csv avro json jsonl

output_compression

Explicit output artifact compression, independent of the uploaded file. gzip is supported for csv/json/jsonl. Avro uses native DEFLATE and rejects outer gzip.

string

default: none

Allowed values: none gzip

Examples

Deliver using the Standard IAG template

{
  "template_id": "standard_iag"
}

Deliver a custom attribute set, matched records only

{
  "field_list": [
    "age",
    "gender",
    "estimated_household_income"
  ],
  "include_unmatched": false
}

Deliver with webhook notification

{
  "template_id": "standard_iag",
  "webhook_url": "https://hooks.example.com/match-complete"
}

Responses

201

Delivery initiated — or a free re-delivery if this (match_id × version × template) was already completed.

Media typeapplication/json

object

delivery_id

required

string

audience_id

required

string

audience_version

required

integer

destination

required

string

Allowed values: download liveramp narrative

template_id

string | null

field_list

Array<string> | null

status

required

string

Allowed values: processing completed failed

cost

required

Conservative USD estimate for usage accepted for billing; not a finalized invoice total.

number

estimated_cost

Pre-flight safety ceiling for a still-processing delivery. It is released into the final local cost estimate once resolution/export completes; the finalized invoice remains authoritative.

number

already_delivered

true when this exact audience content, resolved field selection, unmatched-row policy, and destination were already delivered — cost is 0 and the existing delivery record is returned.

boolean

message

Human-readable note, present on free re-delivery responses.

string

created_at

required

string

completed_at

string | null

expires_at

required

string

output_format

Output file format. Present on download deliveries. Avro exports preserve native BigQuery column types (including REPEATED/array columns) rather than flattening everything to strings. Read endpoints normalize legacy records; an immediate DSP-create response may omit this field.

string

Allowed values: csv avro json jsonl

output_compression

Explicit outer artifact compression, normalized to none for legacy records on read and possibly omitted by an immediate DSP-create response. It never inherits input compression. Avro uses native DEFLATE and therefore reports none here rather than outer gzip.

string

Allowed values: none gzip

output_bytes

Exact sum of stored object sizes across every output part. Null until completion or when no downloadable artifact is produced.

integer | null

download_urls

Signed GCS download URLs for every completed download artifact part, sorted deterministically. Always an array and may contain multiple BigQuery export shards for any format. Signed URLs expire after 24 hours — call GET /v1/audiences/{id}/deliveries/{did} to regenerate fresh URLs at any time.

Array<string> | null

output_record_count

Actual row count in the exported file. Set at completion for matched audiences only (where the count is unknown until the TVF runs). For filter, similarity, and propensity audiences this equals the audience’s record_count.

integer | null

failure_reason

string | null

matched_segment_id

ID of the matched (file-match) segment resolved from the delivered audience’s composition at delivery creation. Populated only when the audience includes a matched segment; null for filter, similarity, and propensity deliveries and for deliveries created before this attribute existed.

string | null

source_job_id

The matched segment’s originating file-match job ID — links the delivery back to the file-match event that produced its source data. Populated only when the delivered audience resolves a matched segment that carries a source job; null otherwise (including deliveries created before this attribute existed).

string | null

Example

{
  "destination": "download",
  "status": "processing",
  "output_format": "csv",
  "output_compression": "none"
}

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

402

The request cannot proceed on billing grounds. BILLING_INSUFFICIENT_BALANCE applies only to prepay accounts and includes required, available, and shortfall in USD. BILLING_POSTPAY_CEILING_EXCEEDED applies to an account ceiling; BILLING_CONSUMER_POSTPAY_CEILING_EXCEEDED applies to an agency child’s routed ceiling. Both ceiling responses include projected accrued and configured ceiling in USD.

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

code

string

Allowed values: BILLING_INSUFFICIENT_BALANCE BILLING_POSTPAY_CEILING_EXCEEDED BILLING_CONSUMER_POSTPAY_CEILING_EXCEEDED

shortfall

number

required

number

available

number

accrued

number

ceiling

number

Examples

{
  "error": "Insufficient balance",
  "code": "BILLING_INSUFFICIENT_BALANCE",
  "message": "Insufficient effective balance",
  "required": 1,
  "available": 0.75,
  "shortfall": 0.25
}

{
  "error": "Billing capacity unavailable",
  "code": "BILLING_POSTPAY_CEILING_EXCEEDED",
  "message": "Postpay ceiling would be exceeded",
  "accrued": 105,
  "ceiling": 100
}

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

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.

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

503

A required billing provider integration is temporarily unavailable.

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

Example^generated

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