Identity Match
Identity Match compares user-supplied data against authoritative sources, such as name, address, and date of birth. To help determine how closely the user's identity aligns with the information stored by these sources, Identity Match returns match levels and an overall summary score.
You can use Identity Match for phone numbers in the following countries.
Some countries require carrier approvals
Identity Match for phone numbers in the United States and Brazil doesn't require carrier registration and approval. Phone numbers from Canada, France, Germany, Italy, Netherlands, Spain, and United Kingdom require additional carrier registration and approval. After you register with the carrier and get approval, Twilio bills all successful queries to your account. Twilio charges Lookup customers for all successful 200 OK responses. If your API response contains "error_code": null, you get billed for that particular query.
To learn more about pricing and discount information, contact Sales.
Make a GET /v2/PhoneNumbers/{PhoneNumber} request with the following as query parameters:
Fields=identity_match- User-provided information. For example,
FirstName=John.
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 parameters are optional for phone numbers in most countries. Some countries have specific requirements.
| Query parameter | Description | Max length | Example |
|---|---|---|---|
FirstName | Write the user given name. | 128 | Abraham |
LastName | Write the user surname. | 128 | Lincoln |
AddressLine1 | Write the first line of the user physical address. | 256 | The White House |
AddressLine2 | Write the second line of the user physical address. | 256 | 1600 Pennsylvania Ave NW |
City | Write the city of the user physical address. | 128 | Washington |
State | Write the political country subdivision of the user physical address. | 128 | DC |
PostalCode | Write the postal or ZIP code of the user physical address. | 10 | 20500 |
AddressCountryCode | Write the country code of the user physical address. | 2 | US |
NationalId1 | Write the national ID of the user. | 128 | 000-00-0000 |
DateOfBirth | Write the date of birth of the user in YYYYMMDD format. | 8 | 19901213 |
To learn how to become Twilio KYC approved, see Twilio Trust Hub.
Some countries require specific parameters and have different data formatting rules. If a required parameter is missing, Error 60617 will be returned.
| Parameter | Usage | Description |
|---|---|---|
AddressLine1 | Optional | Use only the address formats. |
AddressLine2 | Exclude | Append this data to AddressLine1. |
State | Optional | Use state abbreviations instead of the full state name. |
In the following examples for flats, units, or apartments:
| Physical Address | Written format |
|---|---|
| Flat 2 at 14 Smith St | Write as Flat 2 14 Smith St, 2/14 Smith St, or F 2 14 Smith St. |
| Unit 2 at 14 Smith St | Write as Unit 2 14 Smith St, 2/14 Smith St, or U 2 14 Smith St. |
| Apartment 2 at 14 Smith St | Write as 2/14 Smith or APT 2 14 Smith St. |
| Parameter | Usage | Description | Example |
|---|---|---|---|
FirstName | Required | Write only the first word. | Write Luis for the name Luis Carlos Teixeira Brito Junior. |
LastName | Required | Write all words after the first. | Write Carlos Teixeira Brito Junior for the name Luis Carlos Teixeira Brito Junior. |
AddressLine1 | Required | Write user address in this format{streetName streetNumber BL blNumber APT aptNumber neighborhoodName}. | RUA COSTA ESMERALDA 50 BL 14 APT 22 CENTR |
AddressLine2 | Exclude | Append this data to AddressLine1. | |
City | Exclude | This parameter can't be evaluated in Brazil. | |
AddressCountryCode | Exclude | This parameter can't be evaluated in Brazil. | |
PostalCode | Exclude | This parameter can't be evaluated in Brazil. | |
NationalId | Optional | Write the user national ID. |
| Parameter | Usage | Description | Example |
|---|---|---|---|
FirstName | Required | Write the user given name. | |
LastName | Required | Write the user surname. | |
AddressLine1 | Required | Write the street name and house number. | Immermannstraße 26 and Oderbergerstrasse 12 |
City | Required | Write the city of the user address. | |
PostalCode | Required | Write the postal code of the user address. | |
DateOfBirth | Optional | Write the user date of birth in YYYYMMDD format. | 20001201 |
| Parameter | Usage | Description |
|---|---|---|
FirstName | Required | Write the user given name. |
LastName | Required | Write the user surname. |
AddressLine1 | Required | Write the street name and house number or house name. If both the house number and house name are provided, write both. |
PostalCode | Required | Write the postal code of the user address. |
| Parameter | Usage | Description | Example |
|---|---|---|---|
FirstName | Required | Write the user given name. | |
LastName | Required | Write the user surname. | |
AddressLine1 | Required | Write the street type, street name, and building name or number. | via Garibaldi 27 or 27 via Garibaldi,Via Giacomo Quarenghi 34 or 34 Via Giacomo Quarenghi |
PostalCode | Optional | Write the five-digit postal code of the user address. | 00015 |
| Parameter | Usage | Description | Example |
|---|---|---|---|
FirstName | Optional | Write the first initial of the user given name. | Write L for the name "Luca". |
AddressLine1 | Optional | Write the street name and house number. | Jaarbeursplein 6A or Joris van Andringastraat 172 |
PostalCode | Optional | Write the postal code as four digits and two characters without spaces. | 3054SP or 3521AL |
DateOfBirth | Optional | Write date of birth of the user in the YYYYMMDD format. | 19901214 |
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.
| Match level | Description | Example |
|---|---|---|
exact_match | The user and mobile number data matches exactly. | Robert matches Robert. |
high_partial_match | The user and mobile number data almost exactly matches. | Robere is a high partial match for Robert. |
partial_match | The user and mobile number data moderately matches. | Bob, Rob, or R are partial matches for Robert. |
no_match | The user and mobile number data doesn't match at all. | John doesn't match Robert. |
no_data_available | No data is available for comparison. |
| Attribute | Description | Allowed value set |
|---|---|---|
first_name_match | The match level for the FirstName attribute assigned to the submitted mobile number. | 1 |
last_name_match | The match level for the LastName attribute assigned to the submitted mobile number. | 1 |
address_line_match | The match level for the AddressLine1 and AddressLine2 attributes assigned to the submitted mobile number. | 1 |
city_match | The match level for the City attribute assigned to the submitted mobile number. | 2 |
state_match | The match level for the State attribute assigned to the submitted mobile number. | 2 |
postal_code_match | The match level for the PostalCode attribute assigned to the submitted mobile number. | 2 |
address_country_match | The match level for the AddressCountryCode attribute assigned to the submitted mobile number. | 2 |
date_of_birth_match | The match level for the DateOfBirth attribute assigned to the submitted mobile number. | 1 (Canada only), 2 |
national_id_match | The match level for the NationalId attribute assigned to the submitted mobile number. | 3 |
summary_score | A single summary score that indicates overall match level. | See summary_score |
Allowed values enumerated:
exact_match,high_partial_match,partial_match,no_match,no_data_availableexact_match,no_match,no_data_availableexact_match,no_match,no_data_available,null
The summary_score represents the overall match level ranging from 0 (no match) to 100 (exact match). Twilio calculates this score using the match values of the properties as listed in the following table:
first_name_match | last_name_match | address_line_match | summary_score |
|---|---|---|---|
| Positive | Positive | Positive | 100 |
| Positive | Negative | Positive | 80 |
| Positive | Negative | Negative | 70 |
| Positive | Positive | Negative | 40 |
| Negative | Positive | Positive | 20 |
| Negative | Positive | Negative | 20 |
| Positive | Negative | Negative | 0 |
| Negative | Negative | Positive | 0 |
| Negative | Negative | Negative | 0 |
- Positive matches include
exact_match,high_partial_match, orpartial_match. - Negative matches include
no_match,no_data_available.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchPhoneNumber() {11const phoneNumber = await client.lookups.v212.phoneNumbers("+14159929960")13.fetch({14addressCountryCode: "US",15addressLine1: "321 Main Street",16addressLine2: "Suite 2",17city: "New York",18dateOfBirth: "19901214",19fields: "identity_match",20firstName: "John",21lastName: "Doe",22nationalId: "YZ3456883",23postalCode: "10021",24state: "NY",25});2627console.log(phoneNumber.callingCountryCode);28}2930fetchPhoneNumber();
Use Identity Match when onboarding users. When a user signs up for your service, Twilio recommends collecting all available end-user personally identifiable information (PII). Set FirstName, LastName, and AddressLine1 as the minimum required parameters.
- To make a quick evaluation, use the minimum required parameters and apply the
summary_score. - To evaluate with more parameters, create and apply your own match logic.
This depends on the attributes you prioritize for your use case and the quality of the data provided.
Match scenarios
- An end user signs up for an online bank account. The end user likely provides complete, correct information. When the user's data gets compared with data held within Twilio's authoritative sources, this improves match rates across all data elements.
- An end user signs up for a social media account. The end user might not provide complete, correct information. This reduces match rates.
The quality of the data you submit directly impacts the match results returned by Identity Match.
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.
-
Access to the
NationalIdfield in Identity Match responses is restricted to customers who have completed Twilio's KYC (Know Your Customer) process. Non-KYC customers will receive anullvalue in this field. ↩