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.

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
example447009000000

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.

Example Request

{  "phone_number": "447009000000",  "purpose": "FraudPreventionAndDetection",  "insights": {  "format": {},  "sim_swap": {  "period": 240  }  } }

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_iso2
string
exampleGB

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

country_code_iso3
string
exampleGBR

Three character country code for phone_number. This is in ISO 3166-1 alpha-3 format.

country_name
string
exampleUnited Kingdom

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

country_prefix
string
example44

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

offline_location
string
exampleTexas

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
example447920000000

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

number_national
string
example07920 000000

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 given to this status.

Must be one of:OKPARTIAL_SUCCESSNO_COVERAGEINVALID_NUMBER_FORMATINVALID_PURPOSENOT_FOUNDUNAUTHORIZEDINTERNAL_ERROR
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 given to this status.

Must be one of:OKPARTIAL_SUCCESSNO_COVERAGEINVALID_NUMBER_FORMATINVALID_PURPOSENOT_FOUNDUNAUTHORIZEDINTERNAL_ERROR
message
string
exampleSuccess

More detailed status description.

Example Response

{  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",  "insights": {  "format": {  "country_code_iso2": "GB",  "country_code_iso3": "GBR",  "country_name": "United Kingdom",  "country_prefix": "44",  "offline_location": "Texas",  "time_zones": [  "America/Chicago"  ],  "number_international": "447920000000",  "number_national": "07920 000000",  "format_valid": true,  "status": {  "code": "OK",  "message": "Success"  }  },  "sim_swap": {  "latest_sim_swap_at": "2024-07-08T09:30:27.504Z",  "swapped": true,  "status": {  "code": "OK",  "message": "Success"  }  }  } }