Skip to main content

How to use phone number lookup

A guide that walks through the Bandwidth API to provide carrier information for a telephone number or batch of telephone numbers.

Currently, this service supports lookups of telephone numbers in the mainland United States, Alaska, Hawaii, District of Columbia, and the provinces of Canada. Telephone numbers submitted must be in E.164 format to be processed.

Submit Number Lookup Request

To start the process of looking up information for a phone number, make a POST request to the Create Lookup Request API endpoint.

Use one of the examples to create Single Number Lookup request. This can be done through tools like Postman or cURL.

Examples:

Response

HTTP/1.1 202 Accepted
Content-Type: application/json

{
"requestId": "004223a0-8b17-41b1-bf81-20732adf5590",
"status": "IN_PROGRESS"
}

Fetch Request Information

Since the TN Lookup request processing is asynchronous, make a GET request to our Get Lookup Request Status API endpoint to determine the status. This can be done through tools like Postman or cURL.

Examples:

Request URL

GET https://numbers.bandwidth.com/api/v1/accounts/{accountId}/tnlookup/{requestId}

curl 'https://numbers.bandwidth.com/api/v1/accounts/{accountId}/tnlookup/{requestId}'
-u '{userName}:{password}'

Status Information Displayed in the Response Body

As indicated in the response body, the status for single phone number requests can be 'IN_PROGRESS', 'COMPLETE', or 'FAILED'. In addition to these statuses, multiple phone number requests can also be in a 'PARTIAL_COMPLETE' state. 'COMPLETE', 'PARTIAL_COMPLETE', and 'FAILED' are terminal states, indicating that the request has finished processing. Refer to the examples below of responses for each of the possible statuses.

HTTP/1.1 200 OK
Content-Type: application/json

{
"requestId": "004223a0-8b17-41b1-bf81-20732adf5590",
"status": "IN_PROGRESS"
}

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: