Device Swap

The “Device Swap” feature is designed to provide real-time insights into whether a SIM card associated with a user’s phone number has been transferred to a different physical device. It enhances security, fraud detection, and regulatory compliance by offering clear and structured device swap event information.

Device Swap fraud results in an attacker getting control over a victim's SIM card and therefore, mobile phone number, potentially enabling:

• Identity theft: Attackers can use device 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 gaining control of the victim’s SIM card in their own device, 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 Device Swap insight is to provide an assessment of fraud risk by identifying Device Swap events. Integrating Device Swap can complement various scenarios, including:

• Adding a risk factor to an individual
• Strengthening traditional 2FA methods based on recent events reported by Device Swap
• Monitoring fraudulent activity on customers' phone numbers
• Regulatory compliance can require checks against Device 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 Device Swap Insight programmatically 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 Device Swap insight to check if a device swap has occurred 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/identity-insights/v1/requests  \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "14040000000",
    "purpose": "FraudPreventionAndDetection",
    "insights": {
        "device_swap": {
         "period": 240
          }
        }
    }'

The API will then compare the device associated with the particular mobile phone user with that on file from the mobile phone user's operator's own records, and return information on if and when a device swap happened within the specified period:

{
  "request_id": "c2cc7a65-9b10-493f-9c0a-1c86751a91c4",
  "insights": {
    "device_swap": {
        "latest_device_swap_at": "2024-07-08T09:30:27.504Z",
        "is_swapped": true,
        "status": {
          "code": "OK",
          "message": "Success"
        }
    }
  }
}

You'll see the following fields in the device_swap object:

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.