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.20 per SIM swap check with no annual commitment, carrier data included. SIM swap detection is live in the UK and Germany, with more markets on the way. 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 outside the UK and Germany, where coverage is still expanding. |
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://api.telebase.io/lookup?phone=%2B447700900000 Authorization: Bearer tb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
{
"phoneNumber": "+447700900000",
"active": true,
"carrier": "EE",
"country": "GB",
"numberType": "mobile",
"simSwap": "UNKNOWN", // live in the UK and Germany, more markets to follow
"simSwapAt": null,
"_meta": { "activeSource": "LINE_STATUS" }
}
simSwap returns SWAPPED or NO_SWAP for UK and German numbers today. Elsewhere it returns UNKNOWN, meaning no SIM swap data is available for that number's carrier or region yet, 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 live in the UK and Germany, with more markets on the way. Carrier, country, number type and active status are live globally today. New accounts start in the sandbox with test keys.
Request early access