You can use the Match endpoint to send plaintext (raw) PII and receive from 1 to 10 RampIDs per PII 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 Match


Prerequisite for Requesting Multiple RampID Matches

You must have the 1:1 permission to request multiple RampID matches. If you require this permission, please contact your LiveRamp account representative.

By default, LiveRamp returns a single RampID match for each PII record. To receive more than one maintained RampID, you must set the "limit" parameter to an integer greater than one (to a maximum of ten). The API will return matches in order of decreasing match confidence. All matches must exceed the minimum match threshold to be returned, so it is possible that fewer matches than specified by the limit will be returned on a given request.

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.

For more information about the match cascade, see Data Returned by the Retrieval API - Match Metadata.