Provisioning Telephone Numbers for SMS

Overview

All phone numbers on the IntelePeer network can be used to send and receive SMS messages. You can enable SMS over your phone number by:

Configuring a number through the IntelePeer Customer Portal
Configuring a number using our API

This page discusses enabling SMS via API for long codes only. Enablement allows you to send SMS messages using a phone number (long code) using the SMS send API, and also makes the webhook API available for use on the long code to receive SMS messages.

Short codes can be ordered by contacting IntelePeer directly. Learn more about enabling numbers through the IntelePeer Customer Portal in the SMS / MMS Messaging Quick Start Guide.

Configuring Numbers via API

Configuring a phone number using our API requires the following steps:

Explicitly enable SMS for the phone number
Create and set the webhook for processing of inbound SMS messages

Checking Number Configuration via API

You can check the current configuration of a number through the API:

Get the SMS enablement status of a phone number
Get the current webhook for a phone number

Enabling SMS for Single Phone Number via API

URI

Copy

1
POST to https://api.intelepeer.com/_rest/v4/my/did/sms/provision

Parameters

This API method requires an Authorization Token. To learn more about the Authorization token, check out API Authentication.

Parameter	Data Type	Required	Description
endpoints	list of strings	required	A list of E.164 format of the long codes (TNs) you wish to provision. Only a single E.164 can be submitted to this list.

Request Example

Copy

1
2
3
{
"endpoints": [ "+13031112222" ]
}

Response Example

Copy

1
2
3
4
5
6
{
"code": 202,
"provisioning": {
"state": "requested"
}
}

Response Code	Description
202	The provisioning request has been accepted and is pending completion.
400	The reason for the error is contained within the response.
401	The reason for the error is contained within the response.
409	Provisioning (or deprovisioning) of the number is in progress.

Behavior

Enabling of numbers for SMS typically happens within minutes; however, there are some cases where a number may take longer to enable:

Toll-free numbers for which IntelePeer is not the responsible organization (resporg)
DIDs and toll-free numbers already being used for SMS within another service

Example Code

Copy

1
2
3
import requests ############################################################################### ### update these accordingly ### ############################################################################### authtoken = ‘INSERT_AUTH_TOKEN_HERE’ tn = ‘INSERT_TELEPHONENUMBER_HERE_IN_E.164_FORMAT’ ############################################################################### ### leave these alone ### ############################################################################### url = “https://api.intelepeer.com/_rest/v4/my/did/sms/provision” hdrs = { ‘Content-Type’: “application/json”, ‘Authorization’: {}’.format(authtoken) } request = {
“endpoints”: [ tn ]
} ############################################################################### ### execute the task and parse results ### ############################################################################### response = requests.post(url, json=request, headers=hdrs) print u'{}: {}’.format(‘OK’ if response else ‘ERROR’, response.text )

Checking the SMS Enablement Status of a Phone Number

URI

Copy

1
GET to https://api.intelepeer.com/_rest/v4/my/did/sms/provision?endpoint=%2B{tn}

“%2B” is the URL-encoded ‘+’ component of E.164 format.
{tn} is the phone number being queried, including the leading country-code

For example, you would configure the webhook for +17208675309 by GET-ing from the URL:

Copy

1
https://api.intelepeer.com/_rest/v4/my/did/sms/provision?endpoint=%2B17208675309

Multiple endpoints can be provided by adding additional endpoint parameters in the URL, separated with an ampersand.

Parameters

None, however this API method requires an Authorization token. To learn more about the Authorization token, check out API Authentication.

Response Example

Copy

1
2
3
4
5
6
{
"code": 200,
"provisioning": {
"state": "requested"
}
}

If multiple endpoints are provided, the response code changes to 207 (multi-status) and a list of responses matching the above format is returned in the same order of the query parameters provided.

Response Variable Values

Variable

Available Values

code

matches the http response code

provisioning.state

requested

provisioning

provisioned

derequested

deprovisioning

error

Response Code	Description
200	Status returned in the response
400	The telephone number is not in the proper E.164 format
404	The telephone number is not available for use by the customer

Example Code

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import requests
from urllib import quote
###############################################################################
### update these accordingly ###
###############################################################################
authtoken = 'INSERT_AUTH_TOKEN_HERE'
tn = 'INSERT_TELEPHONENUMBER_HERE_IN_E.164_FORMAT'
###############################################################################
### leave these alone ###
###############################################################################
url = "https://api.intelepeer.com/_rest/v4/my/did/sms/provision?endpoint={}".format(quote(tn))
hdrs = {
'Content-Type': "application/json",
'Authorization': {}'.format(authtoken)
}
###############################################################################
### execute the task and parse results ###
###############################################################################
response = requests.get(url, json={}, headers=hdrs)
print u'{}: {}'.format('OK' if response else 'ERROR', response.text )

Disabling a Number for SMS via API

URI

Copy

1
DELETE to https://api.intelepeer.com/_rest/v4/my/did/sms/provision

Parameters

This API method requires an Authorization token. To learn more about the Authorization token, check out API Authentication.

Copy

1
2
3
4
{
"endpoints": [ "+13031112222" ]
}

Response Example

Copy

1
2
3
4
5
6
{
"code": 202,
"provisioning": {
"state": "derequested"
}
}

Response Code	Description
202	The deprovisioning request has been accepted and is pending completion
400	The reason for the error is contained within the response
401	The reason for the error is contained within the response
409	Provisioning (or deprovisioning) of the number is in progress

Behavior

Deprovisioning can only be requested when a number is in the provisioned state.

Example Code

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import requests
###############################################################################
### update these accordingly                                                ###
###############################################################################
authtoken = 'INSERT_AUTH_TOKEN_HERE'
tn        = 'INSERT_TELEPHONENUMBER_HERE_IN_E.164_FORMAT'
###############################################################################
### leave these alone                                                       ###
###############################################################################
url = "https://api.intelepeer.com/_rest/my/did/sms/provision
hdrs = {
'Content-Type': "application/json",
'Authorization':  {}'.format(authtoken)
}
request = { "endpoints": [ tn ] }
###############################################################################
### execute the task and parse results                                      ###
###############################################################################
response = requests.delete(url, json=request, headers=hdrs)
print u'{}: {}'.format('OK' if response else 'ERROR', response.text )