Developer Guide

Handling every field in the lookup response

Every Telebase lookup returns the same eight fields regardless of the number queried: phoneNumber, active, carrier, country, numberType, simSwap (launching, currently UNKNOWN for GB, DE, NL and FR), simSwapAt and _meta.activeSource. Three of these can be null, and treating null the same as false or an empty string is the most common integration mistake. This page goes through each field, what its possible values mean, and how to handle the null case correctly.

The full response shape

{
  "phoneNumber": "+447700900000",
  "active": true,
  "carrier": "EE",
  "country": "GB",
  "numberType": "mobile",
  "simSwap": "UNKNOWN",
  "simSwapAt": null,
  "_meta": { "activeSource": "LINE_STATUS" }
}

phoneNumber

Echoes back the E.164 number you queried. Always a string, never null. Useful for matching a response back to a request when you are firing lookups asynchronously or in a batch.

active

A three-state field, not a boolean in practice even though it holds boolean values: true means the number is currently reachable on the carrier network, false means it is confirmed unreachable, and null means the provider could not determine reachability at all.

Check _meta.activeSource alongside active to know how much weight to give it, covered below.

carrier

The network operator serving the number, as a string, or null if the carrier could not be determined for that number. A null carrier is worth treating as a data-quality signal in itself for some number ranges, particularly VoIP ranges where carrier attribution is inherently weaker.

country

ISO 3166-1 alpha-2 country code as a string, or null if the number cannot be attributed to a country. Useful for a direct comparison against a country the applicant claims on a form; a mismatch, or a null where a confident match was expected, is worth flagging rather than silently accepting.

numberType

One of six string values: mobile, landline, fixedVoip, nonFixedVoip, tollFree, voicemail. This field does not return null in a successful 200 response. See number type detection for fraud for how to act on each value.

simSwap and simSwapAt

simSwap is one of three strings: SWAPPED, NO_SWAP, or UNKNOWN. UNKNOWN means the upstream provider has no SIM swap data for that number's region or carrier, which is the case for every GB, DE, NL and FR number today while carrier registration completes. simSwapAt is an ISO 8601 timestamp of the most recent detected swap, populated only when simSwap is SWAPPED; it is null in every other case, including UNKNOWN. Do not treat a null simSwapAt as evidence of no swap; check simSwap itself for that.

_meta.activeSource

Tells you how the active value was derived. LINE_STATUS means it came from a live query against the carrier network, a strong signal. VALID means the number only passed format validation and active is inferred rather than confirmed against the network. Soften any decision that depends on active being reliable when activeSource is VALID: an active: true with activeSource: "VALID" is a much weaker claim than the same value with activeSource: "LINE_STATUS".

New to the API? Start with the quickstart guide for the first request end to end.