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 The insight was processed successfully.
INVALID_NUMBER_FORMAT The phone number format is not valid for assignment by carriers to users.
UNSUPPORTED_NETWORK_TYPE The network type is not supported for this Insight.
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.

Baixar a especificação OpenAPI

Identity Insights

Provides real-time intelligence about a phone number.

Operações disponíveis

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-{region}.vonage.com/identity-insights/v1/requests

Variáveis do servidor

Variable	Description	Default Value	Options
region	The region where the API request is sent.	eu	eu, us

Autenticação

Chave	Descrição	Onde	Exemplo
Authorization	Seu token JSON da Web. Saiba mais sobre os JWTs	Headers	`Bearer <JWT>`

Corpo da solicitação
Tipo de conteúdo
application/json

phone_number

string(e164)

Obrigatório

exemplo14040000000

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

exemploFraudPreventionAndDetection

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

Obrigatório

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

format

object

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

sim_swap

object

Request the sim_swap insight.

period

integer(int32)

Mín.1

Max2400

Padrão240

exemplo240

Specifies the time window (in hours) used to determine the is_swapped response field.

original_carrier

object

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

current_carrier

object

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

location_verification

object

Developer Preview

Request the location_verification insight.

location

object

type

string

exemploCIRCLE

Type of area.

Deve ser uma das seguintes opções:CIRCLE

radius

integer(int32)

Mín.2000

Max200000

exemplo3000

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

center

object

Geographic center point defined by latitude and longitude coordinates.

latitude

number

Mín.-90

Max90

exemplo52.52

Latitude in decimal degrees (WGS 84).

longitude

number

Mín.-180

Max180

exemplo13.405

Longitude in decimal degrees (WGS 84).

subscriber_match

object

Beta

Request the subscriber_match insight.

id_document

string

exemplo66666666q

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

given_name

string

exemploFederica

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

family_name

string

exemploSanchez Arjona

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

street_name

string

exemploCrawfords Corner Road

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

street_number

string

exemplo4

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

postal_code

string

exemplo07733

Zip code or postal code

locality

string

exemploHolmdel

Locality of the customer's address

region

string

exemploMonmouth County

Region or prefecture of the customer's address

country

string

exemploUS

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

house_number_extension

string

exemploSuite 2416

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

birthdate

string

exemplo1978-08-22

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

roaming

object

Developer Preview

Request the roaming insight. This field must always be set to an empty object {}.

reachability

object

Developer Preview

Request the reachability insight. This field must always be set to an empty object {}.

device_swap

object

Request the device_swap insight.

period

integer(int32)

Mín.1

Max2400

Padrão240

exemplo240

Specifies the time window (in hours) used to determine the is_swapped response field.

Exemplo Solicitação

{
   "phone_number": "14040000000",
   "purpose": "FraudPreventionAndDetection",
   "insights": {
      "format": {},
      "sim_swap": {
         "period": 240
      },
      "original_carrier": {},
      "current_carrier": {},
      "location_verification": {
         "location": {
            "type": "CIRCLE",
            "radius": 3000,
            "center": {
               "latitude": 52.52,
               "longitude": 13.405
            }
         }
      },
      "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": {},
      "device_swap": {
         "period": 240
      }
   }
}

Respostas
Tipo de conteúdo
application/json

request_id

string(uuid)

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

exemploUS

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

country_name

string

exemploUnited States

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

country_prefix

string

exemplo1

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

offline_location

string

exemploGeorgia

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

exemplo+14040000000

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

number_national

string

exemplo(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

exemplotrue

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

Indicates the status of the information returned for the specified phone number.

code

string(enum)

exemploOK

Code indicating the status of the request. This enum is extensible; clients must handle unknown values.

Deve ser uma das seguintes opções:NO_COVERAGEINVALID_PURPOSEUNAUTHORIZEDINTERNAL_ERRORSUPPLIER_ERRORNOT_FOUNDUNSUPPORTED_NETWORK_TYPEINVALID_NUMBER_FORMATOK

message

string

exemploSuccess

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)

exemplo2024-07-08T09:30:27.504Z

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

is_swapped

boolean

exemplotrue

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

status

object

Indicates the status of the information returned for the specified phone number.

code

string(enum)

exemploOK

Code indicating the status of the request. This enum is extensible; clients must handle unknown values.

Deve ser uma das seguintes opções:NO_COVERAGEINVALID_PURPOSEUNAUTHORIZEDINTERNAL_ERRORSUPPLIER_ERRORNOT_FOUNDUNSUPPORTED_NETWORK_TYPEINVALID_NUMBER_FORMATOK

message

string

exemploSuccess

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)

exemploOrange 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)

exemploMOBILE

The type of network of the original carrier associated with that phone_number. This enum is extensible; clients must handle unknown values.

Deve ser uma das seguintes opções:MOBILELANDLINETOLLFREEPREMIUMVIRTUAL

country_code

string(string)

exemploES

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

network_code

string(string)

exemplo21403

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

status

object

Indicates the status of the information returned for the specified phone number.

code

string(enum)

exemploOK

Code indicating the status of the request. This enum is extensible; clients must handle unknown values.

Deve ser uma das seguintes opções:NO_COVERAGEINVALID_PURPOSEUNAUTHORIZEDINTERNAL_ERRORSUPPLIER_ERRORNOT_FOUNDUNSUPPORTED_NETWORK_TYPEINVALID_NUMBER_FORMATOK

message

string

exemploSuccess

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)

exemploOrange Espana, S.A. Unipersonal

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

network_type

string(enum)

exemploMOBILE

The type of network that phone_number is associated with. This enum is extensible; clients must handle unknown values.

Deve ser uma das seguintes opções:MOBILE

country_code

string(string)

exemploES

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

network_code

string(string)

exemplo21403

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

status

object

Indicates the status of the information returned for the specified phone number.

code

string(enum)

exemploOK

Code indicating the status of the request. This enum is extensible; clients must handle unknown values.

Deve ser uma das seguintes opções:NO_COVERAGEINVALID_PURPOSEUNAUTHORIZEDINTERNAL_ERRORSUPPLIER_ERRORNOT_FOUNDUNSUPPORTED_NETWORK_TYPEINVALID_NUMBER_FORMATOK

message

string

exemploSuccess

More detailed status description.

location_verification

object

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

is_verified

string(enum)

exemploPARTIAL

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.

Deve ser uma das seguintes opções:TRUEFALSEUNKNOWNPARTIAL

latest_location_at

string(date-time)

exemplo2024-07-08T09:30:27.504Z

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

match_rate

integer

Mín.1

Max99

exemplo85

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

Indicates the status of the information returned for the specified phone number.

code

string(enum)

exemploOK

Code indicating the status of the request. This enum is extensible; clients must handle unknown values.

Deve ser uma das seguintes opções:NO_COVERAGEINVALID_PURPOSEUNAUTHORIZEDINTERNAL_ERRORSUPPLIER_ERRORNOT_FOUNDUNSUPPORTED_NETWORK_TYPEINVALID_NUMBER_FORMATOK

message

string

exemploSuccess

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 and trusted third-party data sources.

id_document_match

string

exemploEXACT

Indicates whether Id number associated to the ID document of the customer matches with the one on the Operator's system. This enum is extensible; clients must handle unknown values.

Deve ser uma das seguintes opções:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLE

given_name_match

string

exemploEXACT

Indicates whether First name/given name of the customer matches with the one on the Operator's system. This enum is extensible; clients must handle unknown values.

Deve ser uma das seguintes opções:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLE

family_name_match

string

exemploEXACT

Indicates whether last name/ family name/ surname of the customer matches with the one on the Operator's system. This enum is extensible; clients must handle unknown values.

Deve ser uma das seguintes opções:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLE

address_match

string

exemploPARTIAL

Indicates whether complete address of the customer matches with the one on the Operator's system. This enum is extensible; clients must handle unknown values.

Deve ser uma das seguintes opções:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLE

street_name_match

string

exemploEXACT

Indicates whether the street name of the customer matches with the one on the Operator's system. This enum is extensible; clients must handle unknown values.

Deve ser uma das seguintes opções:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLEINCLUDED_WITH_ADDRESS_MATCH

street_number_match

string

exemploEXACT

Indicates whether the street number of the customer matches with the one on the Operator's system. This enum is extensible; clients must handle unknown values.

Deve ser uma das seguintes opções:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLEINCLUDED_WITH_ADDRESS_MATCH

postal_code_match

string

exemploEXACT

Indicates whether the postal code / zip code of the customer matches with the one on the Operator's system. This enum is extensible; clients must handle unknown values.

Deve ser uma das seguintes opções:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLEINCLUDED_WITH_ADDRESS_MATCH

locality_match

string

exemploEXACT

Indicates whether the locality of the customer's address matches with the one on the Operator's system. This enum is extensible; clients must handle unknown values.

Deve ser uma das seguintes opções:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLEINCLUDED_WITH_ADDRESS_MATCH

region_match

string

exemploEXACT

Indicates whether the region or prefecture of the customer matches with the one on the Operator's system. This enum is extensible; clients must handle unknown values.

Deve ser uma das seguintes opções:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLEINCLUDED_WITH_ADDRESS_MATCH

country_match

string

exemploEXACT

Indicates whether the country of the customer's address matches with the one on the Operator's system. This enum is extensible; clients must handle unknown values.

Deve ser uma das seguintes opções:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLEINCLUDED_WITH_ADDRESS_MATCH

house_number_extension_match

string

exemploLOW

Indicates whether the house number extension of the customer's address with the one on the Operator's system. This enum is extensible; clients must handle unknown values.

Deve ser uma das seguintes opções:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLEINCLUDED_WITH_ADDRESS_MATCH

birthdate_match

string

exemploEXACT

Indicates whether the birthdate of the customer matches with the one on the Operator's system. This enum is extensible; clients must handle unknown values.

Deve ser uma das seguintes opções:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLE

status

object

Indicates the status of the information returned for the specified phone number.

code

string(enum)

exemploOK

Code indicating the status of the request. This enum is extensible; clients must handle unknown values.

Deve ser uma das seguintes opções:NO_COVERAGEINVALID_PURPOSEUNAUTHORIZEDINTERNAL_ERRORSUPPLIER_ERRORNOT_FOUNDUNSUPPORTED_NETWORK_TYPEINVALID_NUMBER_FORMATOKSUBSCRIBER_MATCH.ID_DOCUMENT_REQUIREDSUBSCRIBER_MATCH.ID_DOCUMENT_MISMATCHSUBSCRIBER_MATCH.INVALID_PARAM_COMBINATION

message

string

exemploSuccess

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)

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

exemplotrue

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

Indicates the status of the information returned for the specified phone number.

code

string(enum)

exemploOK

Code indicating the status of the request. This enum is extensible; clients must handle unknown values.

Deve ser uma das seguintes opções:NO_COVERAGEINVALID_PURPOSEUNAUTHORIZEDINTERNAL_ERRORSUPPLIER_ERRORNOT_FOUNDUNSUPPORTED_NETWORK_TYPEINVALID_NUMBER_FORMATOK

message

string

exemploSuccess

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)

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

exemplotrue

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. This enum is extensible; clients must handle unknown values.

Valores disponíveis:

DATA,SMS

status

object

Indicates the status of the information returned for the specified phone number.

code

string(enum)

exemploOK

Code indicating the status of the request. This enum is extensible; clients must handle unknown values.

Deve ser uma das seguintes opções:NO_COVERAGEINVALID_PURPOSEUNAUTHORIZEDINTERNAL_ERRORSUPPLIER_ERRORNOT_FOUNDUNSUPPORTED_NETWORK_TYPEINVALID_NUMBER_FORMATOK

message

string

exemploSuccess

More detailed status description.

device_swap

object

Information about any recent physical device change for a mobile phone number. A recent device swap may indicate a potential risk of account takeover.

latest_device_swap_at

string(date-time)

exemplo2024-07-08T09:30:27.504Z

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

is_swapped

boolean

exemplotrue

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

status

object

Indicates the status of the information returned for the specified phone number.

code

string(enum)

exemploOK

Code indicating the status of the request. This enum is extensible; clients must handle unknown values.

Deve ser uma das seguintes opções:NO_COVERAGEINVALID_PURPOSEUNAUTHORIZEDINTERNAL_ERRORSUPPLIER_ERRORNOT_FOUNDUNSUPPORTED_NETWORK_TYPEINVALID_NUMBER_FORMATOK

message

string

exemploSuccess

More detailed status description.

Exemplo Resposta

{
   "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"
         }
      },
      "device_swap": {
         "latest_device_swap_at": "2024-07-08T09:30:27.504Z",
         "is_swapped": true,
         "status": {
            "code": "OK",
            "message": "Success"
         }
      }
   }
}

Identity Insights API

Identity Insights

Operações disponíveis

Retrieve identity insights from a phone number

Variáveis do servidor

Autenticação

Corpo da solicitação Tipo de conteúdoapplication/json

Exemplo Solicitação

Respostas Tipo de conteúdoapplication/json

Exemplo Resposta

Corpo da solicitação
Tipo de conteúdo
application/json

Respostas
Tipo de conteúdo
application/json