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, active status and SIM swap detection. For a worked example of how these signals fit a digital-bank flow, see phone intelligence for neobank onboarding.
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://api.telebase.io/lookup?phone=%2B447700900000' \ -H 'Authorization: Bearer tb_live_xxxxxxxxxxxxxxxxxxxxxxxx'
{
"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" }
}
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.
Request early access