Getting Started with SIM Swap API

Introduction

This blog post will help you understand the SIM Swap API and guide you through making your first API call. Please note that this API is currently in beta, so some features may change as we continue to improve it.

What is SIM Swap API?

The SIM Swap API allows developers to determine if the SIM card linked to the phone number has recently changed. The API includes two endpoints to answer the following questions:

• Has a SIM swap occurred during the last X hours?
• When did the last SIM swap happen?

SIM Swap API belongs to the new Vonage Network APIs, a new collection of APIs based on the CAMARA standard that exposes developers to the network capabilities of mobile carriers (e.g., Telefonica, Deutsche Telekom, or Vodafone). These mobile carriers are also known as Communication Service Providers (CSPs).

Why SIM Swap API?

SIM swap fraud is considered one of the biggest threats because it grants attackers control over a victim's mobile phone number. Here are some of the most common risks:

• Identity theft. Attackers can use SIM swapping to impersonate the victim's identity as they gain control over the victim’s phone number.
• Account takeover. Many online accounts, including email, social media, and financial accounts, use phone numbers for two-factor authentication (2FA) or account recovery. By swapping the SIM card, attackers can intercept authentication codes sent via SMS and gain unauthorized access to the victim's accounts.
• Financial fraud. Once attackers access the victim's accounts, they can conduct various forms of financial fraud, such as transferring funds, making unauthorized purchases, or taking out loans in the victim's name.
• Privacy violation. Attackers may access personal communications, contacts, and other sensitive information stored on the victim's devices or accounts.

One of the primary purposes of the SIM Swap API is to provide an assessment of fraud risk by identifying SIM swap events. Integrating the SIM Swap API can complement various scenarios, including:

• Adding a risk factor/fraud score to an individual
• Strengthening traditional 2FA method based on recent events reported by SIM Swap API
• Monitoring fraudulent activity on customers' phone numbers
• Regulatory compliance can require checks against SIM Swap

Prerequisites

To follow this tutorial and make your first API call, you’ll need the following:

• A Vonage account. You can create a new account if you don’t have one.
• To access the network APIs, you need a business and application profile approved by the CSPs. The Introduction to the Network Registry post will guide you through the process.
• We will use cURL to make API calls. You can install it from cURL download page using your favorite package manager.

Create New Application

Let’s start by creating a new application with the capabilities of the Network APIs. The Vonage application contains the credentials needed to make API calls. Once your submission is approved by at least one of its CSPs, you can link it to one or more Vonage applications to start using the Network APIs.

Warning: Remember that application credentials are secret and for personal use only. Do not share them with anyone.

Go to "Applications" under the "Build & Manage" menu and click on the "Create a new application" button. Follow these steps:

• Give a name to your application.
• Click on "Generate public and private key," as you’ll need this during the authentication process. A new public key will appear in the text box. Your browser will automatically download the private key.
• Under the capabilities section, enable "Network APIs" and select the business profile and the application profile you have previously created. Since SIM Swap API does not require Redirect UI, you can leave this field blank.

Once finished, click "Generate new application".

Make your First API Call

Authentication

Vonage 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:

• Copy and paste the private key that was automatically downloaded to your browser.
• Copy and paste the application ID, which can be found under the application you created in the previous step.
• Set a valid period of the JWT. For this example, we’ll establish a valid time of 1 hour.
• Leave ACL and the rest of the checkboxes empty.

The JWT will appear on the right side of the screen. Copy the JWT token and send a POST request with the following headers and body:
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"''

Where:

• $JWT is the recently created JWT.
• $MSISDN is the phone number you wish to check (e.g. +34677123456)
• $SCOPE corresponds to the purpose for which you are calling the API. Since we want to check if a SIM card was exchanged, let’s set this to this string value: "dpv:FraudPreventionAndDetection#check-sim-swap"

If everything goes well, 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 we’ll use in the following API call to generate the access token:
curl --url 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

We are ready to perform our API call to SIM Swap API with the access token. According to the API reference, the API contains two different endpoints:

• Check whether a SIM card was exchanged.
• Retrieve the date when the last swap was performed.

Let’s start by checking if our SIM card was swapped. Send a POST request with the following fields in the body in JSON format:

• phoneNumber: this is the phone number we want to check. It should match the phone number used during the authentication step.
• maxAge: corresponds with the maximum number of days we 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
}

Given that the endpoint has returned true, let’s find out when the swap was performed. To do so, we need to retrieve a new 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"''

Where $SCOPE should be pointing to:
"dpv:FraudPreventionAndDetection#retrieve-sim-swap-date"

With the new access token, we are ready to 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"}

Conclusion

SIM Swap API allows developers to determine if the SIM card linked to the phone number has recently changed, offering 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.

If you have further questions, contact Vonage Community Slack or message us on X.

Read further

You can also learn more about the SIM Swap API in our Developer Documentation.