Search Toll-Free Inventory
Toll-Free (TF) numbers are phone numbers within the US that do not incur costs to the caller.
Note: These phone numbers usually charge the person or business being called.
Use Search TF Inventory to locate toll-free numbers that allow customers to call you for free.
Endpoint and Methods
GET: /_rest/v4/carrier/tf
Parameters
Header
- Accept: application/json
- Authorization: xxxxxxxxxxxxxxxxx
Field | Type | Description |
---|---|---|
Accept | STRING | application/json |
Authorization | STRING | Authorization token (for more information, see Atmosphere® API Authentication) |
Path
Field | Type | Description |
---|---|---|
Like (optional) | E.164 |
All or part of an endpoint to search for:
|
Npa (optional) | NUMERIC |
The NPA (area code) of the desired endpoint(s):
|
Page (optional) | INTEGER |
Which page of results to retrieve:
|
pageSize (optional) | INTEGER |
The quantity of endpoints to return per page:
|
Sequential (optional) | BOOLEAN |
Whether or not the desired endpoints must be sequential (contiguous):
|
Response Example and Schema
Request | Response |
---|---|
NPA | GET /_rest/v4/carrier/tf?npa=888 |
Sequential | GET /_rest/v4/carrier/tf?npa=888&sequential=1&pageSize=20 |
Endpoint 1-100 | GET /_rest/v4/carrier/tf?like=%2B1800 |
Note: The plus symbol must be URI encoded.
Success 200
Field | Type | Description |
---|---|---|
endpoints | ARRAY | A list containing the reserved endpoint(s). |
endpoint | NUMERIC | The e.164 representation of the endpoint. |
geo | OBJECT | Geographical information about the endpoint. |
city | STRING | The endpoint’s city. |
country | STRING | The endpoint’s country. |
stateProvince | STRING | The endpoint’s State/Province. |
hasMore | BOOLEAN |
Whether or not more results are available on the next page. Note: Sequential queries always indicate "hasMore": false. |
Success Response
Copy
HTTP/1.1 200 OK
{
"endpoints": [
{
"endpoint": "+18887293863",
"geo": {
"city": null,
"country": "US",
"stateProvince": null
}
},
{
"endpoint": "+18887293864",
"geo": {
"city": null,
"country": "US",
"stateProvince": null
}
}
],
"hasMore": false
}
Error
Name | Type | Description |
---|---|---|
code | INTEGER | Error code |
error | STRING | Error description |
Code 401 Response
Copy
HTTP/1.1 401 Unauthorized
{
"code": 401,
"error": "Unauthorized"
}
Copy
HTTP/1.1 401 Unauthorized
{
"code": 401,
"error": "Session Expired"
}
Code 406 Response
Copy
HTTP/1.1 406 Not Acceptable
{
"code": 406,
"error": "Not Acceptable"
}
Code 409 Response
Copy
HTTP/1.1 409 Conflict
{
"code": 409,
"error": "The following parameters are mutually exclusive: '%s', '%s'"
}
Code 422 Response
Copy
HTTP/1.1 422 Unprocessable Entity
{
"code": 422,
"error": "At least one of the following parameters is required: 'like', 'npa'"
}
Copy
HTTP/1.1 422 Unprocessable Entity
{
"code": 422,
"error": "The '%s' parameter must be scalar."
}
Copy
HTTP/1.1 422 Unprocessable Entity
{
"code": 422,
"error": "The '%s' parameter must be formatted as a(n) boolean."
}
Copy
HTTP/1.1 422 Unprocessable Entity
{
"code": 422,
"error": "The '%s' parameter must be formatted as a(n) integer."
}
Copy
HTTP/1.1 422 Unprocessable Entity
{
"code": 422,
"error": "The '%s' parameter must be formatted as a(n) numeric."
}
Copy
HTTP/1.1 422 Unprocessable Entity
{
"code": 422,
"error": "The '%s' parameter must be formatted as a(n) string."
}