Developers
Caching and cost control for per-query APIs
Telebase bills per successful lookup, so the cheapest query is the one you do not repeat unnecessarily. Carrier and number type change rarely and can be cached safely for a period. Active status and SIM swap reflect live network state and should not be cached. The biggest cost lever is not caching at all: it is only querying at moments that actually carry decision weight.
What is safe to cache, and for how long
carrier and numberType describe properties of the number itself rather than its live network state. A number stays with the same carrier until the subscriber ports it, and its type (mobile, landline, fixed VoIP, non-fixed VoIP, toll-free or voicemail) essentially never changes. Both are safe to cache against the normalised E.164 number for a meaningful period, days to weeks depending on how porting-sensitive your use case is, rather than re-querying on every event. See the full field reference for how each field behaves.
What you should not cache
- active: reflects whether the number is currently reachable on the network right now. A cached "active" result from last week tells you nothing about this session.
- simSwap: is a recency signal by definition. A cached SIM swap result is worse than no result at all, because it can hide a swap that happened after the cache was written. SIM swap detection is launching for GB, DE, NL and FR and currently returns
UNKNOWNfor those markets; see the SIM swap API reference. Never cache this field once it is live for your market.
Query at trust boundaries, not on every request
The largest cost reduction usually has nothing to do with caching: it comes from deciding when a lookup is actually worth doing. A lookup at account creation, before enabling SMS as a second factor, or immediately before a high-value transaction is authorised, carries real decision weight. A lookup on every page load or every API call from an already-verified session usually does not.
Query once, at sign-up, and cache the carrier and number type result against the account.
Avoid re-querying on routine logins. Reserve fresh lookups for moments where the phone number's current state actually changes the decision.
Query fresh, uncached, immediately before actions like a password reset, a new device enrolment or a payment authorisation, where a stale result defeats the point of the check.
Deduplicate before you call
Two representations of the same number, with and without a leading zero, with and without spaces, should resolve to one cache key. Normalise to E.164 first (see E.164 formatting and URL encoding), then check your cache, then call the API only on a miss. This alone removes a meaningful share of duplicate calls in most signup and retry flows.
This matters even more for an autonomous caller. An AI agent given a Telebase lookup as a callable tool can retry or re-invoke a tool call more freely than a human-triggered request path, so the same cache and dedupe layer should sit in front of the API regardless of whether a person or an agent triggered the call. See giving AI agents phone intelligence tools.