lookup

Get a phone number lookup by URL

Performs the same lookup as Create a phone number lookup, with the number in the URL. The response includes the number's serving and issuing networks, porting state, country, and line type. Repeat type to request additional blocks, such as ?type=classification&type=score; only blocks with an ok status incur an additional charge.

Because the number is in the URL, it can appear in proxies, access logs, and browser history. This form does not accept an Idempotency-Key; each retry performs and charges for another lookup.

get/v1/lookup/phone-number/{number}

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/lookup/phone-number/{number}
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Path parameters

numberstring required

The number to look up, in international format. The leading + is optional, and 00 works in its place, so 31612345678 and +31612345678 are the same number, with nothing to percent-encode. If you do send the +, percent-encode it as %2B when your client does not do that for you.

Query parameters

typeLookupProperty[]

An additional data block to request. Repeat the parameter for multiple blocks; each block is billed separately only when its status is ok.

[
  "classification"
]

Headers

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Response

Available network and number-intelligence information.

phone_numberstring required

The number that was looked up, in E.164 format.

country_codestring

ISO 3166-1 alpha-2 country code.

flagsLookupFlag[] required

Notable characteristics of the number. Empty when none apply.

line_type'mobile' | 'fixed_line' | 'voip' | 'toll_free' | 'premium_rate' | 'satellite' | 'pager' | 'payphone' | 'm2m' | 'service' | 'other' | 'unknown' required

What kind of line the number is, as reported by the carrier platform.

This is included in every base lookup, regardless of which properties you request.

  • unknown: the carrier platform holds no classification for the range.
  • other: it holds a classification with no equivalent here.
  • m2m: a range reserved for machine-to-machine traffic, belonging to no individual subscriber.

For the allocated service of the range at finer precision, request the classification property. That answers from a different source, with its own wider vocabulary, and is reported separately so you can always tell the two apart.

Example response

{
  "phone_number": "+441904123456",
  "country_code": "GB",
  "network_info": {
    "carrier_name": "BT",
    "mcc": "234",
    "mnc": "00"
  },
  "original_network_info": null,
  "flags": [],
  "line_type": "service",
  "classification": {
    "status": "ok",
    "value": "premium_rate"
  },
  "score": {
    "status": "ok",
    "value": 48
  },
  "presence": {
    "status": "ok",
    "reachable": true
  },
  "roaming": {
    "status": "unavailable"
  }
}

Changes

No recorded changes to this operation across all 3 revisions of this API.