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
POSThttps://numbers.bandwidth.com/api/v1/accounts/{accountId}/tnlookup
Examples
- Single Number Lookup
- 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"
]
}
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"
}
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
GEThttps://numbers.bandwidth.com/api/v1/accounts/{accountId}/tnlookup/{orderId}
Examples
- IN PROGRESS
- One TN - COMPLETE
- Multiple TNs - COMPLETE
- Multiple TNs - PARTIAL_COMPLETE
- No Information - COMPLETE
- 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": "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": "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"
}
]
}
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"
}
]
}
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"
]
}
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"
}
]
}
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"
]
}