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

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

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

 

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

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

Search Multiple Packages

Copy 
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

Copy 
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

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 422 Response

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

 

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

 

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

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

Request with Explicit Reservation ID

Copy 
{
    "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

Copy 
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

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 Unprocessable Entity
{
    "code": 409,
    "error": "Number(s) not available."
}

Code 422 Response

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

 

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

 

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

 

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

 

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
endpointss 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

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

Order by Quantity

Copy 
{
    "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

Copy 
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

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

 

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

Code 402 Response

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

 

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

Code 406 Response

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

Code 422 Response

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

 

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

 

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

 

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

 

Copy 
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 (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 e-mail 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

Copy
Move TFs to Package 1234567
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

Copy 
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

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 422 Response

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

 

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

 

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

 

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

Copy 
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

Copy 
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

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

 

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

Code 409 Response

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

 

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

 

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

Code 422 Response

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

 

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