Getting Started with SIM Swap API
Published on May 16, 2024

Introduction

This blog post will help you understand the SIM Swap API and guide you through making your first API call.

What is SIM Swap API?

The SIM Swap API allows developers to determine if and when someone's phone number went through a SIM swap. 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.

  • A business and application profile approved by the CSPs to access the Network APIs. The "Setting up your account" section of this tutorial 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.

Set up your account

Before making API calls, we must set up our account by submitting our profile for approval by the CSPs to get access to the Network APIs. Submissions are managed through the Vonage Network Registry.

Here's how you set up your account and get approval:

  1. Create a business profile

  2. Create an application profile

  3. Connect the Vonage application

Create a Business Profile

Log in to your Vonage account, and under your avatar image on the right side of the portal, click on "My dashboard". Then, navigate to Registry -> Network Registry under the Build & Manage section.

Click "Add business profile" and complete the form with your business information, including your organization's profile and business location. Don’t forget to select the countries where your service will be available.

New Business ProfileNew Business Profile

After submission, you’ll see a summary of your business profile. This summary helps you keep track of your registration status. You will receive email notifications when the status of your registration changes.

Create an Application Profile

Application profiles are used to enable one or more Network APIs, declare the purpose for which they will be used, and submit them to our CSPs for approval.

Once your business profile is approved, click on the name of the profile you wish to add applications profiles. Then, click "Add application profile". A form like this will show up where you’ll need to provide more information about what kind of application you are building.

Network application profileNetwork application profile

Once submitted, you will see an updated summary, including your Network Application profiles. You will receive email notifications when your application status changes. You can also monitor the status of your submitted applications by clicking on the application name profile:

Submissions statusSubmission status

Connect Vonage Application

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. The Vonage application contains the credentials needed to make API calls.

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. Note that a new public key will appear on 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 created in the previous steps. Since SIM Swap API does not require Redirect UI, you can leave this field blank.

Network APIs activationNetwork APIs activation

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 detect if a given phone number's SIM card has been swapped, 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.

Alvaro NavarroSenior Developer Advocate

Alvaro is a developer advocate at Vonage, focusing on Network APIs. Passionate about Developer Experience, APIs, and Open Source. Outside work, you can often find him exploring comic shops, attending sci-fi and horror festivals or crafting stuff with those renowned tiny plastic building blocks.

Ready to start building?

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

Subscribe to Our Developer Newsletter

Subscribe to our monthly newsletter to receive our latest updates on tutorials, releases, and events. No spam.