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

v1

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

Single Number Lookup

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

Examples:

Payload

POSThttps://numbers.bandwidth.com/api/v1/accounts/{accountId}/tnlookup

{
  "tns": ["+19196104423"]
}

cURL

  curl -X POST 'https://numbers.bandwidth.com/api/v1/accounts/{accountId}/tnlookup'
  -u '{userName}:{password}'
  -H 'Content-Type: application/json'
  -d '{
    "tns": [
      "+19196104423"
    ]
  }'

Response

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

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

Multiple Number Lookup

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

Examples:

Payload

POSThttps://numbers.bandwidth.com/api/v1/accounts/{accountId}/tnlookup

{
  "tns": ["+19196104423", "+19196104424"]
}

cURL

curl -X POST 'https://numbers.bandwidth.com/api/v1/accounts/{accountId}/tnlookup'
-u '{userName}:{password}'
-H 'Content-Type: application/json'
-d '{
"tns": [
"+19196104423",
"+19196104424"
]
}'

Response

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

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

v2

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

Single Number Lookup

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

Examples:

Payload

POSThttps://numbers.bandwidth.com/api/v2/accounts/{accountId}/lookup/bulk

{
  "phoneNumbers": ["+19196104423"]
}

cURL

curl -X POST 'https://numbers.bandwidth.com/api/v2/accounts/{accountId}/lookup/bulk'
-u '{userName}:{password}'
-H 'Content-Type: application/json'
-d '{
"phoneNumbers": [
"+19196104423"
]
}'

Response

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

{
  "links": []
  "data": {
    "requestId": "004223a0-8b17-41b1-bf81-20732adf5590",
    "status": "IN_PROGRESS"
  }
  "errors": []
}

Multiple Number Lookup

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

Examples:

Payload

POSThttps://numbers.bandwidth.com/api/v2/accounts/{accountId}/lookup/bulk

{
  "phoneNumbers": ["+19196104423", "+19196104424"]
}

cURL

curl -X POST 'https://numbers.bandwidth.com/api/v2/accounts/{accountId}/lookup/bulk'
-u '{userName}:{password}'
-H 'Content-Type: application/json'
-d '{
"phoneNumbers": [
"+19196104423",
"+19196104424"
]
}'

Response

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

{
  "links": []
  "data":
  {
    "requestId": "004223a0-8b17-41b1-bf81-20732adf5590",
    "status": "IN_PROGRESS"
  }
  "errors": []
}

Fetch Request Information

v1

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

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

cURL

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.

IN_PROGRESS

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

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

COMPLETE

One TN

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

{
  "requestId": "004223a0-8b17-41b1-bf81-20732adf5590",
  "status": "COMPLETE",
  "result": [
{
  "Response Code": 0,
  "Message": "NOERROR",
  "E.164 Format": "+19196104424",
  "Formatted": "(919) 610-4424",
  "Country": "US",
  "Line Type": "Mobile",
  "Line Provider": "T-Mobile USA",
  "Mobile Country Code": "310",
  "Mobile Network Code": "160"
}
  ]
}

Multiple TNs

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

{
  "requestId": "004223a0-8b17-41b1-bf81-20732adf5590",
  "status": "COMPLETE",
  "result": [
{
  "Response Code": 0,
  "Message": "NOERROR",
  "E.164 Format": "+19196104424",
  "Formatted": "(919) 610-4424",
  "Country": "US",
  "Line Type": "Mobile",
  "Line Provider": "T-Mobile USA",
  "Mobile Country Code": "310",
  "Mobile Network Code": "160"
},
{
  "Response Code": 0,
  "Message": "NOERROR",
  "E.164 Format": "+19196104423",
  "Formatted": "(919) 610-4423",
  "Country": "US",
  "Line Type": "Mobile",
  "Line Provider": "Verizon Wireless",
  "Mobile Country Code": "310",
  "Mobile Network Code": "010"
}
  ]
}

No Information

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

{
  "requestId": "004223a0-8b17-41b1-bf81-20732adf5590",
  "status": "COMPLETE",
  "result": [
{
  "Response Code": 3,
  "Message": "NXDOMAIN",
  "E.164 Format": "+19196104425",
  "Formatted": "(919) 610-4425",
  "Country": "US"
}
  ]
}

PARTIAL_COMPLETE

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

{
  "requestId": "004223a0-8b17-41b1-bf81-20732adf5590",
  "status": "PARTIAL_COMPLETE",
  "result": [
{
  "Response Code": 0,
  "Message": "NOERROR",
  "E.164 Format": "+19196104424",
  "Formatted": "(919) 610-4424",
  "Country": "US",
  "Line Type": "Mobile",
  "Line Provider": "T-Mobile USA",
  "Mobile Country Code": "310",
  "Mobile Network Code": "160"
}
  ],
  "failedTelephoneNumbers": [
  "+13992077164"
  ]
}

FAILED

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

{
  "requestId": "004223a0-8b17-41b1-bf81-20732adf5590",
  "status": "FAILED",
  "failedTelephoneNumbers": [
  "+13992077164"
  ]
}

v2

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

GEThttps://numbers.bandwidth.com/api/v2/accounts/{accountId}/lookup/bulk/{requestId}

cURL

curl 'https://numbers.bandwidth.com/api/v2/accounts/{accountId}/lookup/bulk/{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.

IN_PROGRESS

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

{
  "links": []
  "data": {
    "requestId": "004223a0-8b17-41b1-bf81-20732adf5590",
    "status": "IN_PROGRESS"
  }
  "errors": []
}

COMPLETE

One TN

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

{
  "links": []
  "data": {
    "requestId": "004223a0-8b17-41b1-bf81-20732adf5590",
    "status": "COMPLETE",
    "result": [
      {
        "phoneNumber": "+19196104424",
        "lineType": "Mobile",
        "messagingProvider": "T-Mobile USA",
        "voiceProvider": "T-Mobile USA"
      }
    ]
  }
  "errors": []
}

Multiple TNs

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

{
  "links": [],
  "data": {
    "requestId": "004223a0-8b17-41b1-bf81-20732adf5510",
    "status": "COMPLETE",
    "results": [
      {
        "phoneNumber": "+19196104424",
        "lineType": "Mobile",
        "messagingProvider": "T-Mobile USA",
        "voiceProvider": "T-Mobile USA"
      },
      {
        "phoneNumber": "+19196104423",
        "lineType": "Mobile",
        "messagingProvider": "Verizon Wireless",
        "voiceProvider": "Verizon Wireless"
      }
    ]
  },
  "errors": []
}

No Information

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

{
  "links": [],
  "data": {
    "requestId": "004223a0-8b17-41b1-bf81-20732adf5510",
    "status": "COMPLETE",
    "results": [
      {
      "phoneNumber": "+19196104424"
      }
    ]
  },
  "errors": []
}

PARTIAL_COMPLETE

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

{
  "links": []
  "data": {
    "requestId": "004223a0-8b17-41b1-bf81-20732adf5590",
    "status": "PARTIAL_COMPLETE",
    "results": [
      {
        "phoneNumber": "+19196104424",
        "lineType": "Mobile",
        "messagingProvider": "T-Mobile USA",
        "voiceProvider": "T-Mobile USA"
      },
      {
        "phoneNumber": "+19196104423",
        "lineType": "Mobile",
        "messagingProvider": "Verizon Wireless",
        "voiceProvider": "Verizon Wireless"
      }
    ]
  }
  "errors": [
    {
      "type": "invalid-phone-number",
      "description": "Phone number is not valid",
      "code": "",
      "source": {
        "phoneNumbers": ["+13992077164", "+19196114420"]
      }
    }
  ]
}

FAILED

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

{
  "links": []
  "data": {
    "requestId": "004223a0-8b17-41b1-bf81-20732adf5590",
    "status": "FAILED",
    "results": []
  }
  "errors": [
    {
      "type": "invalid-phone-number"
      "description": "Phone number is not valid"
      "code": ""
      "source": {
        "phoneNumbers": ["+13992077164", "+19196114420"]
      }
    }
  ]
}

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:

• How to order numbers