Developer Guide
Adding telecom signals to your existing KYC stack
Document verification tools such as Sumsub or Onfido answer one question: is this a genuine identity document, held by the person presenting it. They do not tell you whether the phone number on the application is a disposable VoIP line, whether it is currently reachable, or whether it has recently changed hands. Telebase is a single-endpoint API that adds that phone-based layer alongside your existing document checks, not instead of them. One call returns carrier, country, number type and active status today, with SIM swap detection launching.
What document verification does not see
A document verification provider is built to check a passport, a driving licence or a national ID card and match it against a selfie or liveness check. That is a strong control for a fabricated or stolen document. It has nothing to say about the phone number collected on the same form. A fraud ring can pair a stolen or synthetic identity with a freshly issued non-fixed VoIP number, pass document verification, and still leave a visible gap in the number itself.
The gap widens after onboarding. Document verification typically runs once, at account opening. Phone-based risk is not static: a number can be ported, disconnected or swapped to a new SIM weeks or months into the relationship, and that event is invisible to a one-time document check.
Where Telebase fits alongside document verification
Query the phone number as soon as it is entered on the form, before the applicant reaches the document upload step. A non-fixed VoIP number or an inactive number is a cheap, fast reason to route the applicant to a closer review, before you spend a document verification credit on them.
Feed the Telebase response into the same decision engine that receives the document verification outcome. A passed document check plus an anomalous carrier or a mismatched country on the phone number is a different risk profile from a passed document check with no phone signal at all. Neither tool needs to know about the other for this to work: they are two independent evidence sources feeding one decision.
Document verification does not re-run itself. Telecom signals can. Re-querying active status and carrier on a schedule, or at high-value events such as a withdrawal or a change of registered number, catches account-lifecycle risk that a one-time document check was never designed to catch. This is also where SIM swap detection is aimed once it is live: a swap event weeks after onboarding is exactly the kind of signal a static document check will always miss.
Example call
The endpoint takes a single E.164 phone number and returns every signal in one response. No separate calls for carrier, number type and active status.
curl -s 'https://telebase.fatcatremote.com/api/lookup?phone=%2B447700900000' \ -H 'Authorization: Bearer tb_live_xxxxxxxxxxxxxxxxxxxxxxxx'
{
"phoneNumber": "+447700900000",
"active": true,
"carrier": "EE",
"country": "GB",
"numberType": "mobile",
"simSwap": "UNKNOWN", // launching for GB, DE, NL and FR
"simSwapAt": null,
"_meta": { "activeSource": "LINE_STATUS" }
}
The phone number is E.164, with the leading plus URL-encoded as %2B. Auth is a bearer token from your dashboard.
Signals available today
Live in every response
- Active status: whether the number is currently reachable on the carrier network, for validating a number at KYC onboarding
- Carrier: the network operator serving the number
- Country: ISO country code of the number, useful when checking it matches the applicant's stated jurisdiction, see GDPR-compliant telecom data for KYC
- Number type: mobile, landline, fixedVoip, nonFixedVoip, tollFree or voicemail
If you are starting from nothing, the quickstart guide walks through the first lookup call end to end.