Toll-Free Number Management

Overview

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.

Click the subject name to view the associated API request information.

Base URL

All of the following endpoints share the same base URL: https://customer.intelepeer.com (for example, POST https://customer.intelepeer.com/_rest/v4/carrier/tf).

Search IntelePeer Toll-Free Inventory

Use Search_TF_Inventory to locate toll-free numbers in the IntelePeer inventory that allow customers to call you for free.

Method and Endpoint

GET /_rest/v4/carrier/tf

Header

Accept: application/json
Authorization: xxxxxxxxxxxxxxxxx
Content-Type: application/json

Field	Type	Description
Accept	STRING	application/json
Authorization	STRING	Authorization token (for more information, see Atmosphere API Authentication)
Content-Type	STRING	application/json

Parameters

Field	Type	Description
like	E.164	(optional) All or part of an endpoint to search for Either like or npa is required Must be scalar Mutually exclusive with sequential
npa	NUMERIC[]	(optional) The NPA (area code) of the desired endpoint(s) Either like or npa is required. Must be scalar.
page	INTEGER	(optional) Which page of results to retrieve Must be scalar Default value: 1 Note: This parameter is ignored for sequential queries
pageSize	INTEGER	(optional) The quantity of endpoints to return per page Between 1 and 250 Must be scalar Default value: 100
sequential	BOOLEAN	(optional) 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-800	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 endpoin.
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

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

HTTP/1.1 401 Unauthorized
{
	"code": 401,
	"error": "Unauthorized"
}

HTTP/1.1 401 Unauthorized
{
	"code": 401,
	"error": "Session Expired"
}

Code 406 Response

HTTP/1.1 406 Not Acceptable
{
	"code": 406,
	"error": "Not Acceptable"
}

Code 409 Response

HTTP/1.1 409 Conflict
{
	"code": 409,
	"error": "The following parameters are mutually exclusive: '%s', '%s'"
}

Code 422 Response

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

Toll-Free List or Search of Your Inventory

Use TF_Management to enumerate and search your toll-free inventory of numbers.

Note: When more records are available on the next page, the API returns pageSize + 1 records.

Method and Endpoint

GET /_rest/v3/my/tf

Header

Accept: application/json
Authorization: xxxxxxxxxxxxxxxxx
Content-Type: application/json

Field	Type	Description
Accept	STRING	application/json
Authorization	STRING	Authorization token (for more information, see Atmosphere API Authentication)
Content-Type	STRING	application/json

Parameters

Field	Type	Description
label	STRING	(optional) The label of the desired number(s)
like	STRING	(optional) An alpha-numeric string to search for A single value performs a "starts-with" search Multiple values perform an exact match for each name
packageID	INTEGER	(optional) The package ID of the desired number(s)
page	INTEGER	(optional) Which page of results to retrieve Default: 1 Min: 1 Must be scalar Note: When more records are available on the next page, this API returns pageSize + 1 records.
pageSize	INTEGER	(optional) The maximum number of results to return per page Default: 100 Max: 100 Min: 1 Must be scalar Note: When more records are available on the next page, this API returns pageSize + 1 records.

Search for SmartFlows-Enabled Numbers

GET /_rest/v4/my/tf?hasCpaas=1

Search Multiple Packages

GET /_rest/v4/my/tf?packageID[]=78314&packageID[]=24188

Response Example and Schema

Success 200

Field	Type	Description
endpoints	OBJECT[]	An array of results (numbers) matching the specified filters
accountID	INTEGER	The account ID to which this number is assigned
endpoint	NUMERIC	The e.164 representation of the number
hasCpaas	BOOLEAN	The number's SmartFlows status
label	STRING	(optional) The number’s label.
orderID	INTEGER	The order ID which purchased or ported the number into inventory
packageID	INTEGER	The number’s package ID.
type	STRING	The number's type, indicating if it is a short code or a long code Allowed values: LONG
geo	OBJECT	An object containing geographical data about the number
country	STRING	The number's ISO-3166 country code
stateProvince	STRING	(optional) The 2-letter abbreviation for the number's state or province, usually empty
media	OBJECT	An object containing technical configuration details
sms	OBJECT	An object containing technical details about the number's SMS configuration
rx	OBJECT	(optional) An object containing the number's SMS receiving (rx) configuration
tx	OBJECT[]	(optional) An array of objects containing the number's SMS sending (tx) configurations
voice	OBJECT	An object containing technical details about the number's voice configuration
rx	OBJECT	(optional) An object containing the number's voice receiving (rx) configuration
tx	OBJECT[]	(optional) An array of objects containing the number's voice sending (tx) configurations
hasMore	BOOLEAN	Indicates if there are results available on the next page

Success Response

HTTP/1.1 200 OK
{
    "endpoints": [
        {
            "accountID": 1004318,
            "endpoint": "+18007293863",
            "hasCpaas": false,
            "label": "Head office",
            "packageID": 30744,
            "type": "LONG",
            "geo": {
                "country": "US",
                "stateProvince": null
            },
            "media": {
                "sms": null,
                "voice": {
                    "rx": {
                        "provider": "IntelePeer",
                        "service": "SIP",
                        "ns": "intelepeer.sip",
                        "config": {}
                    },
                    "tx": [
                        {
                            "provider": "IntelePeer",
                            "service": "SIP",
                            "ns": "intelepeer.sip",
                            "config": {}
                        }
                    ]
                }
            }
        },
        {
            "accountID": 1004318,
            "endpoint": "+18003255821",
            "hasCpaas": true,
            "label": "Automated Messaging",
            "packageID": 30744,
            "type": "LONG",
            "geo": {
                "country": "US",
                "stateProvince": null
            },
            "media": {
                "sms": {
                    "rx": {
                        "provider": "IntelePeer",
                        "service": "SIP",
                        "ns": "intelepeer.sip",
                        "config": {
                            "webhook": "cpaas://api.intelepeer.com"
                        }
                    },
                    "tx": [
                        {
                            "provider": "IntelePeer",
                            "service": "SIP",
                            "ns": "intelepeer.sip",
                            "config": {}
                        }
                    ]
                },
                "voice": null
            }
        }
    ],
    "hasMore": false
}

Error

Name	Type	Description
code	INTEGER	Error code
error	STRING	Error description

Code 401 Response

HTTP/1.1 401 Unauthorized
{
	"code": 401,
	"error": "Unauthorized"
}

HTTP/1.1 401 Unauthorized
{
	"code": 401,
	"error": "Session Expired"
}

Code 406 Response

HTTP/1.1 406 Not Acceptable
{
	"code": 406,
	"error": "Not Acceptable"
}

Code 422 Response

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) integer."
}

HTTP/1.1 422 Unprocessable Entity
{
	"code": 422,
	"error": "The '%s' parameter must be formatted as a non-empty string."
}

Reserve Toll-Free Numbers

Search and identify your unique TF numbers, and then hold onto them with Reserve TF Number. Like a shopping cart, reserving allows you to think on them before someone else buys them.

Method and Endpoint

POST /_rest/v4/carrier/tf/reservations

Headers

Accept: application/json
Authorization: xxxxxxxxxxxxxxxxx
Content-Type: application/json

Field	Type	Description
Accept	STRING	application/json
Authorization	STRING	Authorization token (for more information, see API Authentication)
Content-Type	STRING	application/json

Parameter

Field	Type	Description
endpoints	E.164	The endpoints to reserve.
reservationID	STRING	(optional) A Universally Unique Identifier (UUID) to associate with the reserved endpoints (for more information, see Universally Unique Identifier).

Request Example and Schema

{
    "endpoints": [
        "+18887293863",
        "+18887293864"
    ]
}

Request with Explicit Reservation ID

{
    "endpoints": [
        "+18885551201",
        "+18885551202"
    ],
    "reservationID": "F78793B1-7E84-11E6-B908-52540029234D"
}

Success 200

Field	Type	Description
expirationDate	DateTime	The ISO 8601 date the reservation expires.
reservationID	STRING	The Universally Unique Identifier (UUID) associated with the endpoint(s) (for more information, see Universally Unique Identifier).
reservedDate	DATETIME	The ISO 8601 date the reservation was created.
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.

Success Response

HTTP/1.1 200 OK
[
    {
        "expirationDate": "2015-08-16T23:17:01Z",
        "reservationID": "F78793B1-7E84-11E6-B908-52540029234D",
        "reservedDate": "2015-08-16T22:47:01Z",
        "endpoints": [
            {
                "endpoint": "+18887293863",
                "geo": {
                    "city": null,
                    "country": "US",
                    "stateProvince": null
                }
            },
            {
                "endpoint": "+18887293864",
                "geo": {
                    "city": null,
                    "country": "US",
                    "stateProvince": null
                }
            }
        ]
    }
]

Error

Name	Type	Description
code	INTEGER	Error code
error	STRING	Error description

Code 401 Response

HTTP/1.1 401 Unauthorized
{
	"code": 401,
	"error": "Unauthorized"
}

HTTP/1.1 401 Unauthorized
{
	"code": 401,
	"error": "Session Expired"
}

Code 406 Response

HTTP/1.1 406 Not Acceptable
{
	"code": 406,
	"error": "Not Acceptable"
}

Code 409 Response

HTTP/1.1 409 Unprocessable Entity
{
	"code": 409,
	"error": "Number(s) not available."
}

Code 422 Response

HTTP/1.1 422 Unprocessable Entity
{
	"code": 422,
	"error": "The '%s' parameter is required."
}

HTTP/1.1 422 Unprocessable Entity
{
	"code": 422,
	"error": "The '%s' parameter must be formatted as a(n) array."
}

HTTP/1.1 422 Unprocessable Entity
{
	"code": 422,
	"error": "The '%' parameter is required for each Number object."
}

HTTP/1.1 422 Unprocessable Entity
{
	"code": 422,
	"error": "The 'countryCode' parameter must match one of the following values: 1"
}

Purchase Toll-Free Numbers

After finding, or finding and reserving your unique Tool-Free (TF) numbers, use Purchase TF Numbers to buy them.

Method and Endpoint

POST /_rest/v4/my/tf/orders

Header

Accept: application/json
Authorization: xxxxxxxxxxxxxxxxx
Content-Type: application/json

Field	Type	Description
Accept	STRING	application/json
Authorization	STRING	Authorization token (for more information, see API Authentication)
Content-Type	STRING	application/json

Parameters

Field	Type	Description
email	STRING	(optional) An email address to notify about changes in the order’s status Must be scalar
myRespOrg	BOOLEAN	(optional) Should numbers be provisioned to customer’s RespOrg instead of carrier RespOrg Defaults to false
notes	STRING	(optional) Notes regarding the fulfillment of the order Must be scalar
endpoints	ARRAY	An array of reserved numbers to order (see Search and Reserve sections) Mutually exclusive with quantity and reservations. Each item is in the following form: { "countryCode": "1", "number": "1112223456" }
packageID	INTEGER	The target packageID to order numbers for Must be scalar.
quantity	INTEGER	The quantity of numbers to order. Must be scalar. Mutually exclusive with endpoints and reservations.
reservations	STRING	One or more reservationIDs indicating the numbers to order Mutually exclusive with endpoints and quantity
referenceID	STRING	(optional) A non-empty string indicating your reference ID or code Must be scalar
serviceArea	INTEGER	The service area for desired number(s) (for more information, see Lookups – Service Area) Must be scalar

Order by Reservations

{
    "reservationID": [
        "BD929A2A-7F48-11E6-B908-52540029234D",
        "0F85813F-7E8B-11E6-B908-52540029234D"
    ],
    "packageID": 1234567,
    "serviceArea": 4
}

Order by Quantity

{
	"quantity": 1,
	"packageID": 1234567,
	"serviceArea": 4
}

Success 200

Field	Type	Description
accountID	INTEGER	The account ID for which the order was placed, if applicable
batchIDs	INTEGER	The IDs of the batches associated to this order
completed	DateTime	The ISO 8601 date the order was completed; value can be null if a completed date is not available
created	DateTime	The ISO 8601 date the order was placed
orderID	INTEGER	The order ID
packageID	INTEGER	The package ID for which the order was placed, if applicable
referenceID	STRING	The customer key associated to this order; can be null if empty
source	STRING	The source type, where the order originated from Allowed values: API, Portal
status	STRING	The order status Allowed values: "PENDING"
type	STRING	The order type Allowed values: "TF Purchase"

Success Response

HTTP/1.1 200 OK
{
    "accountID": 1006568,
    "batchIDs": [
        800024
    ],
    "completed": null,
    "created": "2019-02-10T20:46:12Z",
    "orderID": 800240,
    "packageID": 31615,
    "referenceID": null,
    "source": "API",
    "status": "PENDING",
    "type": "TF Purchase"
}

Error

Name	Type	Description
code	INTEGER	Error code
error	STRING	Error description

Code 401 Response

HTTP/1.1 401 Unauthorized
{
	"code": 401,
	"error": "Unauthorized"
}

HTTP/1.1 401 Unauthorized
{
	"code": 401,
	"error": "Session Expired"
}

Code 402 Response

HTTP/1.1 402 Payment Required
{
	"code": 402,
	"error": "Order blocked; trial limit realized.  Limit: %d seats."
}

HTTP/1.1 402 Payment Required
{
	"code": 402,
	"error": "Order too large; trial limit exceeded.  Available: %d seats."
}

Code 406 Response

HTTP/1.1 406 Not Acceptable
{
	"code": 406,
	"error": "Not Acceptable"
}

Code 422 Response

HTTP/1.1 422 Unprocessable Entity
{
	"code": 422,
	"error": "The '%s' parameter is required."
}

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) integer."
}

HTTP/1.1 422 Unprocessable Entity
{
	"code": 422,
	"error": "The '%s' parameter must be formatted as a(n) string."
}

HTTP/1.1 422 Unprocessable Entity
{
	"code": 422,
	"error": "The 'countryCode' parameter must match one of the following values: 1"
}

HTTP/1.1 422 Unprocessable Entity
{
	"code": 422,
	"error": "The 'serviceArea' parameter must match one of the following values: 1, 2, 3, 4, 5"
}

Move Toll-Free Numbers

Move Toll-Free (TF) numbers to a different package / route profile.

Method and Endpoint

POST /_rest/v4/my/tf/package

Header

Accept: application/json
Authorization: xxxxxxxxxxxxxxxxx
Content-Type: application/json

Field	Type	Description
Accept	STRING	application/json
Authorization	STRING	Authorization token (for more information, see API Authentication)
Content-Type	STRING	application/json

Parameters

Field	Type	Description
email (optional)	STRING	An email address to notify about changes in this order’s status
endpoints	ARRAY	An array of reserved numbers to order; each item is in the e164 format: "+17207998099"
notes (optional)	STRING	Notes regarding the fulfilment of this order
packageID	INTEGER	The target packageID to order numbers for
referenceID (optional)	STRING	A non-empty string indicating your reference ID or code

Request Example

POST /_rest/v4/my/tf/package

{
    "packageID": 1234567,
    "endpoints": [
        "+17205558000",
        "+13035558099"
    ]
}

Success 200 Fields

Field	Type	Description
accountID	INTEGER	The account ID for which the order was placed, if applicable
batchID	INTEGER	The IDs of the batches associated to this order
completed	DATETIME	The ISO 8601 date the order was completed; the value can be null if a completed date is not available
created	INTEGER	The ISO 8601 date the order was placed
orderID	INTEGER	The order ID
packageID	INTEGER	The package ID for which the order was placed, if applicable
referenceID (optional)	STRING	The customer key associated with this order; can be null if empty
source	STRING	The source type where the order originated from Allowed values: API, Portal
status	STRING	The order status. Allowed values: PENDING
type	STRING	The order type. Allowed values: Change Package

Response Example and Schema

Success 200 Response

HTTP/1.1 200 OK
{
    "accountID": 1006568,
    "batchIDs": [
        800024
    ],
    "completed": null,
    "created": "2019-02-10T20:46:12Z",
    "orderID": 800240,
    "packageID": 31615,
    "referenceID": null,
    "source": "API",
    "status": "PENDING",
    "type": "Change Package"
}

Error

Name	Type	Description
code	INTEGER	Error code
error	STRING	Error description

Code 401 Response

HTTP/1.1 401 Unauthorized
{
	"code": 401,
	"error": "Unauthorized"
}

HTTP/1.1 401 Unauthorized
{
	"code": 401,
	"error": "Session Expired"
}

Code 406 Response

HTTP/1.1 406 Not Acceptable
{
	"code": 406,
	"error": "Not Acceptable"
}

Code 422 Response

HTTP/1.1 422 Unprocessable Entity
{
	"code": 422,
	"error": "The '%s' parameter is required."
}

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) integer."
}

HTTP/1.1 422 Unprocessable Entity
{
	"code": 422,
	"error": "The '%s' parameter must be formatted as a(n) string."
}

Disconnect Toll-Free Numbers

Use TF Disconnect when numbers are ported away or no longer needed.

Method and Endpoint

POST /_rest/v4/my/tf/disconnect

Headers

Accept: application/json
Authorization: xxxxxxxxxxxxxxxxx
Content-Type: application/json

Field	Type	Description
Accept	STRING	application/json
Authorization	STRING	Authorization token (for more information, see API Authentication)
Content-Type	STRING	application/json

Parameters

Field	Type	Description
An	STRING[]	Array of numbers in e.164 format
email	STRING	(optional) An email address to notify about changes in the order’s status Must be scalar
notes	STRING	(optional) Notes regarding the fulfillment of the order Must be scalar
referenceID	STRING	(optional) A non-empty string indicating your customer/external reference ID Must be scalar

Request

POST /_rest/v4/my/tf/disconnect

{
    "endpoints": [
        "+18885550001",
        "+18885550002"
    ]
}

Response Example and Schema

Success 200

Field	Type	Description
accountID	INTEGER	The account ID for which the order was placed, if applicable
batchIDs	INTEGER[]	The IDs of the batches associated to this order
completed	DateTime	The ISO 8601 date the order was completed. Value can be null if a completed date is not available
created	DateTime	The ISO 8601 date the order was placed
orderID	INTEGER	The order ID
packageID	INTEGER	The package ID for which the order was placed, if applicable
referenceID	STRING	The customer key associated to this order; can be null if empty
source	STRING	The source type, where the order originated from Allowed values: API, Portal
status	STRING	The order status Allowed values: "PENDING"
type	STRING	The order type Allowed values: "TF Return"

Success Response

HTTP/1.1 202
{
    "accountID": null,
    "batchIDs": [
        800024
    ],
    "completed": null,
    "created": "2019-02-10T20:46:12Z",
    "orderID": 800240,
    "packageID": null,
    "referenceID": null,
    "source": "API",
    "status": "PENDING",
    "type": "TF Return"
}

Error

Name	Type	Description
code	INTEGER	Error code
error	STRING	Error description

Code 401 Response

HTTP/1.1 401 Unauthorized
{
	"code": 401,
	"error": "Unauthorized"
}

HTTP/1.1 401 Unauthorized
{
	"code": 401,
	"error": "Session Expired"
}

Code 409 Response

HTTP/1.1 409 Conflict
{
	"code": 409,
	"error": "One or more numbers is part of a conflicting order."
}

HTTP/1.1 409 Conflict
{
	"code": 409,
	"error": "One or more numbers is already pending disconnect."
}

HTTP/1.1 409 Conflict
{
	"code": 409,
	"error": "One or more numbers is not assigned to this account."
}

Code 422 Response

HTTP/1.1 422 Unprocessable Entity
{
	"code": 422,
	"error": "The '%s' parameter is required."
}

HTTP/1.1 422 Unprocessable Entity
{
	"code": 422,
	"error": "The '%s' parameter must be formatted as a(n) string."
}