SIM Swap Check

curl --request POST \
  --url https://platform.otpless.app/v1/telecom/sim-swap-check \
  --header 'Content-Type: application/json' \
  --header 'clientId: <api-key>' \
  --header 'clientSecret: <api-key>' \
  --data '
{
  "phoneNumber": "917020141726",
  "maxAge": 72
}
'

{
  "success": true,
  "swapped": false,
  "phoneDetail": {
    "operator": "JIO",
    "countryCode": "91",
    "country": "IN",
    "type": "MOBILE",
    "homeOperator": "JIO",
    "location": "India",
    "timeZones": [
      "Asia/Kolkata"
    ]
  }
}

POST

telecom

sim-swap-check

curl --request POST \
  --url https://platform.otpless.app/v1/telecom/sim-swap-check \
  --header 'Content-Type: application/json' \
  --header 'clientId: <api-key>' \
  --header 'clientSecret: <api-key>' \
  --data '
{
  "phoneNumber": "917020141726",
  "maxAge": 72
}
'

{
  "success": true,
  "swapped": false,
  "phoneDetail": {
    "operator": "JIO",
    "countryCode": "91",
    "country": "IN",
    "type": "MOBILE",
    "homeOperator": "JIO",
    "location": "India",
    "timeZones": [
      "Asia/Kolkata"
    ]
  }
}

What is maxAge?

maxAge is the lookback window in hours. The API checks whether the SIM was swapped within that window.

maxAge: 24 — was the SIM swapped in the last 24 hours?
maxAge: 72 — was the SIM swapped in the last 3 days?
Omit maxAge to use the default lookback window.

A smaller maxAge gives a tighter, more recent check. For high-risk flows (e.g. password reset, large transaction), a shorter window is more conservative.

How to interpret the response

Field	Value	Meaning
`success`	`true`	Check completed. Use `swapped` for the result.
`success`	`false`	Check could not be completed (e.g. operator not supported). Inspect the `error` object.
`swapped`	`true`	A SIM swap was detected within the `maxAge` window. Treat this as a risk signal.
`swapped`	`false`	No SIM swap detected within the window.

swapped: false does not mean the number has never been swapped — it means no swap was found within the requested window. When success is false, swapped is omitted.

What is phoneDetail?

phoneDetail contains enriched metadata about the phone number returned alongside the swap result — including operator, country, line type, and time zones. All fields are omitted when not available for the given number or operator.

Field	Type	Description
`operator`	string	Current network operator (e.g. `JIO`, `AIRTEL`, `VI`)
`countryCode`	string	Numeric country code (e.g. `91`)
`country`	string	ISO 3166-1 alpha-2 country code (e.g. `IN`)
`type`	string	Phone line type (e.g. `MOBILE`)
`homeOperator`	string	Registered operator, which may differ from `operator` if the number is roaming or ported
`location`	string	Location string for the number’s registered area
`timeZones`	string[]	IANA time zones for the number’s registered location

Authorizations

clientId

string

header

required

OTPless API Client ID

clientSecret

string

header

required

OTPless API Client Secret

Body

application/json

phoneNumber

string

required

Phone number including country code, without plus sign. Example: 917020141726 for +91 70201 41726.

Example:

"917020141726"

maxAge

integer

Maximum age of SIM swap to check, in hours. Example: 72 checks whether the SIM was swapped in the last 3 days. Omit to use the default lookback window.

Example:

72

Response

HTTP 200 — Request accepted. Inspect success in the body:

success: true — Check completed. Use swapped to determine result.
success: false — Check could not be completed. Inspect error for details.

success

boolean

required

true if the check completed successfully. false if the check could not be completed — inspect the error object for details.

swapped

boolean

true if a SIM swap was detected within the maxAge window. false if no swap was detected. Omitted when success is false.

phoneDetail

object

Enriched phone metadata. Fields are omitted when not available for the given number or operator.

Show child attributes

error

object

Error object returned inside a 200 response when success is false.

Show child attributes

Overview Call Forwarding Check

⌘I

API Documentation

Verify Frontend SDK token

Telecom

Authorizations

Body

Response