Vonage Network Sim Swap Client

Common errors

• AttributeError: 'Client' object has no attribute 'sim_swap'

  cause The `vonage` library version is too old and does not include the `sim_swap` client, or the `vonage-network-sim-swap` package (which pulls in `vonage`) was not installed correctly.
  fix Ensure you have the latest `vonage-network-sim-swap` installed, which should pull in a compatible `vonage` SDK. Run `pip install --upgrade vonage-network-sim-swap` or `pip install --upgrade vonage`.

• SIM Swap Check failed for +15551234567:   Error Code: 401   Error Message: Authentication failed: Invalid credentials

  cause The provided Vonage API Key and/or API Secret are incorrect or missing, leading to an authentication failure with the Vonage API.
  fix Verify your `VONAGE_API_KEY` and `VONAGE_API_SECRET` are correctly set in your environment variables or passed to the `vonage.Client` constructor. Regenerate them in the Vonage Dashboard if necessary.

• SIM Swap Check failed for 15551234567:   Error Code: 400   Error Message: Invalid parameter: phone_number

  cause The phone number provided to the Sim Swap API is not in the required E.164 format (e.g., missing the leading '+' or country code).
  fix Ensure the `phone_number` variable is formatted correctly, including the '+' and country code, for example, `'+15551234567'`.

• SIM Swap Check failed for +15551234567:   Error Code: NETWORK_REGISTRY_ERROR   Error Message: This feature requires Network Registry to be enabled for your application.

  cause The 'Network Registry' capability has not been enabled for your Vonage Application in the Vonage Dashboard, which is necessary for accessing Sim Swap functionality.
  fix Navigate to your Vonage Dashboard, go to 'Applications', select your application, and enable the 'Network Registry' capability. Select 'Playground' for testing environments.

Warnings

• breaking Older versions of the Vonage SDK or Sim Swap examples might refer to a `check_sim_swap()` method, which is now deprecated. Use `check_sim_swap_date()` or `check_sim_swap_two_factor()` instead for current functionality.
  Fix: Update your code to use `client.sim_swap.check_sim_swap_date()` or `client.sim_swap.check_sim_swap_two_factor()` as per the latest Vonage Python SDK documentation.
• gotcha The Vonage Sim Swap API requires phone numbers to be in E.164 format (e.g., `+12345678900`), including the country code prefix. Incorrect formatting will lead to API errors.
  Fix: Always ensure phone numbers are properly formatted to E.164 before making API calls. You can validate and format numbers using libraries like `phonenumbers`.
• gotcha To use the Sim Swap API, you must enable the 'Network Registry' capability within your Vonage Application in the Vonage Dashboard. For initial testing, utilize the 'Playground' mode, which allows testing with virtual operators or whitelisted numbers without full production approval.
  Fix: Go to your Vonage Dashboard -> Applications, select or create an application, and enable the 'Network Registry' capability. For local development, configure 'Playground' access.
• gotcha Authentication for `vonage.Client` typically uses API Key and Secret. Ensure these are correctly configured and kept secure, preferably via environment variables.
  Fix: Set `VONAGE_API_KEY` and `VONAGE_API_SECRET` environment variables. Alternatively, you can pass them directly to `vonage.Client(key='YOUR_KEY', secret='YOUR_SECRET')` but avoid hardcoding in production.

Install

• pip install vonage-network-sim-swap Install `vonage-network-sim-swap` (also installs `vonage`)

Imports

• Client

  import vonage

  The `vonage-network-sim-swap` package installs the `vonage` library as a dependency. Sim Swap API access is provided via methods on `vonage.Client().sim_swap`.
• date

  from datetime import date

  Required for specifying the date parameter in methods like `check_sim_swap_date`.

Quickstart

This quickstart demonstrates how to initialize the Vonage client and use the `check_sim_swap_date` method to query for SIM swap activity on a given phone number. Ensure your Vonage API Key and Secret are configured, and the phone number is in E.164 format. You must also enable the Network Registry capability in your Vonage Application for this API to work.

import vonage
import os
from datetime import date

# Ensure VONAGE_API_KEY and VONAGE_API_SECRET are set in your environment
# or replace with actual credentials for testing (not recommended for production)
api_key = os.environ.get('VONAGE_API_KEY', 'YOUR_API_KEY')
api_secret = os.environ.get('VONAGE_API_SECRET', 'YOUR_API_SECRET')
phone_number = os.environ.get('VONAGE_SIM_SWAP_PHONE_NUMBER', '+15551234567')

if not api_key or not api_secret or api_key == 'YOUR_API_KEY':
    print("Please set VONAGE_API_KEY and VONAGE_API_SECRET environment variables.")
    exit(1)

if not phone_number.startswith('+'):
    print("Warning: Phone number should be in E.164 format (e.g., +15551234567). Prepending '+' for example.")
    phone_number = '+' + phone_number

client = vonage.Client(key=api_key, secret=api_secret)

try:
    # Check for SIM swap activity as of a specific date
    # The date should be within the last 30 days for most carriers.
    response = client.sim_swap.check_sim_swap_date(
        phone_number=phone_number,
        date_identifier=date(2024, 1, 1), # Example date. Use a relevant date for real checks.
        five_g_nr_check=False # Optional: set to True for 5G network checks if supported and desired
    )

    if response.is_successful():
        print(f"SIM Swap Check successful for {phone_number}:")
        print(f"  Status: {response.status}")
        print(f"  Latest SIM Swap Date: {response.latest_sim_swap_date}")
        print(f"  Is Swapped: {response.is_swapped}")
    else:
        print(f"SIM Swap Check failed for {phone_number}:")
        print(f"  Error Code: {response.error_code}")
        print(f"  Error Message: {response.error_message}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")