Menu

Expand
Rate this page:

Identity Match

Lookup's Identity Match package allows you to get confirmation of ownership for a mobile phone number by comparing user-provided information against authoritative phone-based data sources.

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.

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

Release Stage and Access: Public Beta, to request access submit this form. Once access is granted, all successful queries will be billed to your account at a rate of $0.10/query in the United States. Additional countries have different pricing per the coverage table below. To discuss pricing in more detail or to see if you qualify for volume based discounts, please contact Twilio sales.

Coverage

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, North America, and Oceania 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
Oceania
  • Australia* $0.60/query

Query parameters

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.

It is optional to include these parameters for phone numbers based in most countries. However, some countries have standards that 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 Parameter Description
FirstName User’s first name.
LastName User’s last name.
AddressLine1 User’s first address line. Example: 1600 Pennsylvania Ave NW.
AddressLine2 User’s second address line. Example: Suite 2.
City User’s city.
State User’s country subdivision, such as state, province, or locality.
PostalCode User’s postal zip code.
AddressCountryCode User’s country, up to two characters.
NationalId User’s national ID, such as SSN or Passport ID.
DateOfBirth User’s date of birth, in YYYYMMDD format. Example: 19901213.

Query parameter country requirements

Australia

AddressLine1: Optional parameter. Use only the address formats in the examples below for flats, units, or apartments.

Address description AddressLine1 formatting options
For flat 2 at 14 Smith Street Flat 2 14 Smith St, 2/14 Smith St, or F 2 14 Smith St
For unit 2 at 14 Smith Street Unit 2 14 Smith St, 2/14 Smith St, or U 2 14 Smith St
For apartment 2 at 14 Smith Street 2/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.

Brazil

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 YYYY-MM-DD.

Switzerland

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 1 Residential example 2 Celebrity or important building example
AddressLine1 24 24 Château Gütsch
AddressLine2 Bahnhofstr rue de la Gare
City Biel/Bienne Biel/Bienne Zurich
State BE BE
PostalCode 2502 2502 1111

Germany

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 YYYY-MM-DD.

United Kingdom

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

Italy

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”.

Netherlands

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 YYYY-MM-DD.

Response properties

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

Response Property Description
first_name_match Level 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_match Level 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_match Level 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_match Level of match for City attribute assigned to the submitted mobile number. One of: exact_match, no_match, no_data_available.
state_match Level of match for State attribute assigned to the submitted mobile number. One of: exact_match, no_match, no_data_available.
postal_code_match Level of match for PostalCode attribute assigned to the submitted mobile number. One of: exact_match, no_match, no_data_available.
address_country_match Level of match for AddressCountryCode assigned to the submitted mobile number. One of: exact_match, no_match, no_data_available.
date_of_birth_match Level of match for DatefBirth attribute assigned to the submitted mobile number. One of: exact_match, no_match, no_data_available.
national_id_match Level of match for NationalId attribute assigned to the submitted mobile number. One of: exact_match, no_match, no_data_available.
summary_score A 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.

Summary score details

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_match last_name_match address_line_match summary_score
Any positive match score: exact_match, high_partial_match, partial_match Any positive match score: exact_match, high_partial_match, partial_match Any positive match score: exact_match, high_partial_match, partial_match 100
Any positive match score: exact_match, high_partial_match, partial_match Any negative match score: no_match, no_data_available Any positive match score: exact_match, high_partial_match, partial_match 80
Any positive match score: exact_match, high_partial_match, partial_match Any positive match score: exact_match, high_partial_match, partial_match Any negative match score: no_match, no_data_available 40
Any negative match score: no_match, no_data_available Any positive match score: exact_match, high_partial_match, partial_match Any positive match score: exact_match, high_partial_match, partial_match 20
Any positive match score: exact_match, high_partial_match, partial_match Any negative match score: no_match, no_data_available Any negative match score: no_match, no_data_available 0
Any negative match score: no_match, no_data_available Any positive match score: exact_match, high_partial_match, partial_match Any negative match score: no_match, no_data_available 20
Any negative match score: no_match, no_data_available Any negative match score: no_match, no_data_available Any positive match score: exact_match, high_partial_match, partial_match 0
Any negative match score: no_match, no_data_available Any negative match score: no_match, no_data_available Any negative match score: no_match, no_data_available 0

Match scores

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

Score Value Description
exact_match The user’s data matches the mobile number’s data exactly.
high_partial_match The user’s data almost exactly matches the mobile number’s data. For example, “Robere” is a high partial match for “Robert”.
partial_match The user’s data moderately matches the mobile number’s data. For example, “Bob”, “Rob”, or “R” is a partial match for “Robert”.
no_match The user’s data does not match the mobile number’s data at all.
no_data_available Data was not available to compare to the user’s data.
Loading Code Sample...
        
        
        Valid phone number (paid)

        Identity Match Lookup

        Valid phone number (paid)
        Rate this page:

        Need some help?

        We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

        Loading Code Sample...
              
              
              

              Thank you for your feedback!

              Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

              Sending your feedback...
              🎉 Thank you for your feedback!
              Something went wrong. Please try again.

              Thanks for your feedback!

              thanks-feedback-gif