The Retrieval API Developer Hub

The Retrieval API allows you to match your data to the LiveRamp Identity Graph and receive RampIDs. API calls are made using batch request calls that contain up to 1000 records per call.

Guides    API Reference

The Match Endpoint

Use the Match endpoint to send raw PII.

You can use the Match endpoint to send plaintext (raw) PII and receive from 1 to 10 RampIDs per record.

Use the Match endpoint when you want to maximize the match rate for your PII records by matching against all the available PII fields in a particular record (such as name, address, ZIP code, phone number, email address, etc.).

Plaintext PII sent to the Match endpoint goes through data normalization and utilizes fuzzy matching during the matching process. The Match endpoint matches against all available PII fields in a particular record such as name, address, ZIP code, phone number, or email address.

The PII is taken through a sequence of matching steps (the match cascade), until a match to a maintained RampID is found. If a maintained RampID is not found, a derived RampID is returned.

📘

See RampIDs for more information on maintained and derived RampIDs.

The Match endpoint is used in the following situations:

  • You want to match a file where the PII has not been normalized
  • You want to use fuzzy matching
  • You have files with multiple PII columns

Requesting More Than One RampID

To receive more than one maintained RampID, set the "limit" parameter to a number greater than one (to a maximum of ten).

When you send plaintext PII as input, if a maintained RampID is found during the match process and the "limit" parameter is set to a value greater than 1, the PII is taken through the match cascade again to see if another maintained RampID is associated with any of the PII. For example, if the limit parameter is set to 3, the call will return up to 3 maintained RampIDs associated with the input PII. The first maintained RampID might be associated with the Name/Address/Zip touchpoint, the second might be associated with the Name/Phone, and the third might be associated with the Name/Email.

When more than one maintained RampID is returned, a Group Document for the document class will be returned showing the RampID for the best match first and then any additional RampIDs for additional matches, up to a maximum of 10 (or the limit parameter that was set).

The limit parameter does not impact the requirements for a record to become a match; it only allows additional matches to be returned if they exist.

📘

Each document inside the group document is counted as a transaction.

Match Cascade

When you send plaintext PII as input, the Match endpoint first uses data normalization to structure data variations (for example, in street types, such “Boulevard” vs. “Blvd” vs. “Boulv”) and then converts each component into a hash. Fuzzy matching is then used to compare the hash to the obfuscated data in the identity graph following a match cascade.

The match cascade determines not only the order or priority of the types of matches that are attempted, but also which steps are performed. For example, the obfuscated name, street address, and zip code are compared. If there isn't a match, the obfuscated name and email address is compared, before moving on to the next steps in the match cascade.

Updated 3 months ago

The Match Endpoint


Use the Match endpoint to send raw PII.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.