Number Lookup

The current Lookup API is an early release and subject to change. It currently only supports Phone Number Lookup.

Scope

The Number Lookup service provides key information about a phone number, such as type of service, validation, and network information.

Type of service

Type Of Service	Legend	Example
Fixed	The number belongs to a fixed or landline subscription. It likely supports voice but not SMS.	"mcc": "310", "mnc": "", "mccmnc": "310", "operator": "Comcast IP Phone, LLC", "typeOfService": "fixed", "validation": { "valid": true }
Mobile	The number belongs to the Mobile Network active number range. It likely support both voice and SMS and to be own by a physical individual.	"mcc": "310", "mnc": "010", "mccmnc": "310010", "operator": "Verizon Wireless", "typeOfService": "mobile", "validation": { "valid": true }
Other	The Number belongs to Other providers, such as, but not limited to, Premium Services, Toll-Free Numbers, Virtual Numbers, M2M or IOT, etc. Although such number may support both Voice and SMS are more likely own by corporation then an individuals.	"mcc": "310", "mnc": "", "mccmnc": "310", "operator": "Onvoy, LLC - AL", "typeOfService": "other", "validation": { "valid": true }

Validation

Indicating if the queried number is valid as correctly formed and associated with an active phone number range. An invalid number answer will include a reason field with more details.

Bird's Lookup does not return the live status of the numbers. Lookup validation occurs only for number format, allocation, and type. Valid numbers may be inactive (not associated with active contract lines) or absent (temporarily out of any carrier coverage) and may fail to receive calls or SMS.

Invalid Validation Example

[...],
"validation": {
    "valid": false,
    "reason": ["unallocated"|"special services"|"unknown"]
}

Network Data

Providing details about the network the number belongs to. Information will be provided in two formats:

• Via a Numeric country (MCC : Mobile Country Code) and network (MNC: Mobile Network Code) code. This is an immutable identifier linked to the carrier telecom license and the best indicator of a network identity

• Via a human-readable name, this is subject to change following carrier rebranding and/or corporate actions.

Lookup Rate Limit

Excessive HTTP requests will be rejected with the 429 Too Many Requests status code. When you receive a 429 response, you can safely assume the request has not been processed and can be retried later. Please reduce the rate of your requests and try the request again later.

Our default per workspace limit (all API keys in a given workspace) is 50 Lookup Requests per second

Please get in touch with support if you need higher limits.

API Reference Guide

1. Network/Country information for a phone number