--- updatedAt: 2026-04-07T10:14:47.000Z agentTools: siteIndex: https://developers.liveramp.com/llms.txt projectIndex: https://developers.liveramp.com/rampid-api/llms.txt --- # Match Raw PII to RampID Use the Match endpoint to match raw PII data to a RampID. You should use the Match endpoint when: * You want to match a file where the data have not been normalized. * You want to use fuzzy matching. * You have files with multiple PII columns. When you send plaintext data to the Match endpoint, our algorithms perform data normalization and then use fuzzy matching when comparing the data to the LiveRamp Identity Graph. All PII fields in a particular record (such as name, address, ZIP code, phone number, or email address) are checked against the graph until a maintained RampID is found. If no maintained RampID is found, a derived RampID is returned. By default, the API returns a single RampID per PII record. All calls to the Match endpoint must be structured as [batch request calls](https://developers.liveramp.com/rampid-api/reference/batch-request-calls). You can pass in up to 1000 URL strings in a single batch call. > 📘 > > See [RampIDs](https://developers.liveramp.com/rampid-api/reference/rampids) for more information on maintained and derived RampIDs. > > See [Requesting Multiple RampID Matching](https://developers.liveramp.com/rampid-api/reference/requesting-more-than-one-rampid-match) for more information on matching a single PII record to multiple RampIDs. # Match Cascade When you send plaintext PII to the Match endpoint, LiveRamp first uses data normalization to structure data variations (for example, in street types, such as "Boulevard" vs. "Blvd" vs. "Boulv") and then converts each component into a hash. We then use fuzzy matching to compare different combinations of the hashes to the data in the LiveRamp identity graph. The sequence in which the different combinations are tried is called 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 are compared before moving on to the next steps in the match cascade. If a maintained RampID is not found after all the match cascade steps are performed, a derived RampID is returned. When a match is found, LiveRamp returns a response that includes [insights and metadata](https://developers.liveramp.com/rampid-api/reference/response-documents) about how the match was obtained (that is, about which steps in the match cascade provided a RampID), as well as the RampID itself. For more information, see "[Match Cascade](https://docs.liveramp.com/identity/en/abilitec-components.html#idp36885)" in the Identity help. ## Match Parameter Rules The following list describes the general rules for calls to the Match endpoint. * Each URL string must start with `/people/match?`. * Match parameters must be included after the `?` character in the URL string and formed as `[parameter_name]=[parameter_value]`. * Separate multiple parameters using `&`. * All calls must contain one or more match parameters in each URL string. * Do not include the parsed name (for example, `firstName`, `middleName`, and `lastName`) AND the unparsed name ( `name`) in the same request. * Do not include the parsed street address (for example, `primaryNumber`, `street`) AND the unparsed street address (`streetAddress`) in the same request. ### Match Parameter Validation | Variable | Rule | | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | state | Must be the two-character uppercase state abbreviation | | zipCode | Must be 5, 9, or 11 digits | | email | Must contain an @ character and must contain a period (`.`) in the domain portion | | phone | Must be 10 digits with no special characters | | limit | Must be an integer from 1 to 10. You can only specify an integer greater than 1 if you have the 1:1 permission. Contact your LiveRamp account representative for details | ### Match Parameter Combinations Below are the most common input parameter combinations. Brackets (`[ ]`) around a parameter indicates the parameter is optional. | Input Parameter Combination | | :------------------------------------------- | | Name + Street + \[City] + \[State] + ZipCode | | Name + Email | | Name + Phone | | Email | | Phone | | Name + ZipCode | # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "abilitec-api", "version": "1.2" }, "servers": [ { "url": "https://us.identity.api.liveramp.com" } ], "components": { "securitySchemes": { "sec0": { "type": "oauth2", "flows": {} } } }, "security": [ { "sec0": [] } ], "paths": { "/v1/batch/match": { "post": { "summary": "Match Raw PII to RampID", "description": "Use the Match endpoint to match raw PII data to a RampID.", "operationId": "batch-request-calls-match", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The person's full name. Could include first, middle, last, and suffix. Example: \"Eduardo F Lopez Jr\". Do not include this parameter if the parameters for individual name components are included." }, "streetAddress": { "type": "string", "description": "The complete street address (postal address without city, state, zip). Example: \"101 W Main St S Apt 12\". Do not include this parameter if the parameters for individual address components are included." }, "firstName": { "type": "string", "description": "The person's first name. Examples: \"Eduardo\", \"Felicia\". Do not include this parameter if the \"name\" parameter (the unparsed name) is included." }, "middleName": { "type": "string", "description": "The person's middle name or middle initial. Examples: \"Kyu\", \"K\", \"John\", \"J\". Do not include this parameter if the \"name\" parameter (the unparsed name) is included." }, "lastName": { "type": "string", "description": "The person's last name. Examples: \"Lopez\", \"Nguyen\". Do not include this parameter if the \"name\" parameter (the unparsed name) is included." }, "generationalSuffix": { "type": "string", "description": "The person's generational name suffix. Examples: \"Jr\", \"Sr\", \"II\". Do not include this parameter if the \"name\" parameter (the unparsed name) is included." }, "primaryNumber": { "type": "string", "description": "The street number in a postal address. Examples: \"10\", \"123\", \"3333\". Do not include this parameter if the \"streetAddress\" parameter (the unparsed street address) is included." }, "preDirectional": { "type": "string", "description": "The street pre-directional in a postal address. Examples: \"N\", \"S\", \"E\", \"W\". Do not include this parameter if the \"streetAddress\" parameter (the unparsed street address) is included." }, "street": { "type": "string", "description": "The street name in a postal address. Examples: \"Main\", \"Finley\", \"Hillsdale\". Do not include this parameter if the \"streetAddress\" parameter (the unparsed street address) is included." }, "streetSuffix": { "type": "string", "description": "The street suffix in a postal address. Example: St, Dr, Rd, Blvd. Do not include this parameter if the \"streetAddress\" parameter (the unparsed street address) is included." }, "postDirectional": { "type": "string", "description": "The street post-directional in a postal address. Example: N, S, E, W. Do not include this parameter if the \"streetAddress\" parameter (the unparsed street address) is included." }, "unitDesignator": { "type": "string", "description": "The secondary unit designator in a postal address. Example: Apt, Ste, Fl, Unit. Do not include this parameter if the \"streetAddress\" parameter (the unparsed street address) is included." }, "secondaryNumber": { "type": "string", "description": "The secondary number in a postal address. Does not include the unit designator text (for example, Apt., or #). Example: 12A, 4, 105. Do not include this parameter if the \"streetAddress\" parameter (the unparsed street address) is included." }, "city": { "type": "string", "description": "The city. Example, Los Angeles, Seattle, Paris." }, "state": { "type": "string", "description": "The 2-character standard abbreviation. Example: CA, TN, CO, CT." }, "zipCode": { "type": "string", "description": "The zip/postal code (5 digit, 9 digit, or 11 digit). Example: 95010, 10004-4357" }, "email": { "type": "string", "description": "The plaintext email address." }, "phone": { "type": "string", "description": "For U.S. phone numbers, the complete phone number that includes the 10 digits without delimiters. Example: 6305558052" }, "limit": { "type": "string", "description": "The maximum number of matches to be returned by the API. An integer between `1` (default) and `10` (maximum), inclusive. `1` causes the API to return only the best match, if available. When limit is set to a value greater than `1`, 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. **Note: You must have the 1:1 permission to specify a limit other than `1`.** If you need the 1:1 permission, contact your LiveRamp account representative.", "default": "1" }, "strictValidation": { "type": "string", "description": "Indicates whether a strict match of all parameters is required. When this is set to false, the service will blank out any invalid data and attempt a match with the remaining parameters. Default: true" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Match found": { "value": "{\n\t\"entity\": {\n\t\t\"anonymousAbilitec\": {\n\t\t\t\"anonymousConsumerLink\": \"ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789\",\n\t\t\t\"anonymousAddressLink\": \"ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789\",\n\t\t\t\"anonymousHouseholdLink\": \"ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789\"\n\t\t},\n\t\t\"matchMetadata\": {\n\t\t\t\"matchComponents\": [\n\t\t\t\t\"name\",\n\t\t\t\t\"streetAddress\",\n\t\t\t\t\"zipCode\"\n\t\t\t],\n\t\t\t\"distinctMatch\": true,\n\t\t\t\"matchConfidence\": \"1\",\n\t\t\t\"nameMatchIntegrity\": \"complete\"\n\t\t}\n\t}\n}" }, "No match found": { "value": "{\n\t\"person\": {\n\t\t\"abilitec\": {\n\t\t\t\"consumerLink\": \"0000US1108400000\"\n\t\t}\n\t}\n}\n" } }, "schema": { "oneOf": [ { "title": "Match found", "type": "object", "properties": { "entity": { "type": "object", "properties": { "anonymousAbilitec": { "type": "object", "properties": { "anonymousConsumerLink": { "type": "string", "example": "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789" }, "anonymousAddressLink": { "type": "string", "example": "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789" }, "anonymousHouseholdLink": { "type": "string", "example": "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789" } } }, "matchMetadata": { "type": "object", "properties": { "matchComponents": { "type": "array", "items": { "type": "string", "example": "name" } }, "distinctMatch": { "type": "boolean", "example": true, "default": true }, "matchConfidence": { "type": "string", "example": "1" }, "nameMatchIntegrity": { "type": "string", "example": "complete" } } } } } } }, { "title": "No match found", "type": "object", "properties": { "person": { "type": "object", "properties": { "abilitec": { "type": "object", "properties": { "consumerLink": { "type": "string", "example": "0000US1108400000" } } } } } } } ] } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": "{}" } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false, "x-readme": { "code-samples": [ { "language": "curl", "code": "curl --location --request POST https://us.identity.api.liveramp.com/v1/batch/match\n--header 'Accept: application/json'\n--header 'Content-Type: application/json'\n--header \"Authorization: Bearer ${TOKEN}\"\n--data '[\"/people/match?name=NAME1 HERE\" ]'\n", "name": "cURL - single input" }, { "language": "curl", "code": "curl --location --request POST https://us.identity.api.liveramp.com/v1/batch/match\n--header 'Accept: application/json'\n--header 'Content-Type: application/json'\n--header \"Authorization: Bearer ${TOKEN}\"\n--data '[\"/people/match?name=NAME1 HERE\",\n\"/people/match?name=NAME2 HERE\",\n\"/people/match?name=NAME3 HERE\"\n]'\n", "name": "cURL - multiple inputs" } ], "samples-languages": [ "curl" ] } } } }, "x-readme": { "headers": [], "explorer-enabled": false, "proxy-enabled": true }, "x-readme-fauxas": true } ```