How to use phone number lookup
Example Usage
A guide that walks through the Bandwidth API to provide carrier information for a telephone number or batch of telephone numbers.
Currently supports lookups of telephone numbers in the mainland United States, Alaska, Hawaii, the District of Columbia, and Canada. Voice and messaging provider information is not available for Canadian numbers. Telephone numbers submitted must be in E.164 format to be processed.
PLEASE NOTE: The NPA-NXX associated with an LRN and/or any derived or associated carrier information may only be used by non-NPAC users for the purposes of Rating, Routing, Billing and Network Maintenance as defined in NPAC US Permitted Use Clarifications. Any other uses are expressly restricted.
Determine which Number Lookup endpoint to use: Asynchronous vs Synchronous
Use the asynchronous “bulk” lookup endpoint when processing thousands of phone numbers. This is ideal for routine batch processing, such as weekly or monthly lookups of large number inventories. Use the synchronous "fast" lookup endpoint when looking up 100 or fewer numbers in a workflow that must wait for the response before proceeding. For example, this can be used when validating a user’s phone number during two-factor authentication setup.
Submit Number Lookup Request
- v2
To start the process of looking up information for a phone number, make a POST request to the Create Lookup Request API endpoint.
- Synchronous "Fast" Number Lookup
- Asynchronous "Bulk" Number Lookup
Use this example to get carrier info for up to 100 phone numbers per request. The request is synchronous, so you will get the results back directly in the response. Examples are provided for cURL or your API client of choice (Postman, Bruno, etc).
Examples:
- Payload
- cURL
https://api.bandwidth.com/v2/accounts/{accountId}/phoneNumberLookup{
"phoneNumbers": ["+19192475417", "+12029331234"]
}
curl -X POST 'https://api.bandwidth.com/v2/accounts/{accountId}/phoneNumberLookup'
-u '{userName}:{password}'
-H 'Content-Type: application/json'
-d '{
"phoneNumbers": [
"+19192475417",
"+12029331234"
]
}'
Status Information Displayed in the Response Body
The status for a sync phone number lookup can be 'IN_PROGRESS', 'COMPLETE', 'PARTIAL_COMPLETE', or 'FAILED'. The states 'COMPLETE', 'PARTIAL_COMPLETE', and 'FAILED' are terminal, indicating that the request has finished processing. Refer to the examples below of responses for each possible status.
- COMPLETE
- PARTIAL_COMPLETE
- FAILED
HTTP/1.1 200 OK
Content-Type: application/json
{
"links": [
{
"href": "href",
"method": "GET",
"rel": "rel"
}
],
"data": {
"requestId": "004223a0-8b17-41b1-bf81-20732adf5590",
"status": "COMPLETE",
"results": [
{
"phoneNumber": "+19192475417",
"countryCodeA3": "USA",
"lineType": "MOBILE",
"messagingProvider": "T-MOBILE USA INC",
"voiceProvider": "T-MOBILE USA INC"
},
{
"phoneNumber": "+12029331234",
"countryCodeA3": "USA",
"lineType": "VOIP",
"messagingProvider": "Twilio - SMS/MMS-SVR",
"voiceProvider": "TWILIO INTERNATIONAL, INC."
}
]
},
"errors": []
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"links": [
{
"href": "href",
"method": "GET",
"rel": "rel"
}
],
"data": {
"requestId": "004223a0-8b17-41b1-bf81-20732adf5590",
"status": "PARTIAL_COMPLETE",
"results": [
{
"phoneNumber": "+19192475417",
"countryCodeA3": "USA",
"lineType": "MOBILE",
"messagingProvider": "T-MOBILE USA INC",
"voiceProvider": "T-MOBILE USA INC"
}
]
},
"errors": [
{
"code": "NO-MATCH",
"description": "The following TNs could not be found in the Number Industry data",
"meta": {
"phoneNumbers": [
"+12029331234"
],
"message" : "Invalid TNs",
"code": 1001
},
"type": "NumberInventory"
}
]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"links": [
{
"href": "href",
"method": "GET",
"rel": "rel"
}
],
"data": {
"requestId": "004223a0-8b17-41b1-bf81-20732adf5590",
"status": "FAILED",
"results": []
},
"errors": [
{
"code": "NO-MATCH",
"description": "The following TNs could not be found in the Number Industry data",
"meta": {
"phoneNumbers": [
"+19192475417",
"+12029331234"
],
"message": "Invalid TNs",
"code": 1001
},
"type": "NumberInventory"
}
]
}
Use this example to get carrier info for up to 15000 phone numbers per request. The request is asynchronous, so you will be returned a requestId that can be used to fetch the results. Examples are provided for cURL or your API client of choice (Postman, Bruno, etc).
Examples:
- Payload
- cURL
https://api.bandwidth.com/v2/accounts/{accountId}/phoneNumberLookup/bulk{
"phoneNumbers": ["+19192475417", "+12029331234"]
}
curl -X POST 'https://api.bandwidth.com/v2/accounts/{accountId}/phoneNumberLookup/bulk'
-u '{userName}:{password}'
-H 'Content-Type: application/json'
-d '{
"phoneNumbers": [
"+19192475417",
"+12029331234"
]
}'
Status Information Displayed in the Response Body
The status for an async phone number lookup will always be 'IN_PROGRESS'. Refer to the example below.
- IN_PROGRESS
HTTP/1.1 200 OK
Content-Type: application/json
{
"links": [
{
"href": "href",
"method": "GET",
"rel": "rel"
}
],
"data": {
"requestId": "004223a0-8b17-41b1-bf81-20732adf5590",
"status": "IN_PROGRESS"
"results": []
},
"errors": []
}
Fetch Number Lookup Request
- v2
When making an asynchronous TN Lookup request, make a GET request to our Get Lookup Request Status API endpoint to determine the status and see the results. This can be done through tools like Postman or cURL.
Examples:
Request URL
GEThttps://api.bandwidth.com/v2/accounts/{accountId}/phoneNumberLookup/bulk/{requestId}- cURL
curl 'https://api.bandwidth.com/v2/accounts/{accountId}/phoneNumberLookup/bulk/{requestId}'
-u '{userName}:{password}'
-H 'Content-Type: application/json'
Status Information Displayed in the Response Body
The status for retrieving a phone number request can be 'IN_PROGRESS', 'COMPLETE', 'PARTIAL_COMPLETE', or 'FAILED'. The states 'COMPLETE', 'PARTIAL_COMPLETE', and 'FAILED' are terminal, indicating that the request has finished processing. Refer to the examples below of responses for each possible status.
- IN_PROGRESS
- COMPLETE
- PARTIAL_COMPLETE
- FAILED
HTTP/1.1 200 OK
Content-Type: application/json
{
"links": [
{
"href": "href",
"method": "GET",
"rel": "rel"
}
],
"data": {
"requestId": "004223a0-8b17-41b1-bf81-20732adf5590",
"status": "IN_PROGRESS",
"results": []
},
"errors": []
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"links": [
{
"href": "href",
"method": "GET",
"rel": "rel"
}
],
"data": {
"requestId": "004223a0-8b17-41b1-bf81-20732adf5590",
"status": "COMPLETE",
"results": [
{
"phoneNumber": "+19192475417",
"countryCodeA3": "USA",
"lineType": "MOBILE",
"messagingProvider": "T-MOBILE USA INC",
"voiceProvider": "T-MOBILE USA INC"
},
{
"phoneNumber": "+12029331234",
"countryCodeA3": "USA",
"lineType": "VOIP",
"messagingProvider": "Twilio - SMS/MMS-SVR",
"voiceProvider": "TWILIO INTERNATIONAL, INC."
}
]
},
"errors": []
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"links": [
{
"href": "href",
"method": "GET",
"rel": "rel"
}
],
"data": {
"requestId": "004223a0-8b17-41b1-bf81-20732adf5590",
"status": "PARTIAL_COMPLETE",
"results": [
{
"phoneNumber": "+19192475417",
"countryCodeA3": "USA",
"lineType": "MOBILE",
"messagingProvider": "T-MOBILE USA INC",
"voiceProvider": "T-MOBILE USA INC"
}
]
},
"errors": [
{
"code": "NO-MATCH",
"description": "The following TNs could not be found in the Number Industry data",
"meta": {
"phoneNumbers": [
"+12029331234"
],
"message" : "Invalid TNs",
"code": 1001
},
"type": "NumberInventory"
}
]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"links": [
{
"href": "href",
"method": "GET",
"rel": "rel"
}
],
"data": {
"requestId": "004223a0-8b17-41b1-bf81-20732adf5590",
"status": "FAILED",
"results": []
},
"errors": [
{
"code": "NO-MATCH",
"description": "The following TNs could not be found in the Number Industry data",
"meta": {
"phoneNumbers": [
"+19192475417",
"+12029331234"
],
"message": "Invalid TNs",
"code": 1001
},
"type": "NumberInventory"
}
]
}
Where to next?
Now that you have learned how to lookup information for phone numbers, check out some of the other available actions in our guides: