The Lookup endpoint can be used to perform exact matching on hashed PII strings (including email addresses). Unlike the Match endpoint, the Lookup Endpoint provides only a single RampID for a given combination of touchpoints.

If there is a maintained record associated with the input string or ID, the maintained RampID is returned. If a maintained record is not associated with the input string or ID, a derived RampID is returned.

All calls to the Lookup endpoint must be structured as batch request calls. You can pass in up to 1000 URL strings in a single batch call.

For more information on how matching works, see The Lookup Endpoint.

Lookup Type Parameter and Lookup Value

The lookup_type parameter is used to specify the type of input data included in the API call.

The key parameter specifies the hashed input data lookup value for the call depending on the lookup_type parameter. The key parameter is required for all Lookup endpoint requests.

Use the Lookup endpoint when you don’t want to send raw PII in your API call. The Lookup endpoint allows you to retrieve an exact match to a single hashed PII touchpoint.

You can use the Lookup endpoint to send MD5-hashed email addresses, SHA256-hashed email addresses. SHA1-hashed email addresses, or SHA1-hashed PII strings.

If there is a maintained record associated with the input string or ID, the maintained RampID is returned.

If a maintained record is not associated with the input string or ID, a derived RampID is returned.

Sending Hashed PII Strings

In addition to hashed email addresses, the Lookup endpoint accepts SHA1-hashed PII strings as input. The following SHA1-hashed PII strings are supported:

• Email
• Phone
• Name + Email
• Name + PhoneNumber
• Name + ZipCode

Calls to the Lookup endpoint using a SHA1-hashed PII string as input only return a maintained identifier if the hashed string has an exact match against a maintained record in the Identity Graph. The Lookup endpoint does not perform any approximate or fuzzy string matching. While all fields in the construction of a hashed PII string are optional, the presence or absence of fields may affect the results returned.

📘

Allowed Hash Types

If you're sending just email addresses as input, you can use SHA-1, MD-5, or SHA-256 hashing.

If you're sending any PII other than email addresses, you must use SHA-1 hashing.

Set the "lookup_type" parameter to the hash type used ("sha1", "md5", or "sha256").

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.

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.

For more information, see The Lookup Endpoint.