Enrich records in real time

Use POST /v1/match when the answer belongs in the moment: a lead enters a form, a contact reaches a workflow, or an application needs a richer profile now.

1. Add 1–100 records with the identity signals you already have.
2. Choose the enrichment fields you want returned.
3. Send the request and join each result back to your source with row_id.
4. Save returned tier-01 iag_person_id values for future supported refreshes.

curl -X POST https://api.infiniteaudience.ai/v1/match \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lead-enrichment-2026-08-31-001" \
  -d '{
    "records": [
      {"row_id":"lead-42","email":"[email protected]","first_name":"Jane","last_name":"Doe"}
    ],
    "field_list": ["estimated_household_income","birth_generation"]
  }'

Each record may include email, phone, hashed contact details, name, postal address, date of birth, or an iag_person_id. Use GET /v1/catalog/fields to see available enrichment fields and POST /v1/quote to preview the request.

Choose a spatial matching mode

Set spatial_mode to residential (the default), work, or auto when Phase 3 address-proximity matching matters. residential uses the normal trade area; work always uses the wider commuter trade area. auto uses the commuter trade area when the geocoded input address is classified as commercial and the residential trade area otherwise. Coordinate-only inputs and ZIP5 centroid fallbacks do not trigger commercial expansion under auto. Earlier match phases and direct Person ID refresh do not use this setting.

For a mixed home and workplace list, add "spatial_mode":"auto" beside records in the request body. Keep the same value on an idempotent retry.

Read the result

The response includes match totals, the amount charged, and a records array. Results may not follow input order, so join them by row_id.

const byRowId = new Map(response.records.map((record) => [record.row_id, record]));
const lead = byRowId.get('lead-42');

Tier 01 person IDs represent real graph identities and can be supplied on later requests, including IDs from licensed audience exports of any subtype. A direct refresh of an audience-only identity reports match_level: null until a real match establishes provenance. Other tiers keep unmatched inputs identifiable but do not represent a reusable graph identity. Check resolution_action as well as match metadata when deciding how a result should be used.

Learn how identity resolution works: inputs, matching levels, and the spatial engine →

Learn how organization-safe person IDs and derived IDs work →

Retries without reruns

Send a stable Idempotency-Key with every matching request. If a network retry repeats the same request, Infinite Audience can return the original result instead of doing the work twice.

For larger datasets, use file enrichment.