Enrich a file with the API

File enrichment is the clean path for larger customer lists. Create the job, upload the file, let Infinite Audience do the matching, then export the result.

The workflow

Create a file job with POST /v1/match/file.
Upload the file to the returned signed URL.
Check GET /v1/match/file/{match_id} until matching is complete.
Create an export with POST /v1/match/{match_id}/deliveries.
Check GET /v1/match/{match_id}/deliveries, then download the completed result.

1. Create the job

curl -X POST https://api.infiniteaudience.ai/v1/match/file \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: q1-customer-file" \
  -d '{"name":"Q1 customer list","file_format":"csv"}'

Keep the returned match_id; it is the handle used throughout this workflow. The response also includes an upload_url, its expiration, and file settings.

2. Upload the file

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: text/csv" \
  --data-binary @customers.csv

The upload URL is already authorized, so do not add your bearer token. Upload URLs last 30 minutes. Use the content type that matches the declared format: text/csv, application/json, application/x-ndjson, or application/avro.

For large exports, request 2–50 shards and upload every returned URL. Repeat the same header row in each CSV shard.

3. Wait for matching

curl https://api.infiniteaudience.ai/v1/match/file/$MATCH_ID \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Continue when matching_status is completed; stop and inspect error_message if it is failed. A segment.ready or segment.failed webhook can replace polling.

4. Create the export

curl -X POST https://api.infiniteaudience.ai/v1/match/$MATCH_ID/deliveries \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"include_unmatched":true}'

Add field_list or template_id when you want a specific enrichment set. The account’s pricing and active record licenses determine the final charge; use the quote endpoint before starting when you need a preview.

5. Download the result

curl https://api.infiniteaudience.ai/v1/match/$MATCH_ID/deliveries \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Find your delivery_id and wait for status: completed. Download URLs last 24 hours; call the same endpoint again whenever you need a fresh signed URL.

Understand the returned IDs

Resolved rows receive a tier 01 iag_person_id that is salted for your organization. Save it for supported refresh, segment, and audience workflows. An unmatched row may receive a derived tier 02–05 ID so it stays recognizable in your file; that value is not a real match or a refresh key. Use the match fields and totals—not ID presence alone—to separate resolved records from derived-only rows.

Learn how person IDs and derived IDs work →

Review unusual columns first

Set hitl: true when your file uses internal or ambiguous column names. Upload the file, call POST /v1/match/{match_id}/analyze, review the suggested mapping, then confirm the complete map with POST /v1/segments/{match_id}/mappings. Matching begins after confirmation.