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"
]
}
}SIM Swap Check
Check whether a phone number’s SIM has been recently swapped. Use as a pre-authentication risk signal for fraud prevention.
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?
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
maxAgeto use the default lookback window.
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
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?
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
OTPless API Client ID
OTPless API Client Secret
Body
Phone number including country code, without plus sign. Example: 917020141726 for +91 70201 41726.
"917020141726"
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.
72
Response
HTTP 200 — Request accepted. Inspect success in the body:
success: true— Check completed. Useswappedto determine result.success: false— Check could not be completed. Inspecterrorfor details.
true if the check completed successfully. false if the check could not be completed — inspect the error object for details.
true if a SIM swap was detected within the maxAge window. false if no swap was detected. Omitted when success is false.
Enriched phone metadata. Fields are omitted when not available for the given number or operator.
Show child attributes
Show child attributes
Error object returned inside a 200 response when success is false.
Show child attributes
Show child attributes