In this post, you will learn how to make your first API call to SIM Swap API using the Sandbox, a safe environment to test and interact with the Network APIs before the approval from the CSPs. We’ll also use the Virtual CSP, a fake mobile operator that provides deterministic responses, allowing you to understand how the API behaves. To implement the API calls, we will use Python.

Prerequisites

• A Vonage developer account.

• Python (>= 3.9) is installed on your system.

The steps described in this tutorial are based on macOS or Linux. Similar commands will be used for Windows environments.

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Create a New Application

The first step is to create a new application with “Network Registry“ capabilities. To do this, go to your dashboard and select “Applications” from the left-side menu.

Click on the “Create a new application” button. On the new screen, enter a name for your application and click on “Generate public and private key”. This will generate a new pair of keys. The public key will be displayed on the dashboard, while the private key will be automatically downloaded to your computer. Keep the private key safe, as you’ll need it during the API authentication.

Application properties

Next, go to the “Capabilities” section and locate the “Network Registry” capability. Click the toggle icon to enable it, and select “Sandbox” access type. We won't use the Redirect field since we are testing SIM Swap API. You can set it up to a URL of your choice (e.g. https://example.com/callback)

Network Registry Capability

After creating the application, copy the Application ID displayed in the application summary. You'll need this later.

What Have We Done So Far? 

We have created an application to access the Network APIs in Sandbox mode. The sandbox is a safe, isolated environment where developers can test and interact with APIs without approval from the CSP to start using the APIs.

Inside the Sandbox, we can use live data by adding the phone numbers from supported CSPs to the allowlist, or use fake data with a Virtual CSP, allows us to use the Network APIs without restrictions related to countries or CSPs currently supported.

Set up the Environment

Open a terminal and create a folder.

mkdir simswap-test

Create a new virtual environment to install the dependencies for our project. 

python -m venv .venvsource .venv/bin/activate

Finally, let’s install the Vonage Python SDK, which simplifies the auth flow and the API calls to the Network APIs: 

pip install vonage==4.1.1

The environment is ready!

Authentication

It’s time to start coding! Open your favorite code editor and create a new file called simswap.py.

Let’s start with the authentication part. The SIM Swap API requires server-side (backend) authentication. Using the SDK is as simple as follows:

from vonage import Vonage, Auth

auth = Auth(
       application_id='xxx-yyyy-zzzz',
       private_key='/path/to/my/private.key',
    )

vonage_client = Vonage(auth)

Where application_id and private_key correspond with the credentials from the application created before.

Implement the API Calls

Once our auth object is ready, we can instantiate the client object and perform our first API call. In this example, we are calling the check method from the network_sim_swap package to verify if the phone number was linked with a new SIM card in the last 500 hours:

from vonage_network_sim_swap.requests import SimSwapCheckRequest

response = vonage_client.network_sim_swap.check(
    SimSwapCheckRequest(phone_number='+990491793')
)
print(response)
> {‘swapped’: True}

Since we use the Sandbox with the Virtual CSP, the phone number must start with the +990 prefix. According to the Virtual CSP documentation, we can modify the max_value argument to obtain different responses:

• For values lower than 500, check_sim_swap() returns false.

• For values 500 or higher, the method will return true.

Let’s see some examples:

phone = '+99012345'
response = vonage_client.network_sim_swap.check(
   SimSwapCheckRequest(phone_number=phone, max_age=480)
 )
print(swapped)
> {‘swapped’: False}


phone = '+99012345'
response = vonage_client.network_sim_swap.check(
   SimSwapCheckRequest(phone_number=phone, max_age=501)
 )
print(swapped)
> {‘swapped’: True}

Full Source Code

The simswap.py content should look like this:

from vonage import Vonage, Auth
from vonage_network_sim_swap.requests import SimSwapCheckRequest

auth = Auth(
    application_id="xxxx-yyyy-zzzz",
    private_key="/path/to/your/private.key",
)

vonage_client = Vonage(auth)

try:
    response = vonage_client.network_sim_swap.check(
        SimSwapCheckRequest(phone_number='+990491234')
    )
    print(response)
except Exception as e:
    print(e)

Get in Touch

If you completed the tutorial, congratulations! We’d love to hear your feedback! Join us on the Vonage Community Slack or message us on X, and we will get back to you. 

Thanks for reading!