Vonage Number Insight

1.0.7 · maintenance · verified Thu Apr 16

The `vonage-number-insight` package provides Python access to Vonage's Number Insight API, allowing users to retrieve real-time intelligence about phone numbers at basic, standard, and advanced levels. While currently functional, the Vonage Number Insight API is scheduled for sunset on February 4, 2027, with migration encouraged to the Vonage Identity Insights API. The library's current version is 1.0.7 and it's typically updated in conjunction with the main Vonage Python SDK.

Common errors

```
AuthenticationError: 'Signature verification failed' or 'API Key / Secret is invalid'
```
cause The provided Vonage API Key or API Secret is incorrect, or environment variables are not loaded.

fix Verify your `VONAGE_API_KEY` and `VONAGE_API_SECRET` credentials from your Vonage dashboard. Ensure they are correctly set as environment variables or passed directly to the `Vonage` client constructor.
```
AttributeError: 'VonageClient' object has no attribute 'number_insight'
```
cause The `vonage-number-insight` package is not installed, or the `vonage` SDK is an outdated version that doesn't correctly integrate the number insight methods.

fix Ensure both `vonage` and `vonage-number-insight` packages are installed and up-to-date (`pip install --upgrade vonage vonage-number-insight`). The Number Insight API methods are accessed via `client.number_insight.<method_name>`.
```
requests.exceptions.Timeout: The read operation timed out
```
cause Attempting a synchronous Advanced Number Insight request, which can exceed typical API timeouts due to extensive data processing.

fix Switch to asynchronous Advanced Number Insight requests by using `AdvancedAsyncInsightRequest` and providing a `callback` URL to receive the results.

Warnings

breaking The Vonage Number Insight API, which this library integrates with, is being sunset on February 4, 2027. Users are strongly encouraged to migrate to the Vonage Identity Insights API for continued support and enhanced functionality.
Fix: Review the Vonage Number Insights Transition Guide and migrate to the Vonage Identity Insights API. This will likely involve using a different library or a different part of the main `vonage` SDK.
gotcha For Advanced Number Insight requests, Vonage strongly recommends using the asynchronous API via webhooks to avoid potential timeouts due to the comprehensive data retrieval. Synchronous Advanced Insight can be slow.
Fix: Implement webhook handlers and use `AdvancedAsyncInsightRequest` with a `callback` URL when performing advanced number insight lookups.
gotcha Caller Name (CNAM) lookup is an optional feature for Standard and Advanced Number Insight and incurs an additional charge. It is only available for US numbers, and not all US numbers are supported.
Fix: Set the `cnam=True` parameter in `StandardInsightRequest` or `AdvancedInsightRequest` only when explicitly needed for US numbers, and be aware of potential extra costs and limitations.
gotcha Phone numbers for insight requests should be in national or international format. If the number does not include a country code or its country is uncertain, you must provide a two-character ISO 3166-1 alpha-2 country code (e.g., 'GB' or 'US').
Fix: Ensure numbers are correctly formatted or provide the `country` parameter in the request object (e.g., `BasicInsightRequest(number='79111234567', country='GB')`).

Install

pip install vonage-number-insight vonage Install Number Insight and core Vonage SDK

Imports

Vonage
```
from vonage import Vonage
```
The core client for authenticating and interacting with Vonage APIs.
BasicInsightRequest
wrong:
```
from vonage.number_insight import BasicInsightRequest
```
correct:
```
from vonage_number_insight import BasicInsightRequest
```
Request models for Number Insight are imported directly from `vonage_number_insight`, not from a submodule of `vonage`.
StandardInsightRequest
```
from vonage_number_insight import StandardInsightRequest
```
Request model for standard Number Insight requests.
AdvancedAsyncInsightRequest
```
from vonage_number_insight import AdvancedAsyncInsightRequest
```
Request model for asynchronous advanced Number Insight requests.

Quickstart

This quickstart demonstrates how to perform a basic Number Insight request. It initializes the Vonage client using API credentials, ideally sourced from environment variables, and then calls the `basic_number_insight` method with a `BasicInsightRequest` object. The response is printed in JSON format. For advanced insights, asynchronous requests via webhooks are recommended.

import os
from vonage import Vonage
from vonage_number_insight import BasicInsightRequest

# Set environment variables: VONAGE_API_KEY, VONAGE_API_SECRET
API_KEY = os.environ.get('VONAGE_API_KEY', 'YOUR_API_KEY')
API_SECRET = os.environ.get('VONAGE_API_SECRET', 'YOUR_API_SECRET')
PHONE_NUMBER = '12345678900' # Replace with a valid phone number

if not API_KEY or not API_SECRET:
    print("Error: VONAGE_API_KEY and VONAGE_API_SECRET environment variables must be set.")
else:
    try:
        client = Vonage(key=API_KEY, secret=API_SECRET)
        
        # Make a Basic Number Insight Request
        request = BasicInsightRequest(number=PHONE_NUMBER)
        response = client.number_insight.basic_number_insight(request)
        
        print(f"Basic Number Insight for {PHONE_NUMBER}:")
        print(response.model_dump_json(indent=2, exclude_none=True))

    except Exception as e:
        print(f"An error occurred: {e}")

view raw JSON →