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:

  • Either like or npa is required.
  • Must be scalar.
  • Mutually exclusive with sequential.
Npa (optional) NUMERIC

The NPA (area code) of the desired endpoint(s):

  • Either like or npa is required.
  • Must be scalar.
Page (optional) INTEGER

Which page of results to retrieve:

  • Must be scalar.
  • Default value: 1
  • Note: This parameter is ignored for sequential queries.
pageSize (optional) INTEGER

The quantity of endpoints to return per page:

  • Between 1 and 250.
  • Must be scalar.
  • Default value: 100
Sequential (optional) BOOLEAN

Whether or not the desired endpoints must be sequential (contiguous):

  • Sequential searches are limited to a maximum pageSize of 100.
  • Requires npa and pageSize.
  • May cause more than pageSize records to be returned.
  • Must be scalar.
  • Allowed values: 0, 1

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."

}