Skip to content

API reference

Number lookup

Validate a number and see its country, line type, network, risk and cheapest live price. Prefix-based, free.

1 operationBase URL https://packetexchange.io/api/v1Postman collection
BrowseNumber lookup

Look up a phone number

GET/api/v1/lookup/{number}

Access
Key optional. A key or token personalises the answer.
Rate limit
60 requests per minute

Validates and formats an E.164 number and tells you what its prefix is on the exchange: country, line type (mobile, fixed, toll free, premium), the network where the rate decks agree, whether it is a blocked or high-risk destination, and the cheapest live public price to reach it by voice and by SMS (the same logic as GET /routes/price-number).

SMS prices are by destination network where the route prices per network: pricing.sms.network says which network the price is for and pricing.sms.countryRate is the price for other or unknown networks. The network is determined from the number's range (ported numbers may be priced at the network the range belongs to).

Prefix-based. No carrier HLR query is made, so the answer cannot tell you whether the number is in service or has been ported. It is free, needs no key (a scoped key needs routes:read), and is limited to 60 lookups a minute per caller. Send the number in international format (+447700900123 or 00447700900123; spaces and dashes are ignored). A malformed number answers 200 with valid: false and a reason.

Parameters

  • numberrequired

    path · string

Response 200

  • datarequired

    object

  • inputrequired

    string · data.input

    What you sent

  • validrequired

    boolean · data.valid

    Whether the input is a well-formed E.164 number

  • reasonrequired

    string | null · data.reason

    Why it is not valid, when it is not

  • e164required

    string | null · data.e164

    + followed by digits, e.g. +447700900123

  • internationalFormatrequired

    string | null · data.internationalFormat

    +<country code> <rest>, e.g. +44 7700900123

  • countryrequired

    object | null · data.country

  • isorequired

    string | null · data.country.iso

    ISO 3166 alpha-2. null for a shared dial code the decks do not resolve (+1, +7)

  • namerequired

    string · data.country.name

  • dialCoderequired

    string · data.country.dialCode

  • basisrequired

    string · data.country.basis

    rate_decks when the matching destinations name the country; dial_code otherwiseOne of rate_decks, dial_code

  • numberTyperequired

    string · data.numberType

    Inferred from the destination names on the rate decks that match the number (prefix-based, not an HLR query)One of mobile, fixed, toll_free, premium, unknown

  • numberTypeConfidencerequired

    number · data.numberTypeConfidence

    0 to 1: the share of matching decks that agree on numberType

  • operatorrequired

    string | null · data.operator

    The network, only when at least three different sellers' decks name the same one for this prefix. Prefix-based: a ported number keeps its original network here

  • networkrequired

    object | null · data.network

    The mobile network the number's RANGE belongs to, from public number-range data. A ported number keeps its range's network here. null when the range is not known

  • mccMncrequired

    string | null · data.network.mccMnc

    Mobile network code (MCC-MNC), when known, e.g. "234-58"

  • operatorrequired

    string | null · data.network.operator

    The network the number range was allocated to, e.g. "Manx Telecom"

  • sourcerequired

    string · data.network.source

    range = public number-range dataOne of range, hlr

  • matchedPrefixrequired

    string | null · data.matchedPrefix

    The longest dial prefix any live deck matched

  • riskrequired

    object · data.risk

  • blockedrequired

    boolean · data.risk.blocked

    A destination we do not carry (embargoed or platform-blocked)

  • sanctionedrequired

    boolean · data.risk.sanctioned

  • highRiskrequired

    boolean · data.risk.highRisk

    Premium-rate, or a prefix on our high-risk list (satellite, remote and high-cost destinations often abused for revenue-share fraud)

  • reasonsrequired

    string[] · data.risk.reasons

  • pricingrequired

    object · data.pricing

  • voicerequired

    object | null · data.pricing.voice

    The cheapest live public route for the number, or null when none serves it

  • raterequired

    string · data.pricing.voice.rate

    USD, 6 decimals: per minute for voice, per message for SMS

  • currencyrequired

    string · data.pricing.voice.currency

    One of USD

  • unitrequired

    string · data.pricing.voice.unit

    One of min, msg

  • billingIncrementrequired

    string | null · data.pricing.voice.billingIncrement

    e.g. "60/60"; null when the listing does not state one

  • destinationrequired

    string · data.pricing.voice.destination

    The destination the number matched on that route, e.g. "United Kingdom-Mobile"

  • routeIdrequired

    string (uuid) · data.pricing.voice.routeId

    The cheapest public route that serves the number (see GET /routes/{id})

  • routesServingrequired

    integer · data.pricing.voice.routesServing

    How many public routes serve the number

  • network

    object | null · data.pricing.voice.network

    SMS only: the network rate is for, when the route prices per network; null otherwise

  • mccMncrequired

    string | null · data.pricing.voice.network.mccMnc

    Mobile network code (MCC-MNC) the price is for, e.g. "234-10"; null when unknown

  • operatorrequired

    string | null · data.pricing.voice.network.operator

    Network name from public number-range data, e.g. "O2"

  • sourcerequired

    string · data.pricing.voice.network.source

    range = number-range data; none = not determinedOne of range, hlr, none

  • rateBasisrequired

    string · data.pricing.voice.network.rateBasis

    network = that network's own rate; all_operators = the route's rate for networks it does not list separately; country = the route's price for other or unknown networksOne of network, all_operators, country

  • countryRate

    string | null · data.pricing.voice.countryRate

    SMS only: the route's price for other or unknown networks (USD, 6 decimals), when it prices per network

  • smsrequired

    object | null · data.pricing.sms

    The cheapest live public route for the number, or null when none serves it

  • raterequired

    string · data.pricing.sms.rate

    USD, 6 decimals: per minute for voice, per message for SMS

  • currencyrequired

    string · data.pricing.sms.currency

    One of USD

  • unitrequired

    string · data.pricing.sms.unit

    One of min, msg

  • billingIncrementrequired

    string | null · data.pricing.sms.billingIncrement

    e.g. "60/60"; null when the listing does not state one

  • destinationrequired

    string · data.pricing.sms.destination

    The destination the number matched on that route, e.g. "United Kingdom-Mobile"

  • routeIdrequired

    string (uuid) · data.pricing.sms.routeId

    The cheapest public route that serves the number (see GET /routes/{id})

  • routesServingrequired

    integer · data.pricing.sms.routesServing

    How many public routes serve the number

  • network

    object | null · data.pricing.sms.network

    SMS only: the network rate is for, when the route prices per network; null otherwise

  • mccMncrequired

    string | null · data.pricing.sms.network.mccMnc

    Mobile network code (MCC-MNC) the price is for, e.g. "234-10"; null when unknown

  • operatorrequired

    string | null · data.pricing.sms.network.operator

    Network name from public number-range data, e.g. "O2"

  • sourcerequired

    string · data.pricing.sms.network.source

    range = number-range data; none = not determinedOne of range, hlr, none

  • rateBasisrequired

    string · data.pricing.sms.network.rateBasis

    network = that network's own rate; all_operators = the route's rate for networks it does not list separately; country = the route's price for other or unknown networksOne of network, all_operators, country

  • countryRate

    string | null · data.pricing.sms.countryRate

    SMS only: the route's price for other or unknown networks (USD, 6 decimals), when it prices per network

  • methodrequired

    string · data.method

    Always prefix: no carrier network query is madeOne of prefix

  • cachedAtrequired

    string · data.cachedAt

    When this answer was computed. Answers are cached for up to 10 minutes

Errors

  • 400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
  • 401UNAUTHORIZED: missing, invalid, expired or revoked credential.
  • 403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
  • 404NOT_FOUND: no such resource on your account.
  • 429RATE_LIMITED: slow down and retry after the Retry-After seconds.
  • 500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.