SIM Swap

The SIM Swap Insight allows you to determine if the SIM card linked to a given phone number has recently changed. It is designed to mitigate the impact of account takeover (SIM swap attack), giving developers the assurance that the phone number can be used for multiple use cases, such as the ability to proceed with SMS two-factor authentication or as a secure communications channel.

SIM swap fraud grants an attacker control over a victim's mobile phone number, potentially enabling:

• 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 insight is to provide an assessment of fraud risk by identifying SIM swap events. Integrating SIM Swap can complement various scenarios, including:

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

Prerequisites

To use Identity Insights, you must ensure your account is configured correctly; see the Getting Started guide for more information on:

• Creating your account,
• Creating a Vonage application for use with the Identity Insights API,
• The different environments available and how to configure your account to use them,
• And how to use the Dashboard Getting Started UI to use the API without writing any code.

This guide will explain how to use the SIM Swap Insight programatically using cURL.

Making an API Call

Authentication for the Identity Insights API is done via JWTs, a compact and self-contained JSON token. To generate a JWT, you can use our online generator, or alternatively use the Vonage CLI. You will need your application ID and private key to generate the JWT. Once you have your JWT, you can send a request to the API.

This example shows a cURL request for the SIM Swap insight to check if a SIM Swap has occured within the last 240 hours; this is defined by the period parameter, which can be set to anywhere between 1 and 2400 hours:

curl -X POST https://api-eu.vonage.com/v0.1/identity-insights \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "14040000000",
    "purpose": "FraudPreventionAndDetection",
    "insights": {
        "sim_swap": {
         "period": 240
          }
        }
    }'

The API will then compare the information associated with the particular mobile phone user with that on file (and verified) from the mobile phone user's operator's own records, and return a match value for each attribute provided:

{
  "request_id": "c2cc7a65-9b10-493f-9c0a-1c86751a91c4",
  "insights": {
    "sim_swap": {
        "latest_sim_swap_at": "2024-07-08T09:30:27.504Z",
        "swapped": true,
        "status": {
          "code": "NO_COVERAGE",
          "message": "Success"
        }
    }
  }
}

You'll see the following fields in the sim_swap array:

Further Reading

• Read more about the Identity Insights API in the API Reference.
• If you have any questions, you can reach out to us on the Vonage Community Slack.