Getting Started with the SIM Swap API

This guide will walk you through all of the necessary steps to get up and running with SIM Swap, an API that enables you to answer two distinct questions:

Has the SIM card linked to the phone number changed within the last n hours? (/check)
When did the last SIM swap occur? (/retrieve-date)

This offers an additional layer of security in environments when having an uncompromised phone number is crucial: recovering your account, confirming bank transactions, or accessing your private data.

Prerequisites

Before you begin, you'll need the following:

A Vonage account: Sign up here if you don't already have one.
cURL: You'll be using this to make API calls. You can install it from the cURL download page using your favorite package manager.

Set up the environment

When working with the Network APIs, there are two different environments:

Production. This environment returns live data from the supported Operators in some countries. Access to the production environment requires approval from the mobile operators. To learn how to request access, follow this guide.
Sandbox. The sandbox is a safe and controlled testing environment where API calls return live data only for a small group of allowlisted phone numbers. Unlike production, it does not require approval from Operators. Additionally, the sandbox provides access to the Virtual CSP, a simulated operator that generates fake but deterministic responses.

In this guide, we will use the Sandbox Environment with the Virtual CSP for two key reasons:

It allows immediate use of the APIs without needing approval from the Operators.
It enables testing the APIs from anywhere in the world.

Create a New Application

To get started, we need to create a new application. This application will contain the credentials required for making API calls. Follow these steps:

Go to the Dashboard and select "Applications" from the left side menu.
Click the "Create a new application" button.
Enter a name for your application in the "Name" field.
Click "Generate public and private key" to generate a key pair. A private key file will be automatically downloaded. Save this file securely, as it is requried for generating JWTs.
Scroll to the capabilities section and enable the "Network Registry" capability. Make sure the "Sandbox" environment is selected.
We don't need the Number Verification Redirect field for SIM Swap API. You can enter a placeholder URL.
Click the "Generate new application" button to finish the creation process.

After the application is created, copy the Application ID displayed on the dashboard. You will need this Application ID along with the private key file to generate JWTs for authenticating API requests.

Making a Call with the SIM Swap API

Authentication

Vonage Network API calls require a valid access token, a credential used to authenticate and authorize access to the APIs. To create an access token, you'll first need to authenticate yourself using a JWT, a compact and self-contained JSON token.

To generate a JWT, you can use our online generator, or alternatively use the Vonage CLI. Copy the JWT token and send a

POST

request with the following headers and body:

curl https://api-eu.vonage.com/oauth2/bc-authorize \
   --header 'Authorization: Bearer '"$JWT"'' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'login_hint='"$MSISDN"'' \
   —-data-urlencode 'scope='"$SCOPE"''

Where:

$JWT is the recently created JWT.
$MSISDN is the phone number you wish to check (e.g. +99012345678)
$SCOPE corresponds to the purpose for which you are calling the API. In this tutorial you'll be checking if a SIM card was exchanged, so set this to this string value: dpv:FraudPreventionAndDetection#check-sim-swap

If this is successful, the authorization server will return a response similar to this:

{
  "auth_req_id": "arid/baad1320-93b9-4e28-a449-123445678",
  "expires_in": 120,
  "interval": 2
}

The response includes the expiration time (in hours) and the auth_req_id, which is used in the next API call to generate the access token:

curl https://api-eu.vonage.com/oauth2/token \
  --header 'Authorization: Bearer '"$JWT_AP"'' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'auth_req_id='"$AUTH_REQ_ID"'' \
  --data-urlencode 'grant_type=urn:openid:params:grant-type:ciba'

The OAuth2 server should return a response like this, containing the access token:

{
   "access_token": "hbGciOiJSUzI1NiJ9.eyJpYXQiOjE3MTM3OTI2NzAsImV4cCI6MTc",
   "token_type": "Bearer",
   "expires_in": 3600,
}

SIM Swap API Call

You are ready to perform an API call to the SIM Swap API using your access token. The API contains two different endpoints:

Has a SIM swap occurred during the last n hours? (check)
When did the last SIM swap occur? (retrieve-date)

First, let's check if the SIM card was swapped. Send a

POST

request with the following fields in the body in JSON format:

phoneNumber: this is the phone number you want to check. It should match the phone number used during the authentication step.
maxAge: corresponds with the maximum number of days you want to check if the SIM was swapped.

curl --url https://api-eu.vonage.com/camara/sim-swap/v040/check \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
  --data '{"phoneNumber": "'"$MSISDN"'", "maxAge": "72"}'

The endpoint will return a boolean indicating whether a swap was performed on the given phone number:

{
   "swapped": true
}

The check has returned true, so now you can lookup when the swap was performed. To do so, you'll need to generate a new access token, as the scope of this second call retrieve is different from the previous one check:

curl --url https://api-eu.vonage.com/oauth2/bc-authorize \
     --header 'Authorization: Bearer '"$JWT"'' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode 'login_hint='"$MSISDN"'' \
     —-data-urlencode 'scope='"$SCOPE"''

Here, $SCOPE should point to dpv:FraudPreventionAndDetection#retrieve-sim-swap-date.

With the new access token, you can now make the API call to the retrieve-date endpoint:

curl --url https://api-eu.vonage.com/camara/sim-swap/v040/retrieve-date \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
  --data '{"phoneNumber": "'"$MSISDN"'"}'

Finally, the endpoint will return a timestamp containing the exact moment when the SIM card was swapped:

{"latestSimChange":"2024-02-24T01:43:31Z"}