Match Records
match_recordsPerform real-time identity resolution on up to 100 records. Returns run_id, match_count, record_count, match_rate, and records[] — one output record per input record, matched or not (each with row_id, iag_person_id, match_level, match_type, match_confidence, enrichment fields, and the licensing labels below). iag_person_id is an org-scoped, non-reversible id: present on a real match, or a best-effort id derived from the row's own identity signals (or null) when unmatched — use match_count/record_count, not id-presence, to tell real matches from derived-only rows. Each record also carries resolution_action (resolved = organic PII match, refreshed = the row submitted a valid iag_person_id, unmatched = no real match, identity_unavailable = a previously valid id no longer resolves to deliverable data) and license_action (none, started, or renewed), plus license_expires_at (ISO-8601 or null) — these two fields are independent: a row can be resolution_action "resolved" and license_action "renewed" at once. The run_id can be passed immediately to get_match_run to retrieve or audit this call later. Matching consumes subscription capacity for real matches. Returned monetary consumption values are estimates in USD; final rated consumption may differ. A tier-01 Person ID from a prior real match or licensed audience delivery can go directly to Refresh; an audience-only ID has null match_level until a real match occurs. Include I in match_level for direct ID lookup, or omit the filter. Active identity licenses provide existing coverage for the identity component. For more than 100 records, use create_segment(subtype="matched") with a file upload instead. A subscription-capacity refusal may notify configured external webhooks. Requires 'creator' scope.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"records": "<records>"
},
"name": "match_records"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| records | Yes | Array of 1–100 records to match. Each record is a key-value object of identity fields: email, phone, full_name (or first_name/middle_name/last_name/name_suffix), address_1/address_2/city/state/zip, dob, iag_person_id. If full_name is provided without first_name/last_name, the engine parses it into components automatically. Pre-hashed clients may submit email_sha256/phone_sha256 (lowercase-hex SHA-256) instead of raw email/phone — do not submit an already-hashed value in the raw field, it will be hashed a second time and never match. Extra permutations beyond the primary identity fields may be supplied as emails[]/phones[]/addresses[]/emails_sha256[]/phones_sha256[] arrays. Each addresses[] entry is read by exact key: address_1, address_2, city, state, zip (zip5/postal_code/zip_code accepted as ZIP aliases); any other key is ignored. | |
| field_list | No | Optional list of output fields to include in matched records | |
| match_level | No | Restrict identity resolution to these match levels (Individual/Household/Digital/Spatial/Address). Omit to use the platform default (all levels). | |
| template_id | No | Optional enrichment template ID to apply | |
| spatial_mode | No | Spatial trade-area mode. residential is the default; use work for workplace-oriented spatial matching, or auto for dynamic commercial workplace routing. | residential |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| records | Yes | ||
| guidance | No | Interpretation or recovery guidance for this result | |
| count_unit | No | ||
| match_rate | Yes | ||
| page_count | No | Number of objects on this page, not the organization total | |
| count_state | No | Unknown means no count; available does not guarantee freshness. Recount for a current value. | |
| match_count | Yes | ||
| next_actions | No | Suggested next calls using returned IDs and available scopes. Not executed and not user consent. | |
| record_count | Yes | ||
| amount_charged | Yes | Estimated subscription capacity consumed, denominated in USD; final rated consumption may differ | |
| population_input | No | Population input used for the preview; IDs refer to their current saved definitions |