Search TF Inventory

Toll-Free (TF)

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.

Search TF Inventory

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 (see Authenticate)

 

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:

 

Note: This parameter is ignored for sequential queries.

 

  • Must be scalar.

 

Default value: 1

 

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

 

Note: The plus symbol must be URI encoded.

GET /_rest/v4/carrier/tf?like=%2B1800
 
 
Success 200

Field

Type

Description

endpoints

Array

An array of endpoints matching the search terms.

 

endpoint

Numeric

The e.164 representation of the endpoint.

 

geo

Object

Geographical information about the endpoint.

 

city

Null

The endpoint’s city.

 

country

String

The endpoint’s country (2-char abbreviation).

 

stateProvince

Null

The endpoint’s state/province.

 

hasMore

Boolean

Whether or not more results are available on the next page.

 

Note: Sequential queries will always indicate “hasMore”: false.

 
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

}

Name

Type

Description

code
Integer

Error code

 

error
String

Error description

HTTP/1.1 401 Unauthorized

{

    "code": 401,

    "error": "Unauthorized"

}

HTTP/1.1 401 Unauthorized

{

    "code": 401,

    "error": "Unauthorized"

}

HTTP/1.1 401 Unauthorized

{

    "code": 401,

    "error": "Session Expired"

}
HTTP/1.1 406 Not Acceptable

{

    "code": 406,

    "error": "Not Acceptable"

}
HTTP/1.1 409 Conflict

{

    "code": 409,

    "error": "The following parameters are mutually exclusive: '%s', '%s'"

}
HTTP/1.1 422 Unprocessable Entity

{

    "code": 422,

    "error": "At least one of the following parameters is required: 'like', 'npa'"

}

HTTP/1.1 422 Unprocessable Entity

{

    "code": 422,

    "error": "The '%s' parameter must be scalar."

}

HTTP/1.1 422 Unprocessable Entity

{

    "code": 422,

    "error": "The '%s' parameter must be formatted as a(n) boolean."

}

HTTP/1.1 422 Unprocessable Entity

{

    "code": 422,

    "error": "The '%s' parameter must be formatted as a(n) integer."

}

HTTP/1.1 422 Unprocessable Entity

{

    "code": 422,

    "error": "The '%s' parameter must be formatted as a(n) numeric."

}

HTTP/1.1 422 Unprocessable Entity

{

    "code": 422,

    "error": "The '%s' parameter must be formatted as a(n) string."

}