Vonage Network Number Verification

Common errors

• ImportError: cannot import name 'Client' from 'vonage.number_verification'

  cause The `vonage-network-number-verification` client is a separate package and not a sub-module of the main `vonage` SDK. You are trying to import it from the wrong path.
  fix Install `vonage-network-number-verification` (`pip install vonage-network-number-verification`) and import its `Client` class directly: `from vonage_network_number_verification import Client`.

• ModuleNotFoundError: No module named 'vonage_network_number_verification'

  cause The `vonage-network-number-verification` package is not installed in your current Python environment.
  fix Install the package using pip: `pip install vonage-network-number-verification`.

• TypeError: Client.__init__ missing 1 required positional argument: 'vonage_client'

  cause The `NumberVerificationClient` from `vonage-network-number-verification` expects an initialized `vonage.Client` instance to be passed during its creation.
  fix First, create a `vonage.Client` instance with your API key and secret, then pass it to the `NumberVerificationClient`: `from vonage import Client as VonageCoreClient; vonage_client = VonageCoreClient(key='YOUR_API_KEY', secret='YOUR_API_SECRET'); nv_client = NumberVerificationClient(vonage_client=vonage_client)`.

• vonage.exceptions.VonageServerException: Request Failed: Bad credentials

  cause The API key or secret used to initialize the underlying `vonage.Client` are incorrect, expired, or do not have the necessary permissions to access the Number Verification Network API.
  fix Double-check your Vonage API Key and Secret in your Vonage dashboard. Ensure they are correctly configured in your code (e.g., environment variables) and that your account has access to the Number Verification Network API.

Warnings

• breaking This package relies on `vonage >= 4.0.0, < 5.0.0`. If the main `vonage` SDK is updated to a `5.x.x` version (or newer major version), this package may become incompatible or break due to API changes in the underlying dependency.
  Fix: Before upgrading the main `vonage` SDK to a new major version, check for a compatible `vonage-network-number-verification` release or consult the official documentation for compatibility notes.
• gotcha Do not confuse `vonage-network-number-verification` with `vonage-number-insight`. They are distinct Vonage APIs serving different purposes. Number Insight provides general information about a number (carrier, type, roaming status), while Network Number Verification provides network-level checks like number reachability and porting status.
  Fix: Ensure you are using the correct API for your specific use case. If you need general number data, use `vonage-number-insight`. For network status, use `vonage-network-number-verification`.
• gotcha The `vonage-network-number-verification` client requires an initialized `vonage.Client` instance, which primarily uses API Key and Secret for authentication. This differs from some other Vonage APIs (e.g., Voice, Video) that frequently use JWT authentication.
  Fix: Always initialize the core `vonage.Client` with `key` and `secret` parameters when creating an instance for `vonage-network-number-verification`. Ensure these credentials have the necessary permissions for the Number Verification Network API.

Install

• pip install vonage-network-number-verification Install latest version

Imports

• Client
  wrong:

  from vonage.number_verification import Client

  correct:

  from vonage_network_number_verification import Client

  This client is a standalone package, not a sub-module of the main `vonage` SDK.
• VerifyNumberRequest

  from vonage_network_number_verification.models import VerifyNumberRequest

Quickstart

This quickstart demonstrates how to initialize the Vonage Network Number Verification client and make a request to verify a phone number. It requires your Vonage API Key and Secret, which are used to initialize the underlying `vonage.Client` instance. The response contains various network-level details about the number.

import os
from vonage import Client as VonageCoreClient
from vonage_network_number_verification import Client as NumberVerificationClient
from vonage_network_number_verification.models import VerifyNumberRequest

# Your Vonage API key and secret
VONAGE_API_KEY = os.environ.get("VONAGE_API_KEY", "YOUR_API_KEY")
VONAGE_API_SECRET = os.environ.get("VONAGE_API_SECRET", "YOUR_API_SECRET")

# Initialize the core Vonage client (required by the number verification client)
vonage_client = VonageCoreClient(key=VONAGE_API_KEY, secret=VONAGE_API_SECRET)

# Initialize the Network Number Verification client
nv_client = NumberVerificationClient(vonage_client=vonage_client)

# Define the request to verify a number
request_body = VerifyNumberRequest(
    type="phone", # Required: 'phone'
    number="447700900000" # Required: The phone number to verify
)

try:
    # Make the API call
    response = nv_client.post_verify_number(request_body)

    # Print the raw response for inspection
    print(f"\nNetwork Number Verification Response:\n{response.model_dump_json(indent=2)}")

    # Access specific fields
    if response.request_id:
        print(f"\nRequest ID: {response.request_id}")
    if response.port_id_check_status:
        print(f"Port ID Check Status: {response.port_id_check_status}")
    if response.reachability_status:
        print(f"Reachability Status: {response.reachability_status}")

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