Telecom Intelligence
SIM swap API
The Telebase SIM swap API returns whether a phone number's SIM has been recently replaced, along with the timestamp of the most recent swap event. It is designed to be queried in real time at authentication, before an OTP is sent or account access is granted. The API also returns carrier, country, number type and active status in the same call. Pricing is $0.03 per query with no contract and no minimum spend. SIM swap detection is launching for GB, DE, NL and FR. Early access is available now.
What the API returns
A single call to the Telebase lookup endpoint returns all available signals for the queried number. The SIM swap field is the headline signal for fraud and authentication use cases.
| Field | Type | Description |
|---|---|---|
simSwap | string | SWAPPED, NO_SWAP, or UNKNOWN. Currently returns UNKNOWN for GB, DE, NL, FR while carrier registration completes. |
simSwapAt | string | null | ISO 8601 timestamp of the most recent swap event. Set only when simSwap is SWAPPED. |
active | boolean | null | Whether the number is currently reachable on the carrier network. |
carrier | string | null | The network operator currently serving the number. |
country | string | null | ISO 3166-1 alpha-2 country code. |
numberType | string | null | One of: mobile, landline, fixedVoip, nonFixedVoip, tollFree, voicemail. |
Example call
GET https://telebase.fatcatremote.com/api/lookup?phone=%2B447700900000 Authorization: Bearer tb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
{
"phoneNumber": "+447700900000",
"active": true,
"carrier": "EE",
"country": "GB",
"numberType": "mobile",
"simSwap": "UNKNOWN", // launching, carrier registration in progress
"simSwapAt": null,
"_meta": { "activeSource": "LINE_STATUS" }
}
simSwap will return SWAPPED or NO_SWAP once carrier registration completes. UNKNOWN means no SIM swap data is available for that number's carrier or region, not that no swap occurred.
How to integrate
- Numbers must be in E.164 format. The leading
+must be URL-encoded as%2Bin the query string. - Authenticate with
Authorization: Bearer tb_live_.... API keys are available from your dashboard after sign-up. - On a
200response, readsimSwapfirst. IfSWAPPED, readsimSwapAtfor recency. A swap within the last 24 to 72 hours before authentication is the highest-risk scenario. - On
UNKNOWN, the signal is unavailable for that number. Do not treat it asNO_SWAP. Fall back to your other risk signals. - Errors return
{"error": "<code>"}. See the full error reference at telebase.io/skills-md.
Coverage
SIM swap detection is launching for GB, DE, NL and FR. Carrier, country, number type and active status are live across all four markets today. New accounts receive a $5.00 starting balance on sign-up.