Install & Compatibility
Where this runs
tested against v2.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 1.233s · 50MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 5.2s · import 1.103s · 50MB
49MB installed
● package 49MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
VerifyRequest
✓ from vonage_verify import VerifyRequest
SmsChannel
✓ from vonage_verify import SmsChannel
SilentAuthChannel
✓ from vonage_verify import SilentAuthChannel
EmailChannel
✓ from vonage_verify import EmailChannel
ChannelType
✓ from vonage_verify import ChannelType
Vonage
✓ from vonage import Vonage
✗ from vonage_verify import Vonage
The Vonage client is part of the main `vonage` package, not `vonage-verify`.
Auth
✓ from vonage import Auth
✗ from vonage_verify import Auth
The authentication object is part of the main `vonage` package.
This quickstart demonstrates how to initialize the Vonage client and send a verification request via SMS using `vonage-verify`. It uses environment variables for API credentials for security. The process involves creating a `VerifyRequest` with a specified `brand` and `workflow` (e.g., `SmsChannel`), and then calling `client.verify.start_verification`.
import os
from vonage import Vonage, Auth
from vonage_verify import VerifyRequest, SmsChannel
# Ensure VONAGE_API_KEY and VONAGE_API_SECRET are set as environment variables
client = Vonage(Auth(key=os.environ.get('VONAGE_API_KEY', ''), secret=os.environ.get('VONAGE_API_SECRET', '')))
# Define the recipient's phone number and brand name
recipient_number = os.environ.get('VONAGE_TEST_NUMBER', '1234567890') # Use E.164 format
brand_name = 'MyTestApp'
# Create an SMS channel for verification
sms_channel = SmsChannel(to=recipient_number)
# Construct the verification request with a workflow (SMS in this case)
params = {
'brand': brand_name,
'workflow': [sms_channel],
}
verify_request = VerifyRequest(**params)
try:
# Start the verification process
response = client.verify.start_verification(verify_request)
print(f"Verification initiated. Request ID: {response['request_id']}")
# In a real application, you would now prompt the user for the code
# and then call client.verify.check_code(request_id=response['request_id'], code=user_entered_code)
# Example of checking a code (assuming '1234' was sent and entered)
# user_entered_code = '1234'
# check_response = client.verify.check_code(request_id=response['request_id'], code=user_entered_code)
# if check_response['status'] == '0':
# print('Verification successful!')
# else:
# print(f"Verification failed: {check_response['error_text']}")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingThe legacy Number Verification API is deprecated and will sunset on September 30, 2025. Users should migrate to the unified Verify API with Silent Authentication for improved features and fallbacks.fixMigrate your integration to use the `vonage-verify` package with the `SilentAuthChannel` within a `workflow`. Refer to the Vonage Verify Migration Guide for detailed steps.
affects: <= 2.0.0 (for those using the old API)
breakingChanges to 10DLC brand verification processes, including the 'Authentication+' requirement for public profit brands, are being introduced (tentative date: October 17, 2024). This requires a 2FA email verification.fixIf you are managing 10DLC brands, you may need to update your existing brands and provide a 'verification email' to re-verify the brand. This might involve triggering a `POST /brands/:brandId/revet` request via the Vonage APIs. Consult Vonage's 10DLC documentation for the latest requirements.
affects: All versions, as this is an API-level change
gotchaThe `vonage-verify` package is a component of the broader `vonage` Python SDK. It's recommended to install and use the main `vonage` package, and interact with verify functionality through the `vonage_client.verify` object. Directly instantiating classes from `vonage-verify` (e.g., `VerifyRequest`) is correct, but the client itself should come from `vonage`.fixAlways install `pip install vonage` and instantiate your `vonage.Client` first. Then, import specific models like `VerifyRequest`, `SmsChannel`, etc., from `vonage_verify` as needed.
affects: All versions
Errors
Common errors & fixes
NameError: name 'Vonage' is not defined
Attempting to use `Vonage` class directly after only importing `vonage_verify`.
fixYou need to import `Vonage` from the main `vonage` package: `from vonage import Vonage, Auth`.
vonage.errors.AuthenticationError: Could not authenticate with Vonage. Check your credentials.
Incorrect `VONAGE_API_KEY` or `VONAGE_API_SECRET` environment variables, or hardcoded values are wrong/missing.
fixVerify that your `VONAGE_API_KEY` and `VONAGE_API_SECRET` environment variables are correctly set and correspond to active credentials in your Vonage account dashboard. Ensure they are accessible by your Python script.
vonage.errors.VerifyError: Your request is incomplete and missing the mandatory parameter $parameter
A required parameter (e.g., 'brand', 'workflow', 'to' within a channel) was omitted or an invalid value was provided in the `VerifyRequest` constructor.
fixReview the Vonage API documentation or the `vonage-verify` model definitions to ensure all mandatory parameters for your chosen verification workflow are provided and correctly formatted. For example, the `to` field for channels should be in E.164 format.
vonage.errors.VerifyError: Concurrent verifications to the same number are not allowed
An active verification request already exists for the target phone number.
fixWait for the ongoing verification to complete, fail, or expire before initiating a new one for the same number. Implement logic to check for existing verifications if this is a common scenario in your application.
vonage.errors.VerifyError: The number you are trying to verify is blacklisted for verification. (Error Code 7)
The phone number is blocked by the Vonage Anti-Fraud System or carrier-specific restrictions.
fixThis can indicate suspicious activity or network-level blocking. Review Vonage's documentation on the Verify Anti-Fraud System and consider checking if the number is on an unsupported network. If this persists for legitimate users, contact Vonage support.
Upgrade
Version history
2.2.0latest on PyPI · released Apr 22, 2026
Audit
Dependencies
vonagerequiredThe `vonage-verify` library is intended to be used as a sub-package of the main `vonage` SDK. The `vonage.Client` object is required to interact with the Verify API.