Number Lookup Service

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 Order

Request URL

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

Examples

Single Number Lookup

Request

POST https://numbers.bandwidth.com/api/v1/accounts/{accountId}/tnlookup HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

{
  "tns": [
    "19196104423"
  ]
}

Response

HTTP 202 Accepted
Content-Type: application/json
Location: https://numbers.bandwidth.com/api/v1/accounts/9999999/tnlookup/004223a0-8b17-41b1-bf81-20732adf5590

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

Multiple Number Lookup

Request

POST https://numbers.bandwidth.com/api/v1/accounts/{accountId}/tnlookup HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

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

Response

HTTP 202 Accepted
Content-Type: application/json
Location: https://numbers.bandwidth.com/api/v1/accounts/9999999/tnlookup/004223a0-8b17-41b1-bf81-20732adf5590

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

Fetch Order Information

Request URL

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

Examples

IN PROGRESS

Request

GET https://numbers.bandwidth.com/api/v1/accounts/{accountId}/tnlookup/{orderId} HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

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

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

One TN - COMPLETE

Request

GET https://numbers.bandwidth.com/api/v1/accounts/{accountId}/tnlookup/{orderId} HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

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 - COMPLETE

Request

GET https://numbers.bandwidth.com/api/v1/accounts/{accountId}/tnlookup/{orderId} HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

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"
    }
  ]
}

Multiple TNs - PARTIAL_COMPLETE

Request

GET https://numbers.bandwidth.com/api/v1/accounts/{accountId}/tnlookup/{orderId} HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

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"
  ]
}

No Information - COMPLETE

Request

GET https://numbers.bandwidth.com/api/v1/accounts/{accountId}/tnlookup/{orderId} HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

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"
    }
  ]
}

FAILED

Request

GET https://numbers.bandwidth.com/api/v1/accounts/{accountId}/tnlookup/{orderId} HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

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

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