Identity Insights API

The Identity Insights API allows clients to request real-time information related to a phone number. Users can retrieve any combination of different datasets, known as insights (e.g., number formatting, SIM swap information), in a single API call.

Each insight is processed independently, and the response includes a structured result for each insight along with a status code. The status code can contain the following values:

OK All Insight attributes are available and included in the response.
PARTIAL_SUCCESS Some response attributes were omitted because they are not applicable or were not available.
INVALID_NUMBER_FORMAT The phone number format is not valid for assignment by carriers to users.
NO_COVERAGE The country or mobile network is not supported by available suppliers.
NOT_FOUND The phone number could not be found for this Insight.
UNAUTHORIZED The request could not be authorized for the combination of application, supplier, and phone number.
INVALID_PURPOSE The purpose used is not valid or allowed for this Insight.
SUPPLIER_ERROR The supplier returned an error while processing the request.
INTERNAL_ERROR An internal error occurred while processing the request.

Additionally, Subscriber Match Insight can return the following status codes:

SUBSCRIBER_MATCH.ID_DOCUMENT_REQUIRED Operator requires idDocument to match any other attributes.
SUBSCRIBER_MATCH.ID_DOCUMENT_MISMATCH Operator cannot match idDocument which is required to match any other attributes.
SUBSCRIBER_MATCH.INVALID_PARAM_COMBINATION Indicated parameter combination is invalid.

Download OpenAPI Specification

Identity Insights

Provides real-time intelligence about a phone number.

Available Operations

Retrieve identity insights from a phone number

Retrieve identity insights from a phone number

Provides multiple phone number insights (e.g., format validation, SIM swap status) in a single request.

posthttps://api-eu.vonage.com/v0.1/identity-insights

Authentication

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`

Request Body
Content Type
application/json

phone_number

string

Required

example14040000000

A single phone number you want insights on, starting with the country code. You may optionally include a leading +, but do not use 00 at the beginning. Ideally, the number should follow the E.164 format. However, the API is designed to extract the phone number even if the input string contains alphanumeric characters, spaces, or symbols like brackets.

purpose

string

exampleFraudPreventionAndDetection

Specifies the reason for the request. This property is required only for Insights that use the Network Registry. For a Network Registry of type Production, the value must match one of the network profile purposes associated with your application. For a Network Registry of type Playground, the value must be "FraudPreventionAndDetection".

insights

object

Required

A list of objects representing the insight(s) requested for the phone number. At least one insight must be requested.

format

object

[BETA FEATURE] Request the format insight. This field must always be set to an empty object {}.

sim_swap

[BETA FEATURE] Request the sim_swap insight.

period

integer(int32)

Min1

Max2400

Default240

example240

Period in hours to be checked for SIM swap.

original_carrier

object

[BETA FEATURE] Request the original_carrier insight. This field must always be set to an empty object {}.

current_carrier

object

[BETA FEATURE] Request the current_carrier insight. This field must always be set to an empty object {}.

location_verification

object

[DEVELOPER PREVIEW FEATURE] Request the location_verification insight.

location

object

type

string

Must be one of:CIRCLE

radius

integer(int32)

Min2000

Max200000

example3000

Expected accuracy for the verification in meters, from location (radius)

center

object

latitude

number

Min-90

Max90

longitude

number

Min-180

Max180

subscriber_match

object

[DEVELOPER PREVIEW FEATURE] Request the subscriber_match insight.

id_document

string

example66666666q

Id number associated to the official identity document in the country. It may contain alphanumeric characters.

given_name

string

exampleFederica

First/given name or compound first/given name of the customer.

family_name

string

exampleSanchez Arjona

Last name, family name, or surname of the customer.

street_name

string

exampleCrawfords Corner Road

Name of the street of the customer's address. It should not include the type of the street.

street_number

string

example4

The street number of the customer's address. Number identifying a specific property on the 'streetName'.

postal_code

string

example07733

Zip code or postal code

locality

string

exampleHolmdel

Locality of the customer's address

region

string

exampleMonmouth County

Region or prefecture of the customer's address

country

string

exampleUS

Country of the customer's address. Format ISO 3166-1 alpha-2

house_number_extension

string

exampleSuite 2416

Specific identifier of the house needed depending on the property type. For example, number of apartment in an apartment building.

birthdate

string

example1978-08-22

The birthdate of the customer, in ISO 8601 calendar date format (YYYY-MM-DD).

roaming

object

[DEVELOPER PREVIEW FEATURE] Request the roaming insight. This field must always be set to an empty object {}.

reachability

object

[DEVELOPER PREVIEW FEATURE] Request the reachability insight. This field must always be set to an empty object {}.

Example Request

{
   "phone_number": "14040000000",
   "purpose": "FraudPreventionAndDetection",
   "insights": {
      "format": {},
      "sim_swap": {
         "period": 240
      },
      "original_carrier": {},
      "current_carrier": {},
      "location_verification": {
         "location": {
            "type": "CIRCLE",
            "radius": 3000,
            "center": {
               "latitude": -90,
               "longitude": -180
            }
         }
      },
      "subscriber_match": {
         "id_document": "66666666q",
         "given_name": "Federica",
         "family_name": "Sanchez Arjona",
         "street_name": "Crawfords Corner Road",
         "street_number": "4",
         "postal_code": "07733",
         "locality": "Holmdel",
         "region": "Monmouth County",
         "country": "US",
         "house_number_extension": "Suite 2416",
         "birthdate": "1978-08-22"
      },
      "roaming": {},
      "reachability": {}
   }
}

{
   "phone_number": "14040000000",
   "purpose": "FraudPreventionAndDetection",
   "insights": {
      "format": {},
      "sim_swap": {
         "period": 240
      },
      "original_carrier": {},
      "current_carrier": {},
      "location_verification": {
         "location": {
            "type": "CIRCLE",
            "radius": 3000,
            "center": {
               "latitude": -90,
               "longitude": -180
            }
         }
      },
      "subscriber_match": {
         "id_document": "66666666q",
         "given_name": "Federica",
         "family_name": "Sanchez Arjona",
         "street_name": "Crawfords Corner Road",
         "street_number": "4",
         "postal_code": "07733",
         "locality": "Holmdel",
         "region": "Monmouth County",
         "country": "US",
         "house_number_extension": "Suite 2416",
         "birthdate": "1978-08-22"
      },
      "roaming": {},
      "reachability": {}
   }
}

Responses
Content Type
application/json

request_id

string

exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The unique identifier for your request. This is a alphanumeric string up to 40 characters.

insights

object

A map of objects representing the requested insight(s), where each key corresponds to the name of the insight and the value contains the result and status of that insight.

format

object

Validates the format of a phone number and provides information based on that format.

country_code

string

exampleUS

Two character country code for phone_number. This is in ISO 3166-1 alpha-2 format.

country_name

string

exampleUnited States

The full name of the country where the phone_number is registered.

country_prefix

string

example1

The numeric prefix for the country where the phone_number is registered.

offline_location

string

exampleGeorgia

The location where the number was originally assigned, based on its prefix. This does not represent the real-time location of the device. The value indicates the country of origin or, when available, the specific geographical area associated with the number. Only landline and mobile numbers are eligible for offline location data.

time_zones

array

List of time zones corresponding to the format.offline_location field, or a single-element list with the default "unknown" time zone if no other time zone was found or if the number is invalid. Time zone values follow the tz database identifiers.

number_international

string

example+14040000000

The phone_number from your request, formatted in international E.164 format.

number_national

string

example(404) 000-0000

The phone_number from your request, formatted according to the local convention of the country it belongs to.

is_format_valid

boolean

exampletrue

Phone number format validation involves verifying the length and prefix details at various levels to ensure accuracy and compliance with global numbering standards. A valid format means the number can be legitimately assigned by carriers to users. However, it does not guarantee that the number is currently assigned to a carrier or that it is reachable.

status

object

Code indicating the status of the request.

code

string

exampleOK

Code indicating the status of the request.

Must be one of:NO_COVERAGEINVALID_PURPOSEUNAUTHORIZEDINTERNAL_ERRORSUPPLIER_ERRORNOT_FOUNDINVALID_NUMBER_FORMATPARTIAL_SUCCESSOK

message

string

exampleSuccess

More detailed status description.

sim_swap

object

Information about any recent SIM pairing changes related to a mobile account. A recent SIM swap may indicate a potential risk of account takeover.

latest_sim_swap_at

string(date-time)

example2024-07-08T09:30:27.504Z

Date and time in UTC ISO 8601 of latest SIM swap performed.

is_swapped

boolean

exampletrue

Indicates whether the SIM card has been swapped during the period.

status

object

Code indicating the status of the request.

code

string

exampleOK

Code indicating the status of the request.

Must be one of:NO_COVERAGEINVALID_PURPOSEUNAUTHORIZEDINTERNAL_ERRORSUPPLIER_ERRORNOT_FOUNDINVALID_NUMBER_FORMATPARTIAL_SUCCESSOK

message

string

exampleSuccess

More detailed status description.

original_carrier

object

Information about the network the number was initially assigned. Information based on the numbering plan prefix.

name

string(string)

exampleOrange Espana, S.A. Unipersonal

The full name of the original carrier associated with that phone_number. This is applicable to mobile numbers only.

network_type

string(enum)

exampleMOBILE

The type of network of the original carrier associated with that phone_number.

Must be one of:MOBILELANDLINETOLLFREEPREMIUMVIRTUAL

country_code

string(string)

exampleES

The country that phone_number is associated with. This is in ISO 3166-1 alpha-2 format.

network_code

string(string)

example21403

Mobile country codes (MCC) + Mobile network codes (MNC). E.212 International mobile subscriber identity.

status

object

Code indicating the status of the request.

code

string

exampleOK

Code indicating the status of the request.

Must be one of:NO_COVERAGEINVALID_PURPOSEUNAUTHORIZEDINTERNAL_ERRORSUPPLIER_ERRORNOT_FOUNDINVALID_NUMBER_FORMATPARTIAL_SUCCESSOK

message

string

exampleSuccess

More detailed status description.

current_carrier

object

Information about the network the number is currently assigned. This is applicable to mobile numbers only.

name

string(string)

exampleOrange Espana, S.A. Unipersonal

The full name of the carrier that phone_number is associated with.

network_type

string(enum)

exampleMOBILE

The type of network that phone_number is associated with.

Must be one of:MOBILE

country_code

string(string)

exampleES

The country that phone_number is associated with. This is in ISO 3166-1 alpha-2 format.

network_code

string(string)

example21403

Mobile country codes (MCC) + Mobile network codes (MNC). E.212 International mobile subscriber identity.

status

object

Code indicating the status of the request.

code

string

exampleOK

Code indicating the status of the request.

Must be one of:NO_COVERAGEINVALID_PURPOSEUNAUTHORIZEDINTERNAL_ERRORSUPPLIER_ERRORNOT_FOUNDINVALID_NUMBER_FORMATPARTIAL_SUCCESSOK

message

string

exampleSuccess

More detailed status description.

location_verification

object

Verify whether the location of certain user device is within the area specified.

is_verified

string(enum)

examplePARTIAL

Result of a verification request:

TRUE: when the network locates the device within the requested area,
FALSE: when the requested area does not match the area where the network locates the device,
UNKNOWN: when the network cannot locate the device,
PARTIAL: when the requested area partially match the area where the network locates the device. A match_rate could be included in the response.

Must be one of:TRUEFALSEUNKNOWNPARTIAL

latest_location_at

string(date-time)

example2024-07-08T09:30:27.504Z

Date and time in UTC ISO 8601 of the last location.

match_rate

integer

Min1

Max99

example85

Estimation of the match rate between the area in the request (R), and area where the network locates the device (N), calculated as the percent value of the intersection of both areas divided by the network area, that is (R ∩ N) / N * 100. Included only if is_verified is PARTIAL.

status

object

Code indicating the status of the request.

code

string

exampleOK

Code indicating the status of the request.

Must be one of:NO_COVERAGEINVALID_PURPOSEUNAUTHORIZEDINTERNAL_ERRORSUPPLIER_ERRORNOT_FOUNDINVALID_NUMBER_FORMATPARTIAL_SUCCESSOK

message

string

exampleSuccess

More detailed status description.

subscriber_match

object

Compare the information associated with a particular mobile phone user with that on file (and verified) by the mobile phone user's Operator in their own KYC records.

id_document_match

string

exampleEXACT

Indicates whether Id number associated to the ID document of the customer matches with the one on the Operator's system.

Must be one of:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLE

given_name_match

string

exampleEXACT

Indicates whether First name/given name of the customer matches with the one on the Operator's system.

Must be one of:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLE

family_name_match

string

exampleEXACT

Indicates whether last name/ family name/ surname of the customer matches with the one on the Operator's system.

Must be one of:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLE

address_match

string

examplePARTIAL

Indicates whether complete address of the customer matches with the one on the Operator's system.

Must be one of:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLE

street_name_match

string

exampleEXACT

Indicates whether the street name of the customer matches with the one on the Operator's system.

Must be one of:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLEINCLUDED_WITH_ADDRESS_MATCH

street_number_match

string

exampleEXACT

Indicates whether the street number of the customer matches with the one on the Operator's system.

Must be one of:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLEINCLUDED_WITH_ADDRESS_MATCH

postal_code_match

string

exampleEXACT

Indicates whether the postal code / zip code of the customer matches with the one on the Operator's system.

Must be one of:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLEINCLUDED_WITH_ADDRESS_MATCH

locality_match

string

exampleEXACT

Indicates whether the locality of the customer's address matches with the one on the Operator's system.

Must be one of:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLEINCLUDED_WITH_ADDRESS_MATCH

region_match

string

exampleEXACT

Indicates whether the region or prefecture of the customer matches with the one on the Operator's system.

Must be one of:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLEINCLUDED_WITH_ADDRESS_MATCH

country_match

string

exampleEXACT

Indicates whether the country of the customer's address matches with the one on the Operator's system.

Must be one of:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLEINCLUDED_WITH_ADDRESS_MATCH

house_number_extension_match

string

exampleLOW

Indicates whether the house number extension of the customer's address with the one on the Operator's system.

Must be one of:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLEINCLUDED_WITH_ADDRESS_MATCH

birthdate_match

string

exampleEXACT

Indicates whether the birthdate of the customer matches with the one on the Operator's system.

Must be one of:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLE

status

object

Code indicating the status of the request.

code

string

exampleOK

Code indicating the status of the request.

Must be one of:NO_COVERAGEINVALID_PURPOSEUNAUTHORIZEDINTERNAL_ERRORSUPPLIER_ERRORNOT_FOUNDINVALID_NUMBER_FORMATPARTIAL_SUCCESSOKSUBSCRIBER_MATCH.ID_DOCUMENT_REQUIREDSUBSCRIBER_MATCH.ID_DOCUMENT_MISMATCHSUBSCRIBER_MATCH.INVALID_PARAM_COMBINATION

message

string

exampleSuccess

More detailed status description.

roaming

object

Check roaming status and country for a given device on a mobile network.

latest_status_at

string(date-time)

example2024-02-20T10:41:38.657Z

Date and time in UTC ISO 8601 of the last time that the associated device roaming status was updated.

is_roaming

boolean

exampletrue

Roaming status. true if roaming.

country_codes

array

An array of country codes in ISO 3166-1 alpha-2 format representing where the phone_number is roaming. The array usually contains one element, but in edge cases where the roaming network is associated with multiple countries, additional country codes are included.

status

object

Code indicating the status of the request.

code

string

exampleOK

Code indicating the status of the request.

Must be one of:NO_COVERAGEINVALID_PURPOSEUNAUTHORIZEDINTERNAL_ERRORSUPPLIER_ERRORNOT_FOUNDINVALID_NUMBER_FORMATPARTIAL_SUCCESSOK

message

string

exampleSuccess

More detailed status description.

reachability

object

Check the connectivity status for a given device, including if it is connected to the newtork for data, SMS, or both.

latest_status_at

string(date-time)

example2024-02-20T10:41:38.657Z

Date and time in UTC ISO 8601 of the last time that the associated device connectivity status was updated.

is_reachable

boolean

exampletrue

Indicates overall device reachability. true if the device is connected to the network.

connectivity

array

Indicates if the device is connected to the network for DATA or SMS usage. Will only be returned if is_reachable is true

Available Values:

DATA,SMS

status

object

Code indicating the status of the request.

code

string

exampleOK

Code indicating the status of the request.

Must be one of:NO_COVERAGEINVALID_PURPOSEUNAUTHORIZEDINTERNAL_ERRORSUPPLIER_ERRORNOT_FOUNDINVALID_NUMBER_FORMATPARTIAL_SUCCESSOK

message

string

exampleSuccess

More detailed status description.

Example Response

{
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "insights": {
      "format": {
         "country_code": "US",
         "country_name": "United States",
         "country_prefix": "1",
         "offline_location": "Georgia",
         "time_zones": [
            "America/New_York"
         ],
         "number_international": "+14040000000",
         "number_national": "(404) 000-0000",
         "is_format_valid": true,
         "status": {
            "code": "OK",
            "message": "Success"
         }
      },
      "sim_swap": {
         "latest_sim_swap_at": "2024-07-08T09:30:27.504Z",
         "is_swapped": true,
         "status": {
            "code": "OK",
            "message": "Success"
         }
      },
      "original_carrier": {
         "name": "Orange Espana, S.A. Unipersonal",
         "network_type": "MOBILE",
         "country_code": "ES",
         "network_code": "21403",
         "status": {
            "code": "OK",
            "message": "Success"
         }
      },
      "current_carrier": {
         "name": "Orange Espana, S.A. Unipersonal",
         "network_type": "MOBILE",
         "country_code": "ES",
         "network_code": "21403",
         "status": {
            "code": "OK",
            "message": "Success"
         }
      },
      "location_verification": {
         "is_verified": "PARTIAL",
         "latest_location_at": "2024-07-08T09:30:27.504Z",
         "match_rate": 85,
         "status": {
            "code": "OK",
            "message": "Success"
         }
      },
      "subscriber_match": {
         "id_document_match": "EXACT",
         "given_name_match": "EXACT",
         "family_name_match": "EXACT",
         "address_match": "PARTIAL",
         "street_name_match": "EXACT",
         "street_number_match": "EXACT",
         "postal_code_match": "EXACT",
         "locality_match": "EXACT",
         "region_match": "EXACT",
         "country_match": "EXACT",
         "house_number_extension_match": "LOW",
         "birthdate_match": "EXACT",
         "status": {
            "code": "OK",
            "message": "Success"
         }
      },
      "roaming": {
         "latest_status_at": "2024-02-20T10:41:38.657Z",
         "is_roaming": true,
         "country_codes": [
            "DE"
         ],
         "status": {
            "code": "OK",
            "message": "Success"
         }
      },
      "reachability": {
         "latest_status_at": "2024-02-20T10:41:38.657Z",
         "is_reachable": true,
         "connectivity": [
            "DATA"
         ],
         "status": {
            "code": "OK",
            "message": "Success"
         }
      }
   }
}

Identity Insights API

Identity Insights

Available Operations

Retrieve identity insights from a phone number

Authentication

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Request Body
Content Type
application/json

Responses
Content Type
application/json