Skip to Content
OpenRoam Docs
Airtime

Look up a phone number

Describes a phone number and returns its carrier from a carrier lookup when the number is valid.

GET
/v1/airtime/number-lookup

Describes a phone number and returns its carrier from a carrier lookup when the number is valid.

Describes the number from numbering-plan data and, for a valid number, adds carrier information from a live carrier lookup. A number without the international shape gives 400 / 10001; a number its country does not assign returns 200 with isValid: false and carrier: null, without a carrier lookup. Returns 503 / 10007 when the carrier lookup is unavailable. The carrier is for display only and nothing is stored; use search to find a sellable operator.

Authorization

PartnerApiKey
headerX-Partner-Key<token>

Partner API Key (X-Partner-Key)

Query Parameters

phoneNumber*string

The number in international format, starting with + or 00; spaces, hyphens and parentheses are allowed.

Response Body

OK

  1. response

What a phone number's own digits say about it, from numbering-plan data, plus carrier data from a carrier lookup. phoneNumber is the number in E.164. isValid is false when the digits do not form a number its country assigns; the other fields then hold whatever could still be read, and lineType is unknown. countryCode is ISO 3166-1 alpha-2, null when the number belongs to no single country. dialCode is the calling code with its leading plus. The formats are for display only. carrier comes from a carrier lookup made only for a valid number; it is null for an invalid one.

phoneNumber*string
isValid*boolean
countryCode?string|null
dialCode*string
nationalNumber*string
internationalFormat*string
nationalFormat*string
lineType*string
Value in"unknown""mobile""fixedLine""fixedLineOrMobile""tollFree""premiumRate""sharedCost""voip""personalNumber""pager""uan""voicemail"
carrier?|

Carrier information from the number lookup. name may identify the original number-block owner when portability data is unavailable; it does not guarantee the current carrier after porting. normalizedName is the reported parent network when known. lineType is the carrier's view of the line. isPorted is null when the lookup does not say, which is common outside the US. For display only: the operator OpenRoam sells for a number comes from search.

Example Request
curl -X GET 'https://api.sandbox.openroam.com/v1/airtime/number-lookup?phoneNumber=%2B994501234567'
Example Response
{  "phoneNumber": "string",  "isValid": true,  "countryCode": "string",  "dialCode": "string",  "nationalNumber": "string",  "internationalFormat": "string",  "nationalFormat": "string",  "lineType": "unknown",  "carrier": {    "name": "string",    "normalizedName": "string",    "lineType": "unknown",    "isPorted": true  }}