Use the Lookup endpoint when you don't want to send plaintext PII.
The Lookup endpoint can be used to perform exact matching on hashed PII strings (including email addresses).
Using hashed PII strings allows API requests without requiring raw (plaintext) PII to be passed as input to the request.
The following SHA1-hashed PII strings are supported:
- Email: MD-5 hashed, SHA-256 hashed, or SHA-1 hashed
- Phone: SHA-1 hashed
- Name + Email: SHA-1 hashed
- Name + PhoneNumber: SHA-1 hashed
- Name + ZipCode: SHA-1 hashed
Allowed Hash Types
- If you're sending just email addresses as input, you can use SHA1, MD5, or SHA256 hashing.
- If you're sending any PII other than email addresses, you must use SHA1 hashing.
- Set the "lookup_type" parameter to the hash type used ("sha1", "md5", or "sha256").
Calls to the Lookup endpoint can be made as single transaction calls for an individual record or batch request calls for multiple records. When possible, batching your requests into groups of 1,000 will result in much better performance for your application. Batch request calls are subject to higher rate limits and are less likely to be throttled.
Making a batch request call involves making a POST call to https://us.identity.api.liveramp.com/v1/batch/lookup and passing in a JSON array of URL strings constructed in the same way as a single transaction call to the Lookup endpoint. You can pass up to 1,000 URL strings in a single batch call.
Data normalization or fuzzy matching is not used on any input data.
If a maintained AbiliTec link is not associated with the input data, the endpoint returns a derived AbiliTec link.
General Construction Rules
The rules listed below apply to all PII string types.
- Strings must be UTF-8 encoded.
- If a field is empty, it should be excluded from the string.
- Separate fields with single spaces. Don't add additional spaces if you leave out a particular field.
- Convert all fields to lowercase before hashing.
- Phone number should be digits only with no special characters.
- Hyphens are allowed except in phone numbers.
- Remove all periods (.) from name and phone fields. Do not remove periods from email addresses.
Constructing Names
See the table below for information on the elements that can be included when constructing names.
| Name Element | Description | Example | Required? |
|---|---|---|---|
| First Name | The person's first name. | Eduardo Felicia | Yes |
| Middle Name | The person's middle name or middle initial. | Kyu k john j | No |
| Last Name | The person's last name. | Lopez Nguyen | Yes |
| Generational Suffix | The person's generational name suffix. | Jr Sr II | No |
Constructing Postal Addresses
Postal addresses may be constructed in the following ways
- Primary Number + Pre Directional + StreetName + StreetSuffix + PostDirectional + Unit Designator + SecondaryNumber + City + State + Zip
- Zip
Supported Inputs for Each Hash
See the table below for all supported variations of hash type and input type. The elements in brackets [] are optional.
| Hash Type | Input Type | Formula |
|---|---|---|
| MD-5 | ||
| SHA-256 | ||
| SHA-1 | ||
| SHA-1 | Phone | Phone |
| SHA-1 | Postal | Primary Number + PreDirectional + Street Name + Street Suffix + PostDirectional + Unit Designator + Secondary Number + City + State + Zip |
| SHA-1 | Name + Email | First + [Middle OR Middle Initial] + Last + [Generational Suffix] + Email |
| SHA-1 | Name + Phone | First + [Middle OR Middle Initial] + Last + [Generational Suffix] + Phone |
| SHA-1 | Name + Postal | First + [Middle OR Middle Initial] + Last + [Generational Suffix] + [Primary Number] + [PreDirectional] + [Street Name] + [Street Suffix] + [PostDirectional] + [Unit Designator] + [Secondary Number] + [City] + [State] + Zip |
For more information, see "Lookup Function" in the Identity help.