{"id":9397,"library":"vonage-number-insight","title":"Vonage Number Insight","description":"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.","status":"maintenance","version":"1.0.7","language":"en","source_language":"en","source_url":"https://github.com/Vonage/vonage-python-sdk","tags":["vonage","api","telecom","number-insight","phone-number","validation","deprecated"],"install":[{"cmd":"pip install vonage-number-insight vonage","lang":"bash","label":"Install Number Insight and core Vonage SDK"}],"dependencies":[{"reason":"The `vonage-number-insight` package is designed to be used as part of the main `vonage` Python SDK, which provides the core client object for API interactions.","package":"vonage"}],"imports":[{"note":"The core client for authenticating and interacting with Vonage APIs.","symbol":"Vonage","correct":"from vonage import Vonage"},{"note":"Request models for Number Insight are imported directly from `vonage_number_insight`, not from a submodule of `vonage`.","wrong":"from vonage.number_insight import BasicInsightRequest","symbol":"BasicInsightRequest","correct":"from vonage_number_insight import BasicInsightRequest"},{"note":"Request model for standard Number Insight requests.","symbol":"StandardInsightRequest","correct":"from vonage_number_insight import StandardInsightRequest"},{"note":"Request model for asynchronous advanced Number Insight requests.","symbol":"AdvancedAsyncInsightRequest","correct":"from vonage_number_insight import AdvancedAsyncInsightRequest"}],"quickstart":{"code":"import os\nfrom vonage import Vonage\nfrom vonage_number_insight import BasicInsightRequest\n\n# Set environment variables: VONAGE_API_KEY, VONAGE_API_SECRET\nAPI_KEY = os.environ.get('VONAGE_API_KEY', 'YOUR_API_KEY')\nAPI_SECRET = os.environ.get('VONAGE_API_SECRET', 'YOUR_API_SECRET')\nPHONE_NUMBER = '12345678900' # Replace with a valid phone number\n\nif not API_KEY or not API_SECRET:\n    print(\"Error: VONAGE_API_KEY and VONAGE_API_SECRET environment variables must be set.\")\nelse:\n    try:\n        client = Vonage(key=API_KEY, secret=API_SECRET)\n        \n        # Make a Basic Number Insight Request\n        request = BasicInsightRequest(number=PHONE_NUMBER)\n        response = client.number_insight.basic_number_insight(request)\n        \n        print(f\"Basic Number Insight for {PHONE_NUMBER}:\")\n        print(response.model_dump_json(indent=2, exclude_none=True))\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"fix":"Implement webhook handlers and use `AdvancedAsyncInsightRequest` with a `callback` URL when performing advanced number insight lookups.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure numbers are correctly formatted or provide the `country` parameter in the request object (e.g., `BasicInsightRequest(number='79111234567', country='GB')`).","message":"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').","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The provided Vonage API Key or API Secret is incorrect, or environment variables are not loaded.","error":"AuthenticationError: 'Signature verification failed' or 'API Key / Secret is invalid'"},{"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>`.","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.","error":"AttributeError: 'VonageClient' object has no attribute 'number_insight'"},{"fix":"Switch to asynchronous Advanced Number Insight requests by using `AdvancedAsyncInsightRequest` and providing a `callback` URL to receive the results.","cause":"Attempting a synchronous Advanced Number Insight request, which can exceed typical API timeouts due to extensive data processing.","error":"requests.exceptions.Timeout: The read operation timed out"}]}