Developer Quickstart

Your first lookup in five minutes

Telebase has one endpoint. You pass a phone number in E.164 format, include your Bearer token, and get back carrier, country, number type, active status and a SIM swap field in a single JSON response. No SDK, no webhooks, no configuration. This page walks from account access to a working query in under five minutes.

Before you start

You need an API key. New accounts start in the sandbox with test keys. Request access at telebase.io/contact-us and we will set up your account. Test keys start with tb_test_ and live keys with tb_live_; live keys are switched on after a short review.

Step 1: make your first request

Replace tb_live_xxxxxxxxxxxxxxxxxxxxxxxx with your key. The phone number must be E.164, with the leading + URL-encoded as %2B.

curl -s 'https://api.telebase.io/lookup?phone=%2B447700900000' \
  -H 'Authorization: Bearer tb_live_xxxxxxxxxxxxxxxxxxxxxxxx'

That is the complete request. No body, no extra headers, no query parameters beyond phone.

Step 2: read the response

{
  "phoneNumber": "+447700900000",
  "active": true,            // boolean or null
  "carrier": "EE",             // string or null
  "country": "GB",             // ISO 3166-1 alpha-2
  "numberType": "mobile",      // mobile | landline | fixedVoip | nonFixedVoip | tollFree | voicemail
  "simSwap": "UNKNOWN",       // SWAPPED | NO_SWAP | UNKNOWN (live in the UK and Germany, more markets to follow)
  "simSwapAt": null,           // ISO 8601 timestamp when simSwap is SWAPPED, else null
  "_meta": {
    "activeSource": "LINE_STATUS"  // LINE_STATUS (strong) or VALID (format check only)
  }
}

Understanding the fields

The one gotcha: URL-encoding the +

All phone numbers must be in E.164 format, which means a leading + followed by the country code and number with no spaces or dashes. When you pass the number as a query string parameter, the + must be URL-encoded as %2B. A raw + in a URL is interpreted as a space, which will cause a lookup failure or an unexpected result.

?phone=%2B447700900000

?phone=+447700900000

If you are constructing the URL in code, use your language's URL encoding function rather than building the string manually. Use the free E.164 formatter to convert any number instantly, or see the phone number validation guide for more on E.164 formatting, or MSISDN, IMSI and ICCID explained for how the E.164 number you send relates to the identifiers stored on the subscriber's SIM.

What a non-200 response looks like

A 401 means your key is missing or malformed. Check that the Authorization header reads exactly Bearer tb_live_... with a space between Bearer and the key, and no extra characters.

A 400 means the phone number failed validation. Common causes: missing country code, raw + rather than %2B, or a number that is too short or too long to be valid E.164.

A 402 means your account balance is at zero. Top up via the dashboard.

A 200 with "active": null is not an error. It means the carrier returned data for the number but could not confirm reachability. _meta.activeSource will be VALID in this case.

What to build next

The most common integration point for fraud and KYC teams is immediately after a user submits their phone number at onboarding or login. The check is synchronous and designed to run inline in your onboarding flow before the next step renders.

• Flag nonFixedVoip numbers before proceeding to document verification. See number type detection for fraud.
• Hold any flow where active is false for a number that should be active.
• When simSwap goes live for your market, add a recency check: if simSwap is SWAPPED and simSwapAt is within your risk window, step up to a harder verification method. See the SIM swap detection API for the full integration pattern.

The full machine-readable API guide is at telebase.io/skills-md and covers authentication, the complete response schema, error codes and usage examples in multiple languages.