Technical Details

The SIM Swap API is one of the Vonage Network APIs, to determine if the SIM card linked to the phone number has recently changed. The API 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.

The SIM Swap API provides real-time verification of the activation date of a SIM card on the mobile network through two endpoints:

• /check determines if a SIM swap has occurred within a specified period. This endpoint answers the question: Has a SIM swap happened in the last n hours?
• /retrieve-date returns the date of the most recent SIM swap event. This endpoint answers the question: When did the last SIM swap occur?

Use Cases

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 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 methods based on recent events reported by SIM Swap API
• Monitoring fraudulent activity on customers' phone numbers
• Regulatory compliance can require checks against SIM Swap

API Reference

The OpenAPI specification for the SIM Swap API is available here.

Getting Started

Check out Getting Started for a step-by-step guide on how to get up and running with the SIM Swap API.

Authentication

The authentication process for the SIM Swap API is referred to as Server Authentication. For a comprehensive overview of how this works, check out our authentication guide.

Be sure to read our Network API Scopes guide to understand how scopes work in the authentication flow.

Registration

Before using the SIM Swap API, you must first register your application with Vonage and the Communication Service Providers (CSPs). The Vonage Network Registry automates the registration process through a common dashboard interface and sends the information to the CSPs for approval. Vonage’s customer dashboard is the single source for registration across all participating CSPs.

Optionally, you can use the Network Registry API to programmatically handle the registration and approval process.

Sandbox

Use the Sandbox to start using the SIM Swap API right away. It allows you to work with live data for up to five phone numbers added to an allowlist.