Making a Request with the SIM Swap API

This API will be sunset on November 23, 2025, and will no longer be available after that date. To detect SIM Swap, please migrate to the Identity Insights API.

This guide explains how to make your first request using the SIM Swap API.

Prerequisites

Before using the SIM Swap API, you will need to register your application with Vonage and the mobile operators. If you already have an approved registration, you are ready to start building your solution. If not, head to our guide on Vonage Network Registration for more information.

You must also generate an access token using the backend authentication flow. See the guide on Network Feature Authentication for more information.

If your registration has not been accepted by Vonage or any operator, for example, the Network Feature Registration status is ‘Pending’ or “Rejected’, you are not authorized to use or send any Network Feature requests.

Make the SIM Swap API Request

Make a

POST
request to the correct endpoint for the operation you are using:

  • Check: Has a SIM swap occurred during the last n hours?
  • Retrieve Date: When did the last SIM swap occur?

To make the request, you'll use the access_token created as part of the prerequisites.

check request

POST
https://api-eu.vonage.com/camara/sim-swap/v040/check

curl -X POST https://api-eu.vonage.com/camara/sim-swap/v040/check \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data $'{
        "phoneNumber": "'$PHONE_NUMBER'",
        "maxAge": 240 
}'

Parameters

Parameter Description
phoneNumber The MSISDN / full phone number of the user you want to run a SIM Swap check for, e.g. 447700900000.
maxAge Period in hours to be checked, from 1 to 2400 (optional, default set to 240)

Successful check response (200)

A successful response will contain the swapped field, a Boolean value that indicates whether a SIM swap has been performed during the period specified in your request.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
"swapped": true
}

retrieve-date request

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

Parameters

Parameter Description
phoneNumber The MSISDN / full phone number of the user you want to run a SIM Swap check for, e.g. 447700900000.

Successful retrieve-date response (200)

A successful response will contain the latestSimChange field showing the timestamp of the latest SIM swap performed.

HTTP/1.1 200 OK
Content-Type: application/json

{
"latestSimChange": "2024-01-31T11:44:22.292Z"
}