Format

The Format Insight is a fundamental validation tool that verifies whether a phone number is correctly structured and potentially assignable to a subscriber. It ensures the number complies with international dialing standards, identifies the associated country, and determines the corresponding time zone. This insight does not confirm whether the number is currently active or in use, but it is a crucial first step in assessing the technical validity of any global phone number.

By analyzing the number’s syntax and prefix structure, Format Insight helps identify whether the number belongs to a valid numbering range in a specific country. It also flags obviously invalid or malformed numbers, allowing organizations to cleanse data before using it for operational or marketing purposes.

Integrating the Format insight into your applications can help with a range of scenarios, including:

• Data Quality & Cleansing: Format Insight is ideal for cleaning historical customer databases. It filters out improperly formatted or clearly invalid numbers, helping maintain high data hygiene standards and improving overall contactability.
• Real-Time Validation at Input: Businesses can integrate this insight into web forms or CRM systems to validate phone numbers as they are entered, reducing the risk of input errors and ensuring only properly formatted numbers are stored.
• Segmentation & Localization: Knowing the country and time zone associated with a number enables businesses to tailor their communications, schedule outreach in appropriate time windows, and comply with local regulations.
• Cost Optimization: Avoid engaging with invalid numbers that would otherwise lead to failed delivery attempts, wasted operational effort, and unnecessary costs in SMS, voice, or fraud prevention workflows.

In summary, Format Insight provides a low-latency, high-reliability way to validate global phone numbers at scale. It is a key building block in any phone number intelligence pipeline, laying the groundwork for more advanced checks such as carrier insights and network features for fraud risk analysis.

Prerequisites

To use Identity Insights, you must ensure your account is configured correctly; see the Getting Started guide for more information on:

• Creating your account,
• Creating a Vonage application for use with the Identity Insights API,
• The different environments available and how to configure your account to use them,
• And how to use the Dashboard Getting Started UI to use the API without writing any code.

This guide will explain how to use the Format Insight programatically using cURL.

Making an API Call

Authentication for the Identity Insights API is done via JWTs, a compact and self-contained JSON token. To generate a JWT, you can use our online generator, or alternatively use the Vonage CLI. You will need your application ID and private key to generate the JWT. Once you have your JWT, you can send a request to the API.

This example shows a cURL request for the Format insight to return useful information based on the phone number provided:

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

The API will then validate that the format of the phone number is valid, and return other information such as the country code, time zones, and different formats of that number:

{
  "request_id": "c2cc7a65-9b10-493f-9c0a-1c86751a91c4",
  "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": "NO_COVERAGE",
          "message": "Success"
      }
    }
  }
}

You'll see the following fields in the format array:

Further Reading

• Read more about the Identity Insights API in the API Reference.
• If you have any questions, you can reach out to us on the Vonage Community Slack.