Technical Details

The SIM Swap API enables developers to mitigate the impact of account takeover fraud by strengthening SIM based authentication processes, such as SMS One-Time Passwords or silent authentication.

Built according to CAMARA standards, Vonage’s SIM Swap API is a standalone product to determine whether and when a SIM swap was last performed on an individual mobile phone number. The API works by checking, in real-time, the activation date of a SIM card on the mobile network. It can be easily integrated into your application and used to answer two distinct questions:

  • Has a SIM swap occurred during the last n hours? (check)
  • When did the last SIM swap occur? (retrieve-date)

Authentication

The authentication process for SIM Swap is known as Back-End Authentication. In summary, the Back-End Authentication is a series of

POST
requests from the mobile application in order to obtain an authorization code from the relevant mobile operator. This authorization token will then be used as part of the SIM Swap API request when checking if a SIM Swap has occurred - this process can be seen in the flow diagram below.

See our guide on Network API Authentication for code samples and more information on how Back-End Authentication works.

SIM Swap API Flow

Making a SIM Swap API call is a simple, three-step process:

  1. The SIM Swap API flow is initiated by your backend application once triggered by an end user, identified by their MSISDN (mobile phone number).
  2. The backend application then requests an authorization code for making the API Call.
  3. Finally, the backend application uses the authorization code to make a SIM Swap API call.
Vonage Communications PlatformBackend ApplicationMobile ApplicationVonage Communications PlatformBackend ApplicationMobile ApplicationTrigger functionality requiring SIM Swap API(MSISDN)Make an OIDC RequestAuthorization ResponseMake a POST to get a CAMARA tokenCAMARA token responseProceed with SIM Swap API RequestResult

SIM Swap API Operations

Vonage’s SIM Swap API offers two operations: check or retrieve-date. Each operation can be performed against one end user mobile phone number, MSISDN, at a time.

check

The check operation determines whether a SIM swap has occurred during a given period of time. The time, maxAge, is specified in hours, from 1 to 2400. If not specified, the API call will default to a maxAge of 24 hours.

retrieve-date

The retrieve-date operation returns the date when the last SIM swap event occurred. No parameters, other than MSISDN, are required for this operation.

Further Reading

For more information on the SIM Swap API, see the API Reference.