SIM Swap

SIM Swap refers to the process of binding a user's phone number to a new SIM card. This usually occurs in the following scenarios: reporting a lost card and getting a replacement, upgrading a SIM card, porting a number to another network, activating multi-SIM services, or a new user inheriting a number previously used by someone else.

Attackers can use SIM Swap to hijack someone else's phone number, intercept SMS verification codes, and subsequently reset passwords and take over accounts. The SIM Swap API can detect in real time whether a specified phone number has undergone a SIM swap, helping businesses identify potential SIM hijacking risks in critical processes such as SMS OTP verification and reducing the probability of account takeover.

Note: Currently, checking SIM Swap is only supported for numbers in the following countries/regions: Brazil, Indonesia.

This API provides two independent endpoints:

• Retrieve Date: Query the time of the most recent SIM Swap for a specified phone number.
• Check: Detect whether a SIM Swap has occurred for a specified phone number within the past N hours.

Authentication

Both endpoints use the HTTP Basic Auth authentication method. Add Authorization to the HTTP Header:

              
              Authorization: Basic ${base64_auth_string}

            

The generation algorithm for ${base64_auth_string} is: base64(dev_key:dev_secret).

For more details, please refer to Authentication to learn how to perform API authentication.

Retrieve Date

Query the time of the most recent SIM Swap for a specified phone number.

Request URL

POST https://otp.api.engagelab.cc/v1/sim-swap/retrieve-date

Request Example

A request object is expressed in JSON format, so the request header needs to include Content-Type: application/json.

Request Header

              
              POST /v1/sim-swap/retrieve-date HTTP/1.1
Content-Type: application/json
Authorization: Basic ${base64_auth_string}

            

Request Body

              
              {
  "phone_number": "+381692223535"
}

            

Request Parameters

Response Parameters

Success Response

Success response example:

              
              {
  "request_id": "2055136570436075520",
  "latest_sim_change": "2026-05-01T15:00:00Z"
}

            

Failure Response

The HTTP status code is 4xx or 5xx, and the response body contains the following fields:

Common failure response examples:

Parameter error example:

              
              {
  "code": 3002,
  "message": "invalid phone_number"
}

            

Insufficient balance example:

              
              {
  "code": 3005,
  "message": "balance not enough"
}

            

Number not in service coverage area example:

              
              {
  "code": 5101,
  "message": "phone number is not in sim swap service coverage"
}

            

General failure example:

              
              {
  "code": 5100,
  "message": "failed to retrieve sim swap date"
}

            

Check

Detect whether a SIM Swap has occurred for a specified phone number within the past N hours.

Request URL

POST https://otp.api.engagelab.cc/v1/sim-swap/check

Request Example

A request object is expressed in JSON format, and the request header also needs to include Content-Type: application/json.

Request Header

              
              POST /v1/sim-swap/check HTTP/1.1
Content-Type: application/json
Authorization: Basic ${base64_auth_string}

            

Request Body

              
              {
  "phone_number": "+381692223535",
  "max_age": 400
}

            

Request Parameters

Response Parameters

Success Response

Success response example:

              
              {
  "request_id": "2055136570293469184",
  "swapped": true
}

            

Failure Response

The structure is the same as the Retrieve Date endpoint. Specific failure response example:

Parameter error (max_age out of range):

              
              {
  "code": 3002,
  "message": "max_age must be between 1 and 2400"
}

            

Error Codes