Number Insights Transition Guide

As the Vonage Number Insights API has evolved, its capabilities for phone number intelligence have been consolidated into the newer Identity Insights API, offering greater flexibility, combined insights in a single request, and modern support for real-time carrier data and fraud prevention features.

As part of this consolidation, the Number Insights API will effectively sunset in February 2027. After this date, Number Insights will be deprecated. To avoid service disruption and to benefit from unified insights, new network features like SIM Swap and Subscriber Match, and ongoing enhancements, customers are strongly encouraged to migrate their existing Number Insights integrations to Identity Insights ahead of this deadline.

This guide helps you migrate your existing implementations that use these Number Insights services to the equivalent Identity Insights requests:

Number Insights Basic
Number Insights Standard
Number Insights Advanced

Common Concepts

The table below shows how the legacy Number Insights endpoints / attributes align with Identity Insights:

Legacy Number Insights	Identity Insights Equivalent
Basic: number formatting	Format
Standard/Advanced: `original_carrier`	Original Carrier insight
Standard/Advanced: `current_carrier`	Current Carrier insight

These are explained in further detail below.

Phone Number Format

In Number Insights, the Basic endpoint provided formatted representations of phone numbers (national and international), and basic validation.

In Identity Insights, this is supported by the Format insight, returning number formatting and validation details within a structured model.

Original Carrier

Legacy Standard and Advanced Number Insights returned an original_carrier object containing carrier details reflecting the network to which the number was initially assigned.

Identity Insights maintains this capability under its Original Carrier insight with similar fields such as name, country, network type, and identifiers.

Current Carrier

Number Insights exposed a current_carrier object indicating the carrier to which a mobile number is currently associated (including number portability where supported).

Identity Insights continues with its Current Carrier insight, reflecting live assignment for mobile numbers.

Roaming and reachability

Number Insights Advanced exposed roaming and reachability information. These fields were derived from HLR (Home Location Register) based lookups, a legacy approach that is increasingly constrained by privacy regulations and technical limitations across the industry, making this data source unreliable.

Identity Insights moves away from HLR-based data sources and instead relies on Network APIs, which provide more reliable and real-time information by querying mobile networks directly. However, availability and geographic coverage for these Network API–backed insights are currently limited, and they are only exposed through Vonage Virtual Operator.

In Identity Insights, these capabilities are provided through the Roaming and Reachability insights.

Error Handling

How Error Handling Worked in Number Insights

In legacy Number Insights (Basic, Standard, Advanced), error handling was normally request-level:

The HTTP status code reflected the overall success or failure of the request.
If the request succeeded (for example, HTTP 200), the request itself was considered successful and processing was completed, although some individual fields might still be missing depending on number type, coverage, or data availability.
If the request failed, no partial data was returned.
Errors were communicated via top-level fields such as status, status_message, or HTTP error responses.

This model assumed all-or-nothing execution.

How Error Handling Works in Identity Insights

Identity Insights introduces a multi-status response model.

Each requested insight (for example format, original_carrier, current_carrier) is processed independently and returns its own status information.

As a result:

The HTTP response can succeed (e.g. HTTP 200) even if one or more insights failed.
Some insights may return valid data while others return errors
Applications must inspect the status of each insight individually.

Identity Insights: Making the API Call

Identity Insights allows you to request multiple insights in one payload. Here’s an example that replaces legacy Number Insight API request for Basic, Standard and Advanced requests:

curl -X POST https://api-eu.vonage.com/identity-insights/v1/requests \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "14040000000",
    "purpose": "FraudPreventionAndDetection",
    "insights": {
      "format": {},
      "original_carrier": {},
      "current_carrier": {}
    }
  }'

Note: You must use a JWT authorization token for Identity Insights calls, not the api_key/api_secret style used by legacy Number Insight API. For more information on JWTs, see the Authentication guide.

Response Structure

A typical Identity Insights response includes attributes for each enabled insight. For example:

{
   "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"
         }
      },
      "original_carrier": {
            "name": "AT&T Mobility",
            "network_type": "MOBILE",
            "country_code": "US",
            "network_code": "310090",
            "status": {
                "code": "OK",
                "message": "Success"
            }
        },
"current_carrier": {
            "name": "AT&T Mobility",
            "network_type": "MOBILE",
            "country_code": "US",
            "network_code": "310090",
            "status": {
                "code": "OK",
                "message": "Success"
            }
        },
   }
}

Fields match legacy semantics but are returned under a single JSON structure, simplifying your parsing.

Summary Checklist

When migrating:

Replace legacy Basic / Standard / Advanced Number Insights calls with a single Identity Insights call.
Include the format insight for number formatting and validation.
Include both original_carrier and current_carrier insight objects to preserve legacy carrier data semantics.
Update your authorization to use JWT.