{"id":9398,"library":"vonage-numbers","title":"Vonage Numbers","description":"The `vonage-numbers` library provides a dedicated Python client for interacting with the Vonage Numbers API. It allows developers to programmatically manage their Vonage phone numbers, including searching, buying, updating, and canceling them. It is built on top of the `vonage-python` SDK and is currently at version 1.0.5, with updates tied to the underlying Vonage API and SDK changes.","status":"active","version":"1.0.5","language":"en","source_language":"en","source_url":"https://github.com/Vonage/vonage-python-numbers","tags":["vonage","api","telecom","numbers","sdk"],"install":[{"cmd":"pip install vonage-numbers","lang":"bash","label":"Install vonage-numbers"}],"dependencies":[{"reason":"Required as the core Vonage SDK client for authentication and API communication.","package":"vonage-python"}],"imports":[{"symbol":"Numbers","correct":"from vonage_numbers import Numbers"},{"note":"The core Vonage client (for authentication) is imported from the parent `vonage-python` SDK and then passed to the `vonage-numbers` client.","symbol":"Client","correct":"import vonage"}],"quickstart":{"code":"import vonage\nfrom vonage_numbers import Numbers\nimport os\n\nVONAGE_API_KEY = os.environ.get(\"VONAGE_API_KEY\", \"YOUR_API_KEY\")\nVONAGE_API_SECRET = os.environ.get(\"VONAGE_API_SECRET\", \"YOUR_API_SECRET\")\n\nif VONAGE_API_KEY == \"YOUR_API_KEY\" or VONAGE_API_SECRET == \"YOUR_API_SECRET\":\n    print(\"Please set VONAGE_API_KEY and VONAGE_API_SECRET environment variables or replace placeholders.\")\nelse:\n    try:\n        # Initialize Vonage client\n        client = vonage.Client(key=VONAGE_API_KEY, secret=VONAGE_API_SECRET)\n\n        # Initialize Numbers client\n        numbers_client = Numbers(client)\n\n        # Example: get all numbers\n        print(\"Fetching all Vonage numbers...\")\n        all_numbers = numbers_client.get_all_numbers()\n        if all_numbers and all_numbers.get('numbers'):\n            print(f\"Successfully retrieved {len(all_numbers['numbers'])} numbers.\")\n            for number_data in all_numbers['numbers'][:2]: # Print first 2 for brevity\n                print(f\"- Number: {number_data.get('msisdn')}, Country: {number_data.get('country')}\")\n        else:\n            print(\"No numbers found or response was empty.\")\n\n    except vonage.exceptions.VonageClientException as e:\n        print(f\"Vonage API Error: {e}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"Initialize the core `vonage.Client` with API credentials, then use it to instantiate the `vonage_numbers.Numbers` client to perform operations like fetching all owned numbers. Ensure `VONAGE_API_KEY` and `VONAGE_API_SECRET` environment variables are set."},"warnings":[{"fix":"Ensure both `vonage-numbers` and `vonage-python` are installed: `pip install vonage-numbers vonage-python`","message":"The `vonage-numbers` library is a thin wrapper around the `vonage-python` SDK. You must install `vonage-python` separately for `vonage-numbers` to function correctly.","severity":"gotcha","affected_versions":"All versions"},{"fix":"First create `client = vonage.Client(key='YOUR_KEY', secret='YOUR_SECRET')`, then `numbers_client = Numbers(client)`.","message":"The `vonage_numbers.Numbers` client requires an initialized `vonage.Client` instance to be passed to its constructor. Directly instantiating `Numbers()` without the client will result in a `TypeError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Regularly consult the official Vonage Developer Documentation for the Numbers API to stay updated on schema changes or deprecated features.","message":"While `vonage-numbers` itself is stable, underlying changes to the Vonage Numbers API can lead to unexpected request/response formats or deprecated endpoints. Keep an eye on official Vonage API documentation.","severity":"breaking","affected_versions":"All versions (due to external dependency on API)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the `vonage-python` SDK: `pip install vonage-python`","cause":"The core `vonage-python` SDK, which `vonage-numbers` depends on for client initialization and API interaction, is not installed.","error":"ModuleNotFoundError: No module named 'vonage'"},{"fix":"First, create an authenticated `vonage.Client` instance, then pass it to `Numbers`: `client = vonage.Client(key='...', secret='...'); numbers_client = Numbers(client)`","cause":"You attempted to instantiate the `vonage_numbers.Numbers` client without providing an initialized `vonage.Client` instance.","error":"TypeError: Numbers.__init__() missing 1 required positional argument: 'client'"},{"fix":"Ensure `VONAGE_API_KEY` and `VONAGE_API_SECRET` environment variables are set correctly, or pass your valid API key and secret directly as arguments to `vonage.Client(key='YOUR_API_KEY', secret='YOUR_API_SECRET')`.","cause":"The `vonage.Client` was initialized without valid API key and secret, or the provided credentials were incorrect.","error":"vonage.exceptions.VonageClientException: You need to supply a key and secret to the Vonage client"}]}