Identity Match

Identity Match is available for phone numbers in the following countries.

• France* $0.55/query
• Germany* $0.40/query
• Italy* $1.20/query
• Netherlands* $0.60/query
• Spain* $0.40/query
• United Kingdom* $0.50/query

• Brazil $0.20/query

• Canada* $0.28/query
• United States $0.10/query
• Puerto Rico $0.10/query

Make a GET /v2/PhoneNumbers/{PhoneNumber} request with the following as query parameters:

• Fields=identity_match
• User-provided information. For example, FirstName=John.

1
curl -X GET "https://lookups.twilio.com/v2/PhoneNumbers/{PhoneNumber}?Fields=identity_match&FirstName=John" \ -u
2
$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

For detailed implementation examples, see Code examples and responses.

Provide the user-provided information as query parameters. Identity Match will provide match levels for how the given parameters compare against authoritative phone-based data sources.

Most of these parameters are optional for phone numbers in most countries. However, some countries have specific requirements.

Some countries require specific parameters and have different data formatting rules. If a required parameter is missing, Error 60617 will be returned.

The response includes the identity_match object, which contains match levels for the user's submitted data. The identity_match object also contains a summary score that provides an overall match level for the user's identity.

The summary_score represents the overall match level, with values ranging from 0 (no match) to 100 (exact match). Possible values include 0, 20, 40, 70, 80, and 100. This score isn't a percentage but is calculated based on the match values of the first_name_match, last_name_match, and address_line_match properties.

The following table shows how the summary_score is calculated based on different match scenarios:

Identity Match is most commonly used during new user onboarding workflows. Twilio recommends submitting all available end-user PII when a new user signs up for your service, with FirstName, LastName, and AddressLine1 as the minimum required parameters.

You can either rely on the summary score for a quick evaluation or implement more advanced logic based on individual parameter match levels. If you're validating more than the three key parameters mentioned above, Twilio suggests using your own match logic, as the summary score is calculated solely based on those parameters.

What's considered a "good match rate" for Identity Match depends on the attributes you prioritize for your use case and the quality of the data provided.

For example, imagine an end user is signing up for an online bank account. They're very likely to provide all the correct information. This will result in higher match rates across all data elements when that customer data is compared with data held at our authoritative sources.

Now imagine an end user is signing up for a social media account. They may not provide accurate data. This will result in lower match rates.

The quality of the data you submit directly impacts the match results returned by Identity Match.

When Twilio onboards an authoritative data source, we validate their data using a truth file.

A truth file begins with Personally Identifiable Information (PII) match data that results in an exact match. Twilio then generates a series of permutations of this data to gradually reduce the match quality to "no match." If the resulting match value at each stage aligns with expectations, then we can confirm the accuracy of the source data.

No, the Identity Match API only supports a single input data set per request. This includes the name, address, date of birth, and national ID associated with the end user's mobile phone number. The API returns a single set of match results in response.