---
"@context": https://schema.org
"@type": TechArticle
"@id": https://www.twilio.com/docs/lookup/v2-api/identity-match#article
headline: Identity Match
description: Use Identity Match to verify phone number ownership by comparing user data with authoritative sources. Available in the US, Brazil, and more.
url: https://www.twilio.com/docs/lookup/v2-api/identity-match
inLanguage: en
dateModified: 2026-09-22T21:26:59.000Z
author:
  "@type": Organization
  name: Twilio Developer Education Team
publisher:
  "@type": Organization
  name: Twilio
---

# Identity Match

Identity Match compares user-supplied data such as name, address, and date of birth against authoritative or carrier sources depending on the country the phone number belongs to. To help determine how closely the user's identity aligns with the information stored by these sources, Identity Match returns attribute specific match levels and an overall summary score.

## Coverage

You can use Identity Match for phone numbers in the following countries.

* United States of America
* Canada
* United Kingdom
* Brazil
* Netherlands
* Italy
* Spain
* Germany
* France

> \[!NOTE]
>
> Identity Match for phone numbers in the United States and Brazil uses 3rd party data providers that use authoritative sources, such as postal, utility databases, and credit bureaus. As a result, customers that want to use Identity Match in the US and Brazil don't require carrier registration or 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][].

## Attempt to match an identity

Make a [`GET /v2/PhoneNumbers/{PhoneNumber}`][get-phone] request with the following as query parameters:

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

Identity Match Lookup

```bash
curl -X GET "https://lookups.twilio.com/v2/PhoneNumbers/%2B14159929960?Fields=identity_match&FirstName=John" \
-u $TWILIO_API_KEY:$TWILIO_API_SECRET
```

For detailed implementation examples, see [Code examples and responses][code-examples].

## Query parameters

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`                       |
| `NationalId`[^1]     | 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`                 |

[^1]: Access to the `NationalId` field in Identity Match responses is restricted to customers who have completed Twilio's KYC (Know Your Customer) process. Non-KYC customers will receive a `null` value in this field. To learn how to become Twilio KYC approved, see [Twilio Trust Hub][].

## Frequently asked questions

#### How do you recommend I implement Identity Match?

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.

#### What's considered a "good match rate?"

This depends on the attributes you prioritize for your use case and the quality of the data provided.

> \[!NOTE]
>
> * 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.

#### Can Identity Match requests contain multiple addresses?

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.

[Error 60617]: /docs/api/errors/60617

[Some countries have specific requirements]: #country-specific-requirements

[Twilio Trust Hub]: /docs/trust-hub

[additional carrier registration and approval]: https://twlo.my.salesforce-sites.com/countrycarrier/SN_CarrierRegistration_VFP

[au-abbr]: https://www.bda-online.org.au/help/bda-conventions/abbreviations-states

[cc]: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

[code-examples]: #code-example-for-identity-match-lookup

[contact Sales]: https://www.twilio.com/en-us/help/sales

[get-phone]: /docs/lookup/v2-api#making-a-request

[pii]: https://en.wikipedia.org/wiki/Personal_data

[score]: #summary-score-calculation

### Country-specific requirements

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

#### Australia

| Parameter      | Usage    | Description                                                        |
| -------------- | -------- | ------------------------------------------------------------------ |
| `AddressLine1` | Optional | Use only the address formats.                                      |
| `AddressLine2` | Exclude  | Append this data to `AddressLine1`.                                |
| `State`        | Optional | Use [state abbreviations][au-abbr] 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`.                         |

#### Brazil

| 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<br />`{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.                                                                                    |                                                                                        |

#### Germany

| 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 <br />`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`                                            |

#### United Kingdom

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

#### Italy

| 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 <br />`27 via Garibaldi`,<br />`Via Giacomo Quarenghi 34` or <br />`34 Via Giacomo Quarenghi` |
| `PostalCode`   | Optional | Write the five-digit postal code of the user address.            | `00015`                                                                                                             |

#### Netherlands

| 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 <br />`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`                                                  |

## Response properties

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][score] that provides an overall match level for the user's identity.

### Match levels

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

### `identity_match` attributes and match levels

| 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`][score] | A single summary score that indicates overall match level.                                                    | See [`summary_score`][score] |

Allowed values enumerated:

1. `exact_match`, `high_partial_match`, `partial_match`, `no_match`, `no_data_available`
2. `exact_match`, `no_match`, `no_data_available`
3. `exact_match`, `no_match`, `no_data_available`, `null`

### Summary score calculation

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                      | Positive          | Negative(no\_data\_available) | `70`            |
| Negative(no\_data\_available) | Positive          | Positive                      | `60`            |
| Negative(no\_data\_available) | Positive          | Negative(no\_data\_available) | `60`            |
| Positive                      | Positive          | Negative(no\_match)           | `40`            |
| Negative(no\_data\_available) | Positive          | Negative(no\_match)           | `40`            |
| Negative(no\_match)           | Positive          | Positive                      | `20`            |
| Negative(no\_match)           | Positive          | Negative                      | `20`            |
| Positive                      | Negative          | Negative                      | `0`             |
| Negative                      | Negative          | Positive                      | `0`             |
| Negative                      | Negative          | Negative                      | `0`             |

* Positive matches include `exact_match`, `high_partial_match`, or `partial_match`.
* Negative matches include `no_match`, `no_data_available`.

## Code example for Identity Match lookup

Identity Match Lookup

```js
// Download the helper library from https://www.twilio.com/docs/node/install
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

// Find your Account SID at twilio.com/console
// Provision API Keys at twilio.com/console/runtime/api-keys
// and set the environment variables. See http://twil.io/secure
// For local testing, you can use your Account SID and Auth token
const accountSid = process.env.TWILIO_ACCOUNT_SID;
const apiKey = process.env.TWILIO_API_KEY;
const apiSecret = process.env.TWILIO_API_SECRET;
const client = twilio(apiKey, apiSecret, { accountSid: accountSid });

async function fetchPhoneNumber() {
  const phoneNumber = await client.lookups.v2
    .phoneNumbers("+14159929960")
    .fetch({
      addressCountryCode: "US",
      addressLine1: "321 Main Street",
      addressLine2: "Suite 2",
      city: "New York",
      dateOfBirth: "19901214",
      fields: "identity_match",
      firstName: "John",
      lastName: "Doe",
      nationalId: "YZ3456883",
      postalCode: "10021",
      state: "NY",
    });

  console.log(phoneNumber.callingCountryCode);
}

fetchPhoneNumber();
```

```python
# Download the helper library from https://www.twilio.com/docs/python/install
import os
from twilio.rest import Client

# Find your Account SID at twilio.com/console
# Provision API Keys at twilio.com/console/runtime/api-keys
# and set the environment variables. See http://twil.io/secure
# For local testing, you can use your Account SID and Auth token
api_key = os.environ["TWILIO_API_KEY"]
api_secret = os.environ["TWILIO_API_SECRET"]
account_sid = os.environ["TWILIO_ACCOUNT_SID"]
client = Client(api_key, api_secret, account_sid)

phone_number = client.lookups.v2.phone_numbers("+14159929960").fetch(
    fields="identity_match",
    first_name="John",
    last_name="Doe",
    address_line1="321 Main Street",
    address_line2="Suite 2",
    city="New York",
    state="NY",
    postal_code="10021",
    address_country_code="US",
    national_id="YZ3456883",
    date_of_birth="19901214",
)

print(phone_number.calling_country_code)
```

```csharp
// Install the C# / .NET helper library from twilio.com/docs/csharp/install

using System;
using Twilio;
using Twilio.Rest.Lookups.V2;
using System.Threading.Tasks;

class Program {
    public static async Task Main(string[] args) {
        // Find your Account SID at twilio.com/console
        // Provision API Keys at twilio.com/console/runtime/api-keys
        // and set the environment variables. See http://twil.io/secure
        // For local testing, you can use your Account SID and Auth token
        string apiKey = Environment.GetEnvironmentVariable("TWILIO_API_KEY");
        string apiSecret = Environment.GetEnvironmentVariable("TWILIO_API_SECRET");
        string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");

        TwilioClient.Init(apiKey, apiSecret, accountSid);

        var phoneNumber = await PhoneNumberResource.FetchAsync(
            pathPhoneNumber: "+14159929960",
            fields: "identity_match",
            firstName: "John",
            lastName: "Doe",
            addressLine1: "321 Main Street",
            addressLine2: "Suite 2",
            city: "New York",
            state: "NY",
            postalCode: "10021",
            addressCountryCode: "US",
            nationalId: "YZ3456883",
            dateOfBirth: "19901214");

        Console.WriteLine(phoneNumber.CallingCountryCode);
    }
}
```

```java
// Install the Java helper library from twilio.com/docs/java/install

import com.twilio.Twilio;
import com.twilio.rest.lookups.v2.PhoneNumber;

public class Example {
    // Find your Account SID at twilio.com/console
    // Provision API Keys at twilio.com/console/runtime/api-keys
    // and set the environment variables. See http://twil.io/secure
    // For local testing, you can use your Account SID and Auth token
    public static final String API_KEY = System.getenv("TWILIO_API_KEY");
    public static final String API_SECRET = System.getenv("TWILIO_API_SECRET");
    public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID");

    public static void main(String[] args) {
        Twilio.init(API_KEY, API_SECRET, ACCOUNT_SID);
        PhoneNumber phoneNumber = PhoneNumber.fetcher("+14159929960")
                                      .setFields("identity_match")
                                      .setFirstName("John")
                                      .setLastName("Doe")
                                      .setAddressLine1("321 Main Street")
                                      .setAddressLine2("Suite 2")
                                      .setCity("New York")
                                      .setState("NY")
                                      .setPostalCode("10021")
                                      .setAddressCountryCode("US")
                                      .setNationalId("YZ3456883")
                                      .setDateOfBirth("19901214")
                                      .fetch();

        System.out.println(phoneNumber.getCallingCountryCode());
    }
}
```

```go
// Download the helper library from https://www.twilio.com/docs/go/install
package main

import (
	"fmt"
	"github.com/twilio/twilio-go"
	lookups "github.com/twilio/twilio-go/rest/lookups/v2"
	"os"
)

func main() {
	// Find your Account SID at twilio.com/console
	// Provision API Keys at twilio.com/console/runtime/api-keys
	// and set the environment variables. See http://twil.io/secure
	// For local testing, you can use your Account SID and Auth token
	accountSid := os.Getenv("TWILIO_ACCOUNT_SID")
	apiKey := os.Getenv("TWILIO_API_KEY")
	apiSecret := os.Getenv("TWILIO_API_SECRET")
	client := twilio.NewRestClientWithParams(twilio.ClientParams{
		Username:   apiKey,
		Password:   apiSecret,
		AccountSid: accountSid,
	})

	params := &lookups.FetchPhoneNumberParams{}
	params.SetFields("identity_match")
	params.SetFirstName("John")
	params.SetLastName("Doe")
	params.SetAddressLine1("321 Main Street")
	params.SetAddressLine2("Suite 2")
	params.SetCity("New York")
	params.SetState("NY")
	params.SetPostalCode("10021")
	params.SetAddressCountryCode("US")
	params.SetNationalId("YZ3456883")
	params.SetDateOfBirth("19901214")

	resp, err := client.LookupsV2.FetchPhoneNumber("+14159929960",
		params)
	if err != nil {
		fmt.Println(err.Error())
		os.Exit(1)
	} else {
		if resp.CallingCountryCode != nil {
			fmt.Println(*resp.CallingCountryCode)
		} else {
			fmt.Println(resp.CallingCountryCode)
		}
	}
}
```

```php
<?php

// Update the path below to your autoload.php,
// see https://getcomposer.org/doc/01-basic-usage.md
require_once "/path/to/vendor/autoload.php";

use Twilio\Rest\Client;

// Find your Account SID at twilio.com/console
// Provision API Keys at twilio.com/console/runtime/api-keys
// and set the environment variables. See http://twil.io/secure
// For local testing, you can use your Account SID and Auth token
$apiKey = $_ENV["TWILIO_API_KEY"];
$apiSecret = $_ENV["TWILIO_API_SECRET"];
$sid = $_ENV["TWILIO_ACCOUNT_SID"];
$twilio = new Client($apiKey, $apiSecret, $sid);

$phone_number = $twilio->lookups->v2->phoneNumbers("+14159929960")->fetch([
    "fields" => "identity_match",
    "firstName" => "John",
    "lastName" => "Doe",
    "addressLine1" => "321 Main Street",
    "addressLine2" => "Suite 2",
    "city" => "New York",
    "state" => "NY",
    "postalCode" => "10021",
    "addressCountryCode" => "US",
    "nationalId" => "YZ3456883",
    "dateOfBirth" => "19901214",
]);

print $phone_number->callingCountryCode;
```

```ruby
# Download the helper library from https://www.twilio.com/docs/ruby/install
require 'twilio-ruby'

# Find your Account SID at twilio.com/console
# Provision API Keys at twilio.com/console/runtime/api-keys
# and set the environment variables. See http://twil.io/secure
# For local testing, you can use your Account SID and Auth token
api_key = ENV['TWILIO_API_KEY']
api_secret = ENV['TWILIO_API_SECRET']
account_sid = ENV['TWILIO_ACCOUNT_SID']
@client = Twilio::REST::Client.new(api_key, api_secret, account_sid)

phone_number = @client
               .lookups
               .v2
               .phone_numbers('+14159929960')
               .fetch(
                 fields: 'identity_match',
                 first_name: 'John',
                 last_name: 'Doe',
                 address_line1: '321 Main Street',
                 address_line2: 'Suite 2',
                 city: 'New York',
                 state: 'NY',
                 postal_code: '10021',
                 address_country_code: 'US',
                 national_id: 'YZ3456883',
                 date_of_birth: '19901214'
               )

puts phone_number.calling_country_code
```

```bash
# Install the twilio-cli from https://twil.io/cli

twilio api:lookups:v2:phone-numbers:fetch \
   --phone-number +14159929960 \
   --fields identity_match \
   --first-name John \
   --last-name Doe \
   --address-line1 "321 Main Street" \
   --address-line2 "Suite 2" \
   --city "New York" \
   --state NY \
   --postal-code 10021 \
   --address-country-code US \
   --national-id YZ3456883 \
   --date-of-birth 19901214
```

```bash
curl -X GET "https://lookups.twilio.com/v2/PhoneNumbers/%2B14159929960?Fields=identity_match&FirstName=John&LastName=Doe&AddressLine1=321%20Main%20Street&AddressLine2=Suite%202&City=New%20York&State=NY&PostalCode=10021&AddressCountryCode=US&NationalId=YZ3456883&DateOfBirth=19901214" \
-u $TWILIO_API_KEY:$TWILIO_API_SECRET
```

#### View the response

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