Vonage Verify (Legacy)

1.0.1 · deprecated · verified Thu Apr 16

The `vonage-verify-legacy` package provides an interface for interacting with Vonage's older Verify API, which primarily supports 2FA via SMS and Voice channels. This library is part of the Vonage Python SDK monorepo and is explicitly marked as a legacy component, encouraging users to migrate to the newer Verify API. The current version is 1.0.1, and its release cadence is tied to the maintenance of the broader Vonage Python SDK, with a focus on deprecation rather than new features.

Common errors

```
Authentication Error: Invalid API Key / Secret (or similar HTTP 401/403)
```
cause Attempting to use JWT (Application ID and Private Key) credentials with the legacy Verify API, which expects API Key and API Secret, or vice-versa.

fix Verify that your `vonage_client` is initialized with the correct authentication type: `Auth(api_key='...', api_secret='...')` for the legacy `verify_legacy` client, or `Auth(application_id='...', private_key='...')` for the newer `verify` client.
```
AttributeError: 'LegacyVerify' object has no attribute 'send_whatsapp_code' (or similar for new channels)
```
cause Trying to access newer Verify API features (like WhatsApp, Email, Silent Auth, custom workflows) through the `vonage-verify-legacy` client, which only supports SMS and Voice with fixed workflows.

fix Migrate your implementation to use the new Vonage Verify API client (`vonage_client.verify`) which supports these advanced features. This will involve updating your code to use the new API's parameters and response structures.
```
ModuleNotFoundError: No module named 'vonage_verify_legacy'
```
cause The `vonage-verify-legacy` package was not explicitly installed, and only the main `vonage` package (which does not auto-install this legacy component) is present.

fix Run `pip install vonage-verify-legacy`. If you intend to use the new Verify API, you likely don't need this legacy package and should ensure you are importing from `vonage.verify` instead.

Warnings

breaking The `vonage-verify-legacy` package and the underlying Verify v1 API are deprecated. Vonage strongly encourages migration to the new Verify API (often referred to as Verify v2). The new API offers enhanced features, more channels (Silent Auth, WhatsApp, Email, RCS), flexible workflows, and improved security.
Fix: Migrate to the `vonage.verify` client within the main `vonage` SDK. This requires updating authentication to JWT and adapting to the new API's request/response models. Consult the official Vonage migration guide.
deprecated The Number Verification API, which is closely related to legacy silent authentication flows, will sunset on September 30, 2025. This indicates a broader end-of-life for older verification mechanisms and highlights the urgency of migrating to the unified Verify API with Silent Authentication workflow.
Fix: Plan and execute migration to the new Vonage Verify API's Silent Authentication workflow, which offers a single, unified API with built-in fallbacks.
gotcha The legacy Verify API uses API Key and API Secret for authentication, while the new Vonage Verify API (v2) primarily uses JWT Bearer authentication. Attempting to use JWT credentials with the `vonage-verify-legacy` client or vice-versa will lead to authentication failures.
Fix: Ensure you are using the correct authentication method for the specific Verify API version you are targeting. For `vonage-verify-legacy`, use `vonage.Auth(api_key=..., api_secret=...)`. For the new Verify API, use `vonage.Auth(application_id=..., private_key=...)` and configure `client.verify`.

Install

pip install vonage-verify-legacy Install only legacy verify package
pip install vonage Install main Vonage SDK (includes legacy verify client)

Imports

VerifyRequest

from vonage_verify_legacy import VerifyRequest

StartVerificationResponse
wrong:
```
from vonage.verify import StartVerificationResponse
```
correct:
```
from vonage_verify_legacy import StartVerificationResponse
```
The new Vonage Verify API has its own response objects; ensure you import from `vonage_verify_legacy` for legacy calls.

Quickstart

This quickstart demonstrates how to initialize the Vonage client using API key/secret (the legacy authentication method) and initiate a verification request using the `vonage-verify-legacy` package. It covers creating a `VerifyRequest` object and calling `start_verification`.

import os
from vonage import Vonage, Auth
from vonage_verify_legacy import VerifyRequest

# Configure your Vonage API key and secret (legacy authentication)
# For production, use 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')

if API_KEY == 'YOUR_API_KEY' or API_SECRET == 'YOUR_API_SECRET':
    print("Please set VONAGE_API_KEY and VONAGE_API_SECRET environment variables or replace placeholders.")
    exit()

# Initialize the Vonage client using legacy API key/secret authentication
auth = Auth(api_key=API_KEY, api_secret=API_SECRET)
vonage_client = Vonage(auth=auth)

# Define verification parameters
params = {
    'number': '14155550100', # E.164 format
    'brand': 'MyCompany',
    'workflow_id': 1 # Default workflow for SMS then Voice
}

try:
    # Create a legacy VerifyRequest object
    request = VerifyRequest(**params)

    # Make the verification request using the legacy client
    response = vonage_client.verify_legacy.start_verification(request)

    if response.status == '0' or response.status == '00':
        print(f"Verification request successful. Request ID: {response.request_id}")
        # You can then prompt the user for the code and check it
        # vonage_client.verify_legacy.check(request_id=response.request_id, code='USER_CODE')
    else:
        print(f"Verification request failed: {response.error_text} (Status: {response.status})")
except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →