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:

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

Identity Insights

Provides real-time intelligence about a phone number.

Available Operations

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

KeyDescriptionWhereExample
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

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

sim_swap

[ALPHA 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

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

current_carrier
object

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

location_verification
object

[ALPHA FEATURE] Request the location_verification insight.

location
object
type
string
Must be one of:CIRCLE
radius
integer(int32)
Min2000
Max20000000
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
id_document
string
example66666666q

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

name
string
exampleFederica Sanchez Arjona

Complete name of the customer, usually composed of first/given name and last/family/sur- name in a country. Depending on the country, the order of first/give name and last/family/sur- name varies, and middle name could be included. It can use givenName, middleNames, familyName and/or familyNameAtBirth. For example, in ESP, name+familyName; in NLD, it can be name+middleNames+familyName or name+middleNames+familyNameAtBirth, etc.

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.

address
string
example101 Crawfords Corner Road Ste 2416

Complete address of the customer. For some countries, it is built following the usual concatenation of parameters in a country, but for other countries, this is not the case. For some countries, it can use streetName, streetNumber and/or houseNumberExtension. For example, in ESP, streetName+streetNumber; in NLD, it can be streetName+streetNumber or streetName+streetNumber+houseNumberExtension.

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

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(date)
example{}

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

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",
         "name": "Federica Sanchez Arjona",
         "given_name": "Federica",
         "family_name": "Sanchez Arjona",
         "address": "101 Crawfords Corner Road Ste 2416",
         "street_name": "Crawfords Corner Road",
         "street_number": "4",
         "postal_code": "07733",
         "locality": "Holmdel",
         "country": "US",
         "house_number_extension": "Suite 2416",
         "birthdate": {}
      }
   }
}

Responses
Content Type
application/json

OK

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.

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

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

code
string

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.

swapped
boolean

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

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

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

code
string

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

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

code
string

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.

verified
string(enum)

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

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 verified is PARTIAL.

status
object

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

code
string

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

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
name_match
string

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

Must be one of:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLE
given_name_match
string

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

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

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

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

Must be one of:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLE
street_number_match
string

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

Must be one of:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLE
postal_code_match
string

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

Must be one of:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLE
locality_match
string

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

Must be one of:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLE
country_match
string

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

Must be one of:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLE
house_number_extension_match
string

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

Must be one of:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLE
birthdate_match
string

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

Must be one of:EXACTHIGHPARTIALLOWNONEDATA_UNAVAILABLE
status
object

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

code
string

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",
         "format_valid": true,
         "status": {
            "code": "NO_COVERAGE",
            "message": "Success"
         }
      },
      "sim_swap": {
         "latest_sim_swap_at": "2024-07-08T09:30:27.504Z",
         "swapped": true,
         "status": {
            "code": "NO_COVERAGE",
            "message": "Success"
         }
      },
      "original_carrier": {
         "name": "Orange Espana, S.A. Unipersonal",
         "network_type": "MOBILE",
         "country_code": "ES",
         "network_code": "21403",
         "status": {
            "code": "NO_COVERAGE",
            "message": "Success"
         }
      },
      "current_carrier": {
         "name": "Orange Espana, S.A. Unipersonal",
         "network_type": "MOBILE",
         "country_code": "ES",
         "network_code": "21403",
         "status": {
            "code": "NO_COVERAGE",
            "message": "Success"
         }
      },
      "location_verification": {
         "verified": "TRUE",
         "latest_location_at": "2024-07-08T09:30:27.504Z",
         "match_rate": 1,
         "status": {
            "code": "NO_COVERAGE",
            "message": "Success"
         }
      },
      "subscriber_match": {
         "id_document_match": "EXACT",
         "name_match": "EXACT",
         "given_name_match": "EXACT",
         "family_name_match": "EXACT",
         "address_match": "EXACT",
         "street_name_match": "EXACT",
         "street_number_match": "EXACT",
         "postal_code_match": "EXACT",
         "locality_match": "EXACT",
         "country_match": "EXACT",
         "house_number_extension_match": "EXACT",
         "birthdate_match": "EXACT",
         "status": {
            "code": "NO_COVERAGE",
            "message": "Success"
         }
      }
   }
}