Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Identity Match


Identity Match verifies who owns a mobile phone number by checking if the name, address, and date of birth provided match the information associated with that number from reliable sources like telecommunications companies. The Identity Match API then shows the match results for each piece of data, giving customers a detailed look at how closely the user's identity aligns with the information stored by the authoritative source.

To make an Identity Match request, add identity_match to the optional query parameter Fields when making a standard Lookup request, as well as any optional identity-based query parameters described in this section.


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

(information)

Info

Release Stage and Access: Generally Available. Certain carriers require approval to start the process. Submit this form to request access(link takes you to an external page). Once access is granted, all successful queries will be billed to your account. Rates are determined by the location of the user being identified and can be found in the table below. To discuss pricing in more detail or to see if you qualify for volume based discounts, please contact Twilio sales.

Identity Match is accessible for US phone numbers by default. You do not need to submit an access request.


Coverage

coverage page anchor
(warning)

Warning

Identity Match requires pre-approval from mobile network operators prior to gaining access and is supported in select countries.

We are supporting countries in Europe, Latin America, and North America listed in the table below. Countries marked with a * symbol require additional carrier approval before using Identity Match.

Europe

  • 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

Latin America

  • Brazil $0.20/query

North America

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

Frequently Asked Questions

frequently-asked-questions page anchor

What is the recommended implementation of Identity Match

Identity Match is most frequently used in your new user onboarding workflow. We suggest submitting all of the end user PII (including FirstName, LastName, and AddressLine1 at a minimum for best results) whenever a new user signs up for your service. Depending on how much information you decide to validate with the Identity Match API, you can decide if you want to leverage our Summary Score or if you would prefer to use more sophisticated logic based on individual parameter match values. If you are validating more than the three parameters mentioned above, we suggest using your own match logic, as the Summary score will only be based on those three parameters.

What is considered a "good match rate?"

What is considered a "good match rate" for Identity Match really depends on the attribute(s) you focus on for your particular use case, and the quality of the data that you are sending through to the Identity Match API.

For example, imagine an end user is signing up for an online bank account - they are very likely to provide all the correct information. In turn, this will drive 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 necessarily provide all the correct data to the customer. In turn, this will impact match rates when that end user data is compared with data held at our authoritative sources.

Therefore, it is your use case that determines which data elements are important and what you should look for when evaluating the responses from the API. The quality of the data supplied for those data elements will have a direct impact on the output from Identity Match.

How does Twilio measure the accuracy of our data providers?

We ensure accuracy of a given provider when we onboard them - we validate accuracy using a truth file.

Truth files start with PII match data that results in an "exact match" - then, a series of permutations of this data are generated to gradually reduce the match quality to "no match." If the resultant match value at each stage are as expected, it helps us to confirm the accuracy of that provider.

Can Identity Match requests contain multiple addresses?

Currently, the Identity Match API only allows for a single input data set (name/address/DOB/NationalId against the end-user's mobile phone number), and returns a single set of match results in response.


You can include parameters in your request that represent user-provided information. Lookup will provide match scores for how the given parameters compare against authoritative phone-based data sources.

Most of these parameters are optional for phone numbers based in most countries. However, some countries require the inclusion of certain parameters and have different data formatting rules. If a country-required parameter is not included, Error 60617 will be returned. See the Query parameter country requirements section for more information.

Query ParameterDescriptionMax Character Length
FirstNameUser's first name.128 Characters
LastNameUser's last name.128 Characters
AddressLine1User's first address line. Example: 1600 Pennsylvania Ave NW.256 Characters
AddressLine2User's second address line. Example: Suite 2.256 Characters
CityUser's city.128 Characters
StateUser's country subdivision, such as state, province, or locality.128 Characters
PostalCodeUser's postal zip code.10 Characters
AddressCountryCodeUser's country, up to two characters.2 Characters
NationalIdUser's national ID, such as SSN.128 Characters
DateOfBirthUser's date of birth, in YYYYMMDD format. Example: 19901213.8 Characters

Query parameter country requirements

query-parameter-country-requirements page anchor

Australia

australia page anchor

Note: We are not accepting new customers for Identity Match in Australia at this time. AddressLine1: Optional parameter. Use only the address formats in the examples below for flats, units, or apartments.

Address descriptionAddressLine1 formatting options
For flat 2 at 14 Smith StreetFlat 2 14 Smith St, 2/14 Smith St, or F 2 14 Smith St
For unit 2 at 14 Smith StreetUnit 2 14 Smith St, 2/14 Smith St, or U 2 14 Smith St
For apartment 2 at 14 Smith Street2/14 Smith or APT 2 14 Smith St

AddressLine2: Do not include this parameter, this information should be included in AddressLine1.

State: Optional parameter. Use state abbreviations such as "QLD" instead of the full state name.

FirstName: Required parameter. For a name with multiple words, only the first word should be used for this field. For example, the name "Luis Carlos Teixeira Brito Junior" should be set as "Luis".

LastName: Required parameter. For a name with multiple words, every word after the first should be used for this field. For example, the name "Luis Carlos Teixeira Brito Junior" should be set as "Carlos Teixeira Brito Junior".

AddressLine1: Required parameter. Use the format "streetName streetNumber BL blNumber APT aptNumber neighborhoodName". For example: "RUA COSTA ESMERALDA 50 BL 14 APT 22 CENTR".

AddressLine2: Do not include this parameter, this information should be included in AddressLine1.

City: Do not include this parameter, it cannot be evaluated in Brazil.

AddressCountryCode: Do not include this parameter, it cannot be evaluated in Brazil.

PostalCode: Do not include this parameter, it cannot be evaluated in Brazil.

DateOfBirth: Optional parameter. Use the format YYYYMMDD.

FirstName: Optional parameter. First letter must be capitalized.

LastName: Optional parameter. First letter must be capitalized.

AddressLine1: Optional parameter. Either the house number or house name should be used for this field. A house name is given to important buildings and estates such as castles. For example: "Château Gütsch".

AddressLine2: Optional parameter. If a house number was given in AddressLine1, this field should be the street name. If a house name was given in AddressLine1, this field is not necessary.

City: Required parameter when AddressLine1 or AddressLine2 is provided. The full name of the city should be used. For example, the city "Biel/Bienne" should be set to "Biel/Bienne" instead of "Biel", "Bienne", or "Biel Bienne".

PostalCode: Required parameter when AddressLine1 or AddressLine2 is provided.

Residential example 1Residential example 2Celebrity or important building example
AddressLine12424Château Gütsch
AddressLine2Bahnhofstrrue de la Gare
CityBiel/BienneBiel/BienneZurich
StateBEBE
PostalCode250225021111

FirstName: Required parameter.

LastName: Required parameter.

AddressLine1: Required parameter. The street name and house number should be used for this field. For example: "Immermannstraße 26", "Oderbergerstrasse 12".

City: Required parameter.

PostalCode: Required parameter

DateOfBirth: Optional parameter. Use the format YYYYMMDD.

FirstName: Required parameter.

LastName: Required parameter.

AddressLine1: Required parameter. The street name and house number or house name should be used for this field. Include both the house number and name if they are available.

PostalCode: Required parameter

FirstName: Required parameter.

LastName: Required parameter.

AddressLine1: Required parameter. The street type, street name, and building name/number should be used for this field. For example: "via Garibaldi 27" or "27 via Garibaldi", "Via Giacomo Quarenghi 34" or "34 Via Giacomo Quarenghi".

PostalCode: Optional parameter. Field must be five digits long. For example: "00015", "80044", "00145".

FirstName: Optional parameter. The first initial should be used for this field. For example, the name "Luca" should be set as "L".

AddressLine1: Optional parameter. The street name and house number should be used for this field. For example: "Jaarbeursplein 6A", "Joris van Andringastraat 172"

PostalCode: Optional parameter. Field must be composed of four digits and two characters with no spaces. For example: "3054SP", "3521AL", "1055VV".

DateOfBirth: Optional parameter. Use the format YYYYMMDD.


Lookup generates scores to represent the level of match between the user-provided information and the authoritative information.

Score ValueDescription
exact_matchThe user's data matches the mobile number's data exactly.
high_partial_matchThe user's data almost exactly matches the mobile number's data. For example, "Robere" is a high partial match for "Robert".
partial_matchThe user's data moderately matches the mobile number's data. For example, "Bob", "Rob", or "R" is a partial match for "Robert".
no_matchThe user's data does not match the mobile number's data at all.
no_data_availableData was not available to compare to the user's data.

The following additional response properties are returned for an Identity Match request.

Response PropertyDescription
first_name_matchLevel of match for FirstName attribute assigned to the submitted mobile number. One of: exact_match, high_partial_match, partial_match, no_match, no_data_available.
last_name_matchLevel of match for LastName attribute assigned to the submitted mobile number. One of: exact_match, high_partial_match, partial_match, no_match, no_data_available.
address_line_matchLevel of match for AddressLine1 and AddressLine2 attributes assigned to the submitted mobile number. One of: exact_match, high_partial_match, partial_match, no_match, no_data_available.
city_matchLevel of match for City attribute assigned to the submitted mobile number. One of: exact_match, no_match, no_data_available.
state_matchLevel of match for State attribute assigned to the submitted mobile number. One of: exact_match, no_match, no_data_available.
postal_code_matchLevel of match for PostalCode attribute assigned to the submitted mobile number. One of: exact_match, no_match, no_data_available.
address_country_matchLevel of match for AddressCountryCode assigned to the submitted mobile number. One of: exact_match, no_match, no_data_available.
date_of_birth_matchLevel of match for DatefBirth attribute assigned to the submitted mobile number. One of: exact_match, no_match, no_data_available. Note: for users in Canada we also support high_partial_match and partial_match.
national_id_matchLevel of match for NationalId attribute assigned to the submitted mobile number. One of: exact_match, no_match, no_data_available.
summary_scoreA single summary score that indicates overall level of match, ranging from 0 (no match) to 100 (exact match) derived from the first_name_match, last_name_match, and address_line_match properties.

The summary_score indicates an overall level of match, ranging from 0 (no match) to 100 (exact match) with possible values being 0, 40, 80, or 100. The summary_score property is not a percentage score, its value is derived from the values of the first_name_match, last_name_match, and address_line_match properties.

The table below shows how the summary_score is calculated in different scenarios.

first_name_matchlast_name_matchaddress_line_matchsummary_score
Any positive match score: exact_match, high_partial_match, partial_matchAny positive match score: exact_match, high_partial_match, partial_matchAny positive match score: exact_match, high_partial_match, partial_match100
Any positive match score: exact_match, high_partial_match, partial_matchAny negative match score: no_match, no_data_availableAny positive match score: exact_match, high_partial_match, partial_match80
Any positive match score: exact_match, high_partial_match, partial_matchAny positive match score: exact_match, high_partial_match, partial_matchAny negative match score: no_match, no_data_available40
Any negative match score: no_match, no_data_availableAny positive match score: exact_match, high_partial_match, partial_matchAny positive match score: exact_match, high_partial_match, partial_match20
Any positive match score: exact_match, high_partial_match, partial_matchAny negative match score: no_match, no_data_availableAny negative match score: no_match, no_data_available0
Any negative match score: no_match, no_data_availableAny positive match score: exact_match, high_partial_match, partial_matchAny negative match score: no_match, no_data_available20
Any negative match score: no_match, no_data_availableAny negative match score: no_match, no_data_availableAny positive match score: exact_match, high_partial_match, partial_match0
Any negative match score: no_match, no_data_availableAny negative match score: no_match, no_data_availableAny negative match score: no_match, no_data_available0

Valid phone number (paid)

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_24
// Download the helper library from https://www.twilio.com/docs/node/install
_24
import twilio from "twilio";
_24
_24
// Find your Account SID and Auth Token at twilio.com/console
_24
// and set the environment variables. See http://twil.io/secure
_24
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_24
const authToken = process.env.TWILIO_AUTH_TOKEN;
_24
const client = twilio(accountSid, authToken);
_24
_24
const phoneNumber = await client.lookups.v2.phoneNumbers("+14159929960").fetch({
_24
addressCountryCode: "US",
_24
addressLine1: "321 Main Street",
_24
addressLine2: "Suite 2",
_24
city: "New York",
_24
dateOfBirth: "19901214",
_24
fields: "identity_match",
_24
firstName: "John",
_24
lastName: "Doe",
_24
nationalId: "YZ3456883",
_24
postalCode: "10021",
_24
state: "NY",
_24
});
_24
_24
console.log(phoneNumber.callingCountryCode);

Output

_32
{
_32
"calling_country_code": "1",
_32
"country_code": "US",
_32
"phone_number": "+14159929960",
_32
"national_format": "(415) 992-9960",
_32
"valid": true,
_32
"validation_errors": [],
_32
"caller_name": null,
_32
"sim_swap": null,
_32
"call_forwarding": null,
_32
"line_status": null,
_32
"line_type_intelligence": null,
_32
"identity_match": {
_32
"first_name_match": "exact_match",
_32
"last_name_match": "high_partial_match",
_32
"address_lines_match": "no_match",
_32
"city_match": "no_match",
_32
"state_match": "high_partial_match",
_32
"postal_code_match": "no_data_available",
_32
"address_country_match": "exact_match",
_32
"national_id_match": "exact_match",
_32
"date_of_birth_match": "exact_match",
_32
"summary_score": 90,
_32
"error_code": null,
_32
"error_message": null
_32
},
_32
"reassigned_number": null,
_32
"sms_pumping_risk": null,
_32
"phone_number_quality_score": null,
_32
"pre_fill": null,
_32
"url": "https://lookups.twilio.com/v2/PhoneNumbers/+14159929960"
_32
}


Rate this page: