Consumer Identity Data API - Person, Household, Business

Turn the details you hold about somebody into the documents an identity graph holds about them. One flat row per document, with everything your contract covers attached.

What this actor does

• Resolves six kinds of document, not one kind of record. People, households, places, residencies, businesses and entities are separate classes at this provider, and they answer different questions. The individual, the group living at an address, the address itself, the household at that place, the company, and the resolved identity across sources are each their own request, and each is available here.
• Lets you look somebody up without sending anything about them. Lookup mode takes a key you already hold, a persistent link, a hashed email or a name and address representation hashed at your end, and fetches the document by exact key. No personal detail leaves your side, which is often the difference between a workable integration and one legal will not sign off.
• Validates every record before it can spoil a batch. Requests travel a hundred at a time, and this provider fails the whole batch when one record breaks a rule rather than skipping the bad field. Every documented rule, postcode length, state abbreviation, digit counts on the three phone parts, coordinate ranges, the four pairs of fields that cannot travel together, is checked here first. A record that would have failed is reported as its own row with the reason, and the other ninety-nine still go.
• Batches a hundred at a time and pairs the answers back up. Position is kept from request to response, so every row says which of your records produced it.
• Asks for more than one match when you want the alternatives. A record can resolve to up to ten documents, best first, each with its rank. The run says plainly that each of those is a separate transaction at the provider, because a limit of ten across a hundred records is a thousand transactions.
• Says when a name only partly matched. An email or phone match where part of the name also lined up is reported by the provider as a partial name match, and it ranks above a match on the contact detail alone. That distinction is its own column, and its own filter.
• Handles the two-part authorisation this provider actually uses. A bearer token says who you are; a role and a tenant say which contracted view you get. Both are inputs, both are echoed into the run log, and a refusal explains that the pair is the usual cause rather than the credential.
• Refuses to guess at your bundles. No two accounts are contracted for the same data, so nothing here assumes a bundle exists. The document is written through exactly as sent, and the bundles that actually came back are listed in their own column.
• Charges nothing for a miss. Only rows carrying a document are billed.

Input

Field	What it does
mode	Match from details, or look up by an exact key.
documentClass	People, households, places, residencies, businesses, entities.
records	One object per record, using this provider's own parameter names.
emails / phones	Shortcuts for records that are only an email or only a number.
lookupDocumentClass / lookupType / lookupValues	The key lookup.
clientId / apiKey	Your own OAuth client id and secret.
tokenUrl / scope / baseUrl	Overrides for a tenant on its own hosts.
role / tenant	The contracted pair that decides which view you get.
bundles	Named bundles to return. Empty means everything contracted.
limit	Documents per record, up to ten, best first.
persistedDocumentsOnly	Stored documents only, or allow calculated ones.
matchLevel	The full match cascade, or strict.
strictValidation	Fail a record with an invalid field, or blank the field.
geoCoderLevel	How precisely to geocode.
skipPostal	Skip postal correction before matching.
docIdOnly	Return nothing but the document id.
onlyFullNameMatches	Drop partial name matches.
requireDocId	Drop documents with no id.
skipNotFound	Leave misses out of the dataset.
maxResults	Row ceiling, and therefore the cost ceiling.
requestsPerMinute	Pacing, to match your contracted throttle rate.

Example output

{
  "documentClass": "people",
  "mode": "match",
  "requestIndex": 1,
  "bundlesRequested": ["postalContact", "matchMetadata"],
  "lookupType": null,
  "lookupValue": null,
  "inputSummary": "name=mary robinson zipCode=60515",
  "found": true,
  "rank": 1,
  "docId": "000000US00Yc6Bd5-a08a4FHSWN9JW34aCS88m",
  "nameMatchIntegrity": "full",
  "bundlesReturned": ["matchMetadata", "postalContact"],
  "notFoundReason": null,
  "document": {
    "docId": "000000US00Yc6Bd5-a08a4FHSWN9JW34aCS88m",
    "matchMetadata": { "nameMatchIntegrity": "full" },
    "postalContact": { "city": "Downers Grove", "state": "IL", "zipCode": "60515" }
  }
}

The document column carries whatever your contract covers. The example shows two bundles because that is what the example account asked for; yours will differ.

FAQ

What is the difference between match and lookup?

Match takes ordinary identity details, a name, an address, an email, a phone number, and runs them through a cascade of matching steps until something resolves. Lookup takes a key that already identifies a document, a persistent link, a document id, or a hash of a name and address representation, and fetches that document by exact key with no matching involved. Match answers "who is this"; lookup answers "give me this one again".

How do I look somebody up without sending their personal details?

Build the entity representation at your end, lowercase the name and address into a single string, hash it, and send the hash as the lookup value with the matching hash type. The provider resolves against hashes of the same representations. The same works for an email using MD5 or SHA256. Nothing identifying crosses the network, which is why this route exists.

Why does one bad record matter so much?

Because requests travel in batches of up to a hundred and this provider validates strictly: a nine-character postcode with a letter in it, or a phone number with dashes still in it, produces a validation error for the request rather than a quietly ignored field. This actor applies every rule the provider documents before sending, so a malformed record is reported on its own and the batch it would have spoiled still goes out.

What are the role and the tenant, and do I need them?

They are the two values that say which contracted view of the data your request runs under. If your credentials are mapped to exactly one of each, the provider infers them and you can leave both empty. If your account carries more than one, they are required, and leaving them out produces a refusal that reads like a permissions problem rather than a missing parameter. Both are issued by the provider, not chosen by you.

Which document class should I ask for?

Ask for what you want back. A person document describes the individual. A household document describes the group of people at an address, which is the right class for anything addressed to a dwelling rather than a name. A place document describes the address itself. A residency joins a household to a place. A business document describes a company. An entity document is the resolved identity across the sources behind all of them. Asking for the wrong class returns nothing rather than an error, so it is worth being deliberate.

What does a partial name match mean?

The provider's default cascade includes steps that match on an email address or a phone number alone. When part of the name also lines up on such a match, it is reported as partial rather than as a bare contact-detail match, and it ranks higher. It is not a full name match: some of the name matched and some did not. Use the strict match level to skip those steps entirely, or the partial name filter to drop them after the fact.

Why does asking for ten documents per record cost so much more?

Because each document in a multi-document result is billed by the provider as its own transaction, and is written here as its own row. A hundred records at a limit of ten is up to a thousand of each. The run logs the arithmetic before it starts. The limit does not loosen what counts as a match; it only lets through more of the matches that already qualified.

Can I run this without credentials?

No, and the actor will tell you so rather than failing. Every call uses your own OAuth client id and secret, and access to this data is contracted: the provider approves a production key against a stated use before issuing one. Credentials also expire every six months, so a pair that used to work may simply have aged out.

Keyword map

consumer identity data API, identity graph resolution, identity resolution API, person household match API, email to identity append, hashed email lookup, persistent identity link, address hygiene and match, household data API, consumer demographics API, entity resolution API, batch identity match, PII-free identity lookup, business firmographic match, identity data enrichment.