SMS API Introduction

Welcome to the Voxtelesys SMS REST API. This API offers an easy, secure solution to longcode and shortcode SMS messaging.

Base URL

All URLs referenced in this document have the following base: https://smsapi.voxtelesys.net/api/v1

Authentication

The SMS API utilizes tokens to authenticate its resources. When setting up an SMS account, users have the option to choose between a persistent token or short-lived tokens. In most applications, persistent tokens will provide adequate security.

Persistent tokens

Persistent tokens are configured during the on-boarding process and do not expire. If a persistent token has been issued to your account, simply provide the token via Bearer authentication when sending requests to the SMS API.

Authorization: Bearer={TOKEN}

Authorization: Bearer=f2d1c9b6-1158-11e6-bb4e-26a732fd0877

Short-lived tokens

Short-lived tokens provide additional security, as they expire after 10 minutes of inactivity. This style of implementation is very similar to OAuth2.0. If your account is setup to use short-lived tokens, then a username and password will be assigned to your account during the on-boarding process.

To get started with short-lived tokens, the user must first request a token via the /authorize/login method. The login method utilizes HTTP basic authentication.

Request:

curl --request GET \
  --url https://smsapi.voxtelesys.net/api/v1/authorize/login \
  --header 'authorization: Basic ZGVtbzpwd2Q='

Response: 200

{
  "status": {
    "status": "Authorized",
    "token": "7bdf5350-5895-46ec-a25a-a531613c5046",
    "account_id": 190761,
    "account_name": "voxtelesys vts",
    "service_group_id": 70001
  },
  "services": [
    {
      "full_name": "SMS Messaging",
      "service_id": 6,
      "short_name": "SMS"
    }
  ],
  "error": ""
}

GET /authorize/login

Header	Type	Required	Description	Example
Authorization	string	true	basic authentication	`Authentication: Basic dXNyOnB3ZA==`

The assigned token is valid for 10 minutes, refreshing for an additional 10 minutes with subsequent successful requests. As a further layer of protection, the assigned token is only valid for the IP address from which the HTTP request was attempted. For applications making request to the SMS API via separate IP addresses, you must obtain unique tokens per application.

The user can then use the provided token by providing the subsequent Authorization headers with requests sent to the SMS API:

Authorization: Token token={TOKEN}

Authorization: Token token=f2d1c9b6-1158-11e6-bb4e-26a732fd0877

Messages

The messages namespace provides a paginated mechanism for retrieval and listing of inbound and outbound SMS messages. Retrieved messages can be filtered via an assortment of query parameters, such as dates, to(s), from(s), batch IDs, and read status.

The latter parameter, unread_only, allows for retrieval of 'new' inbound messages. When messages are retrieved via the /msgs/inbound endpoint, Voxtelesys will flag the messages with a 'read' status. Subsequent calls to this namespace, with the unread_only parameter will result in any previously retrieved messages being filtered out.

For real-time communications, please see Callbacks.

Message statuses

Each outbound message has a status field to indicate the delivery state that it is in. This status is also provided in the delivery report for the respective SMS batch. The list of possible statuses is provided below:

Status	Type	Description
Queued	Intermediate	Message has been queued and will be sent for delivering according to account rate.
Delivering	Intermediate	Message has been sent and is awaiting final delivery state.
Delivered	Final	Message has been delivered.
Failed	Final	Message failed to be delivered.
Unknown	Final	Final delivery state is unknown.
Canceled	Final	Message was canceled before attempting delivery.
Expired	Final	Message expired before attempting delivery.

Retrieve inbound messages

Request:

curl --request GET \
  --url 'https://smsapi.voxtelesys.net/api/v1/msgs/inbound' \
  --header 'authorization: Token token=459ae346-7521-494b-8f79-9fff6fe2e977'

Response: 200

{
  "page": 1,
  "page_size": 25,
  "page_count": 1,
  "count": 3,
  "results": [
    {
      "id": "5c86ace6d3ea23543ceab921",
      "to": "14029999402",
      "from": "14029999999",
      "body": "Test outbound message #1!",
      "received_at": "2019-03-11T18:45:57Z"
    },
    {
      "id": "5c86aac1d3ea23543ceab920",
      "to": "14029999402",
      "from": "14029999999",
      "body": "Test outbound message #2!",
      "received_at": "2019-03-11T18:36:49Z"
    },
    {
      "id": "5c86aa10d3ea23543ceab91f",
      "to": "14029999402",
      "from": "14029999999",
      "body": "Test outbound message #3!",
      "received_at": "2019-03-11T18:33:51Z"
    }
  ]
}

This endpoint retrieves inbound messages associated with your account.

HTTP Request

GET /msgs/inbound

Query Parameter	Type	Required	Description	Example
page	integer	false	page number starting from 1; default = 1	`1`
page_size	integer	false	number of messages to retrieve per page; default = 25	`50`
start_date	string	false	retrieve messages at or after this date time; must be ISO-8601 format	`2018-03-01 08:00 -0600`
end_date	string	false	retrieve messages at or before this date time; must be ISO-8601 format	`2018-03-28 08:00 -0600`
to	string	false	retrieve messages based upon 'to' field; multiple numbers may be comma separated	`40121,14029999402`
from	string	false	retrieve messages based upon 'from' field; multiple numbers may be comma separated	`1701123456`
sub_account_id	string	false	retrieve messages associated with this sub account	`1011`
unread_only	boolean	false	retrieve new messages; all messages get flagged as 'read' once retrieved	`true`

Retrieve outbound messages

Request:

curl --request GET \
  --url 'https://smsapi.voxtelesys.net/api/v1/msgs/outbound' \
  --header 'authorization: Token token=459ae346-7521-494b-8f79-9fff6fe2e977'

Response: 200

{
  "page": 1,
  "page_size": 25,
  "page_count": 1,
  "count": 3,
  "results": [
    {
      "id": "5c87f6747af41d0c5b46a9f0",
      "to": "14029999999",
      "from": "14029999402",
      "body": "Test outbound message #1!",
      "status": "delivered",
      "modified_at": "2019-03-12T18:12:07Z",
      "sent_at": "2019-03-12T18:12:04Z"
    },
    {
      "id": "5c86ad547af41d0c5b46a9ef",
      "to": "14029999999",
      "from": "14029999402",
      "body": "Test outbound message #2!",
      "status": "delivered",
      "modified_at": "2019-03-11T18:47:52Z",
      "sent_at": "2019-03-11T18:47:48Z"
    },
    {
      "id": "5c86acfb7af41d0c5b46a9ee",
      "to": "14029999999",
      "from": "14029999402",
      "body": "Test outbound message #3!",
      "status": "delivered",
      "modified_at": "2019-03-11T18:46:23Z",
      "sent_at": "2019-03-11T18:46:19Z"
    }
  ]
}

This endpoint retrieves outbound messages associated with your account.

HTTP Request

GET /msgs/outbound

Query Parameter	Type	Required	Description	Example
page	integer	false	page number starting from 1; default = 1	`1`
page_size	integer	false	number of messages to retrieve per page; default = 25	`50`
start_date	string	false	retrieve messages at or after this date time; must be ISO-8601 format	`2018-03-01 08:00 -0600`
end_date	string	false	retrieve messages at or before this date time; must be ISO-8601 format	`2018-03-28 08:00 -0600`
to	string	false	retrieve messages based upon 'to' field; multiple numbers may be comma separated	`40121,14029999402`
from	string	false	retrieve messages based upon 'from' field; multiple numbers may be comma separated	`1701123456`
sub_account_id	string	false	retrieve messages associated with this sub account	`1011`
batch_id	string	false	retrieve messages from this SMS batch	`BPBPqNgILE2urR4S`
status	string	false	retrieve messages with this status	`delivered`

Applications

Applications are a crucial component of the SMS API. They define the actions to execute based upon inbound SMS messages and also control real-time callbacks for inbound messaging and outbound delivery reporting.

A few common use cases include:
1. Forwarding inbound messages to an on-site server for real-time chat services.
2. Building and maintaining lists of mobile subscribers for bulk messaging.
3. Setting up automatic reply keywords for one-time downloads.

Please refer to the longcodes namespace to see how to assign an application to a longcode.

Actions

The following actions can be used when creating and updating an SMS application.

mo_callback
dr_callback
auto_reply
opt_out
opt_in
two_fact_auth

mo_callback

Example:

{
  "mo_callback": {
    "url": "https://example.com:3000/api/v1/callbacks/mos",
    "method": "post",
    "basic": "usr:pwd"
  }
}

The "mo_callback" action forwards inbound messages to the configured endpoint. This is the recommended method to receive inbound messages for real-time communication. As inbound messages are received, Voxtelesys will send an HTTP request with the respective data to the specified endpoint.

Property	Type	Default	Description
url	string	required	URL of server to receive callbacks
method	string	post	HTTP method; must be get,post
basic	string	null	username:password for basic authentication
bearer	string	null	Token to be used for bearer authentication

dr_callback

Example:

{
  "dr_callback": {
    "url": "https://example.com:3000/api/v1/callbacks/reports",
    "method": "post",
    "basic": "usr:pwd",
    "type": "detailed"
  }
}

The "dr_callback" action forwards delivery receipts/reports to the configured endpoint.

Property	Type	Default	Description
url	string	required	URL of server to receive callbacks
method	string	post	HTTP method; must be get,post
basic	string	null	username:password for basic authentication
bearer	string	null	token to be used for bearer authentication
type	string	summary	type of delivery report; must be summary,detailed

auto_reply

Example:

{
  "auto_reply": [
    {
      "keywords": ["HELP", "INFO"],
      "reply": "VTS: Please give us a call at 402-403-4435 for assistance."
    },
    {
      "keywords": ["download"],
      "reply": "Please download our mobile app: {link_here}"
    }
  ]
}

The "auto_reply" action sends the reply message to the mobile user in response to inbound messages matching one of the specified keywords. Multiple sets of keyword/replies can be defined by adding multiple objects within the auto_reply array.

Property	Type	Default	Description
keywords	array	required	Keywords to initiate auto reply; case insensitive
reply	string	required	Reply message

opt_in

Example:

{
  "opt_in": [
    {
      "keywords": ["VTS"],
      "reply": "VTS: You have chosen to receive periodic system updates. Reply CONFIRM to opt-in. Reply STOP to opt-out. Reply HELP for support. Msg&Data rates may apply. T&Cs: http://bit.ly/2BBnp34",
      "status": "init"
    },
    {
      "keywords": ["CONFIRM"],
      "reply": "VTS: Your have successfully been subscribed to system update alerts!",
      "status": "double"
    }
  ]
}

The "opt_in" action adds the mobile user to the respective list with the specified status and sends the reply message in response to inbound messages matching one of the specified keywords.

Property	Type	Default	Description
keywords	array	required	Keywords to initiate opt-in; case insensitive
reply	string	required	Reply message
status	string	single	msisdn will be added into list with this status; must be init, single, double, or verified

opt_out

Example:

{
  "opt_out": [
    {
      "keywords": ["stop","cancel","end","quit"],
      "reply": "You have been unscubscribed and will no longer received SMS alerts."
    }
  ]
}

The "opt_out" action marks the mobile user as opted-out of the respective list and send the reply message in response to inbound messages matching one of the specified keywords.

Property	Type	Default	Description
keywords	array	required	Keywords to initiate opt-out; case insensitive
reply	string	required	Reply message

two_fact_auth

Example:

{
  "two_fact_auth": {
    "request": "Voxtelesys: Your one-time code is ${6}. Please use this code to complete your request.",
    "confirm": "Voxtelesys: Your account has successfully been verified.",
    "keywords": ["code","verify"]
  }
}

The "two_fact_auth" action provides a mechanism for 2FA, initiated by either the mobile user or application manager (see application initiation). The mobile user can initiate the 2FA process by sending a message matching one of the specified keywords. The user will then receive back the request message with a populated verification code. Codes are random and generated based upon the specified length within the request property. For example: ${6} => 6 digit random code. Once the code has been verified (see two factor authentication, the user will receive the confirm message and will be added to the respective list with a "verified" status.

Property	Type	Default	Description
request	string	required	Message to be sent to initialize verification
confirm	string	required	Message to be sent after successful verification
keywords	array	null	Keywords that will initiate 2FA; case insensitive

Create an application

Request:

curl --request POST \
  --url https://smsapi.voxtelesys.net/api/v1/apps \
  --header 'authorization: Token token=176a78b0-8e81-4e56-9e3f-da67d17915bb' \
  --header 'content-type: application/json' \
  --data '{
    "name": "Test App",
    "script": {
      "mo_callback": {
        "url": "https://example.com:3000/api/v1/callbacks",
        "method": "post"
      },
      "opt_out": [
        {
          "keywords": ["stop","cancel","end","quit"],
          "reply": "You have been unscubscribed and will no longer received SMS alerts."
        }
      ],
      "opt_in": [
        {
          "keywords": ["VTS"],
          "reply": "VTS: You have chosen to receive periodic system updates. Reply CONFIRM to opt-in. Reply STOP to opt-out. Reply HELP for support. Msg&Data rates may apply. T&Cs: http://bit.ly/2BBnp34",
          "status": "init"
        },
        {
          "keywords": ["CONFIRM"],
          "reply": "VTS: Your have successfully been subscribed to system update alerts!",
          "status": "double"
        }
      ],
      "auto_reply": [
        {
          "keywords": ["HELP","INFO"],
          "reply": "VTS: Please give us a call at 402-403-4435 for assistance."
        }
      ]
    }
  }'

Response: 200

{
  "id": "9Nskupdq_byZSygx",
  "name": "Test App",
  "created_at": "2019-02-19T21:08:10Z",
  "modified_at": "2019-02-19T21:08:10Z",
  "script": {
    "mo_callback": {
      "url": "https://example.com:3000/api/v1/callbacks",
      "method": "post"
    },
    "opt_out": [
      {
        "keywords": ["stop","cancel","end","quit"],
        "reply": "You have been unscubscribed and will no longer received SMS alerts."
      }
    ],
    "opt_in": [
      {
        "keywords": ["vts"],
        "reply": "VTS: You have chosen to receive periodic system updates. Reply CONFIRM to opt-in. Reply STOP to opt-out. Reply HELP for support. Msg&Data rates may apply. T&Cs: http://bit.ly/2BBnp34",
        "status": "init"
      },
      {
        "keywords": ["confirm"],
        "reply": "VTS: Your have successfully been subscribed to system update alerts!",
        "status": "double"
      }
    ],
    "auto_reply": [
      {
        "keywords": ["help","info"],
        "reply": "VTS: Please give us a call at 402-403-4435 for assistance."
      }
    ]
  }
}

This endpoint creates an application.

HTTP Request

POST /apps

Body Param	Type	Required	Description	Example
name	string	false	name of call flow	`foo_bar`
script	object	true	description of call flow	see sample request
script.mo_callback	object	false	mo-callback action	see sample request
script.dr_callback	object	false	dr-callback action	see sample request
script.auto_reply	array	false	auto-reply action	see sample request
script.opt_in	array	false	opt-in action	see sample request
script.opt_out	array	false	opt-out action	see sample request
script.two_fact_auth	object	false	2FA action	see sample request

Replace an application

Request:

curl --request PUT \
  --url https://smsapi.voxtelesys.net/api/v1/apps/9Nskupdq_byZSygx \
  --header 'authorization: Token token=176a78b0-8e81-4e56-9e3f-da67d17915bb' \
  --header 'content-type: application/json' \
  --data '{
    "script": {
      "auto_reply": [
        {
          "keywords": ["HELP", "INFO"],
          "reply": "VTS: Please give us a call at 402-403-4435 for assistance."
        }
      ]
    }
  }'

Response: 200

{
  "id": "9Nskupdq_byZSygx",
  "name": "Test App",
  "created_at": "2019-02-19T21:08:10Z",
  "modified_at": "2019-02-19T21:17:00Z",
  "script": {
    "auto_reply": [
      {
        "keywords": ["help","info"],
        "reply": "VTS: Please give us a call at 402-403-4435 for assistance."
      }
    ]
  }
}

This endpoint replaces an application. The script is overwritten with the provided script.

HTTP Request

PUT /apps/{id}

URL Parameter	Type	Required	Description	Example
id	string	true	ID of application	`9Nskupdq_byZSygx`

Body Param	Type	Required	Description	Example
name	string	false	name of call flow	`foo_bar`
script	object	true	description of call flow	see sample request
script.mo_callback	object	false	mo-callback action	see sample request
script.dr_callback	object	false	dr-callback action	see sample request
script.auto_reply	array	false	auto-reply action	see sample request
script.opt_in	array	false	opt-in action	see sample request
script.opt_out	array	false	opt-out action	see sample request
script.two_fact_auth	object	false	2FA action	see sample request

Modify an application

Request:

curl --request PATCH \
  --url https://smsapi.voxtelesys.net/api/v1/apps/9Nskupdq_byZSygx \
  --header 'authorization: Token token=176a78b0-8e81-4e56-9e3f-da67d17915bb' \
  --header 'content-type: application/json' \
  --data '{
    "script": {
      "opt_out": [
        {
          "keywords": ["stop","cancel","end","quit"],
          "reply": "You have been unscubscribed and will no longer received SMS alerts."
        }
      ]
    }
  }'

Response: 200

{
  "id": "9Nskupdq_byZSygx",
  "name": "Test App",
  "created_at": "2019-02-19T21:08:10Z"
  "modified_at": "2019-02-19T21:22:46Z",
  "script": {
    "auto_reply": [
      {
        "reply": "VTS: Please give us a call at 402-403-4435 for assistance.",
        "keywords": ["help","info"]
      }
    ],
    "opt_out": [
      {
        "keywords": ["stop","cancel","end","quit"],
        "reply": "You have been unscubscribed and will no longer received SMS alerts."
      }
    ]
  }
}

This endpoint modifies an existing application. Properties within the existing script will not be replaced unless the property is provided in the request script.

HTTP Request

PATCH /apps/{id}

URL Parameter	Type	Required	Description	Example
id	string	true	ID of application	`9Nskupdq_byZSygx`

Body Param	Type	Required	Description	Example
name	string	false	name of call flow	`foo_bar`
script	object	true	description of call flow	see sample request
script.callback	object	false	callback action	see sample request
script.auto_reply	array	false	auto-reply action	see sample request
script.opt_in	array	false	opt-in action	see sample request
script.opt_out	array	false	opt-out action	see sample request
script.two_fact_auth	object	false	2FA action	see sample request

List applications

Request:

curl --request GET \
  --url https://smsapi.voxtelesys.net/api/v1/apps \
  --header 'authorization: Token token=176a78b0-8e81-4e56-9e3f-da67d17915bb'

Response: 200

{
  "page": 1,
  "page_size": 10,
  "page_count": 1,
  "count": 1,
  "results": [
    {
      "id": "9Nskupdq_byZSygx",
      "name": "Test App",
      "created_at": "2019-02-19T21:08:10Z",
      "modified_at": "2019-02-19T21:22:46Z",
      "script": {
        "auto_reply": [
          {
            "reply": "VTS: Please give us a call at 402-403-4435 for assistance.",
            "keywords": ["help","info"]
          }
        ]
      }
    }
  ]
}

This endpoint retrieves a list of applications.

HTTP Request

GET /apps

Query Parameter	Type	Required	Description	Example
page	integer	false	page number starting from 1; default = 1	`1`
page_size	integer	false	number of records to retrieve per page; default = 25	`50`

Retrieve an application

Request:

curl --request GET \
  --url https://smsapi.voxtelesys.net/api/v1/apps/9Nskupdq_byZSygx \
  --header 'authorization: Token token=176a78b0-8e81-4e56-9e3f-da67d17915bb'

Response: 200

{
  "id": "9Nskupdq_byZSygx",
  "name": "Test App",
  "created_at": "2019-02-19T21:08:10Z",
  "modified_at": "2019-02-19T21:22:46Z",
  "script": {
    "auto_reply": [
      {
        "reply": "VTS: Please give us a call at 402-403-4435 for assistance.",
        "keywords": ["help","info"]
      }
    ]
  }
}

This endpoint retrieves a specified application.

HTTP Request

GET /apps/{id}

URL Parameter	Type	Required	Description	Example
id	string	true	ID of application	`9Nskupdq_byZSygx`

Delete an application

Request:

curl --request DELETE \
  --url https://smsapi.voxtelesys.net/api/v1/apps/rdDdVqWLbwsCtDY2 \
  --header 'authorization: Token token=176a78b0-8e81-4e56-9e3f-da67d17915bb'

Response: 204

This endpoint deletes a specified application.

DELETE /apps/{id}

URL Parameter	Type	Required	Description	Example
id	string	true	ID of application	`9Nskupdq_byZSygx`

Callbacks

A callback is an HTTP GET or POST request made from Voxtelesys to a pre-configured URI. The callback will contain either (1) the inbound message (MO) received, or (2) the delivery report (DR) for outbound messaging. Voxtelesys requires a 2XX response from the receiving server. Invalid responses will result in a scheduled retry. The current schedule is 10, 30, 60, 120, 240, 480, 960, 1920, 3840, and 7680 seconds after the first attempt.

Callbacks offer the following authentication methods:

No authentication: URI called without any authentication headers
Basic Authentication: URI called with provided a username and password
Bearer Authentication: URI called with provided a token

Please see the MO callback and DR callback actions to setup callbacks on your account.

MO Callback

{
  "to": "14029999402",
  "from": "14022770210",
  "body": "Hello there, this is a test message!",
  "received_at": "2019-02-19T21:22:46Z"
}

Delivery Report Callback - Summary

 {
  "batch_id": "Z0S0jQOf8_hl9YRt",
  "batch_status": "in-progress",
  "count": 3,
  "results": [
    {
      "status": "queued",
      "count": 3
    }
  ]
}

Delivery Report Callback - Detailed

{
  "batch_id": "Z0S0jQOf8_hl9YRt",
  "batch_status": "in-progress",
  "count": 3,
  "results": [
    {
      "status": "queued",
      "count": 3,
      "to": [
        "14024439159",
        "14024431551",
        "14024431550"
      ]
    }
  ]
}

Longcodes

Longcodes are standard 10-digit dedicated phone numbers (TFNs / DIDs) that enable businesses to receive SMS, voice, and fax messaging. Please contact Voxtelesys at support@voxtelesys.com, or call at 402-403-4435 to inquire about longcode pricing and availability.

List longcodes

Request:

curl --request GET \
  --url https://smsapi.voxtelesys.net/api/v1/longcodes \
  --header 'authorization: Token token=176a78b0-8e81-4e56-9e3f-da67d17915bb'

Response: 200

{
  "page": 1,
  "page_size": 25,
  "page_count": 1,
  "count": 2,
  "results": [
    {
      "longcode": "14029999402",
      "sub_account_id": null,
      "app_id": "9Nskupdq_byZSygx"
    },
    {
      "longcode": "14024034435",
      "sub_account_id": "1001",
      "app_id": "U0EFxA3mFcWZxUHf"
    }
  ]
}

This endpoint retrieves a list of longcodes associated with your account. Each record includes any associated sub account and/or application.

HTTP Request

GET /longcodes

Query Parameter	Type	Required	Description	Example
page	integer	false	page number starting from 1; default = 1	`1`
page_size	integer	false	number of messages to retrieve per page; default = 25	`50`

Retrieve a longcode

Request:

curl --request GET \
  --url https://smsapi.voxtelesys.net/api/v1/longcodes/14029999402 \
  --header 'authorization: Token token=176a78b0-8e81-4e56-9e3f-da67d17915bb'

Response: 200

{
  "longcode": "14029999402",
  "sub_account_id": null,
  "app_id": "9Nskupdq_byZSygx"
}

This endpoint retrieves a specific longcode and associated data.

HTTP Request

GET /longcodes/{longcode}

URL Parameter	Type	Required	Description	Example
longcode	string	true	10-digit longcode	`4029999402`

Update a longcode

Request:

curl --request PUT \
  --url https://smsapi.voxtelesys.net/api/v1/longcodes/14029999402 \
  --header 'authorization: Token token=176a78b0-8e81-4e56-9e3f-da67d17915bb' \
  --data '{
    "app_id": "U0EFxA3mFcWZxUHf",
    "sub_account_id": "1010"
  }'

Response: 200

{

  "longcode": "14029999402",
  "app_id": "U0EFxA3mFcWZxUHf",
  "sub_account_id": "1010"
}

This endpoint updates the sub account and/or application associated with the specified longcode.

HTTP Request

PUT /longcodes/{longcode}

URL Parameter	Type	Required	Description	Example
longcode	string	true	10-digit longcode	`4029999402`

Body Param	Type	Required	Description	Example
sub_account_id	string	false	ID of sub account	`1010`
app_id	string	false	ID of application	`U0EFxA3mFcWZxUHf`

Two factor authentication

This endpoint provides a mechanism for Two Factor Authentication (2FA). 2FA is an extra layer of security used to make sure that people trying to gain access to an account are who they say they are.

Step #1:

The first step in the 2FA process is to send a mobile user a random, unique verification code. By providing the body parameter in the request with a ${length} variable, Voxtelesys will generate a verification code of the specified length and populate the message body. The code is valid for 10 minutes and 3 attempts.

If the body paramter is not provided then the longcode's associated application will be utilized if the "two_fact_auth" action is provided.

Request:

curl --request POST \
  --url https://smsapi.voxtelesys.net/api/v1/longcodes/14029999402/two_fact_auth \
  --header 'authorization: Token token=176a78b0-8e81-4e56-9e3f-da67d17915bb'
  --header 'content-type: application/json' \
  --data '{
    "to": "4024434559",
    "body": "Your one-time security code is: ${6}."
  }'

Response: 200

{
  "to": "14024434559",
  "from": "14024431551",
  "body": "Your one-time security code is: ${6}.",
  "timestamp": "2019-02-20T03:45:10Z",
  "results": [
    {
      "status": "queued",
      "error": null,
      "to": [
        "14024434559"
      ]
    }
  ]
}

HTTP Request

POST /longcodes/{longcode}/two_fact_auth

URL Parameter	Type	Required	Description	Example
longcode	string	true	10-digit longcode	`4029999402`

Body Param	Type	Required	Description	Example
to	string	true	msisdn for 2FA	`4024434559`
body	string	false	Body of message to send to msisdn	`Your one-time code is: ${6}.`

Step #2:

The second step in the 2FA process is to validate the verification code provided by the mobile user. Once verified, the msisdn is added to the respective list with status of verified.

If the body paramter is not provided then the longcode's associated application will be utilized if the "two_fact_auth" action is provided.

Request:

curl --request PUT \
  --url https://smsapi.voxtelesys.net/api/v1/longcodes/14029999402/two_fact_auth/4024434559 \
  --header 'authorization: Token token=176a78b0-8e81-4e56-9e3f-da67d17915bb' \
  --header 'content-type: application/json' \
  --data '{
    "verify_code": "895675",
    "body": "Your account has successfully been verified."
  }'

Response: 200

{
  "to": "14024434559",
  "from": "14024431551",
  "body": "Test confirm message!",
  "timestamp": "2019-02-20T03:58:27Z",
  "results": [
    {
      "status": "queued",
      "error": null,
      "to": [
        "14024434559"
      ]
    }
  ]
}

HTTP Request

PUT /longcodes/{longcode}/two_fact_auth/{msisdn}

URL Parameter	Type	Required	Description	Example
longcode	string	true	10-digit longcode	`4029999402`
msisdn	string	true	msisdn for 2FA	`4024434559`

Body Param	Type	Required	Description	Example
body	string	false	Body of message to send to msisdn	`Your account has successfully been verified.`

Longcode List Management

Subscriber lists provide an easy mechanism to manage opted-in and opted-out MSISDNs. Please refer to the applications section to see how to setup automated opt-in and opt-out actions on your longcodes.

Retrieve subscriber list

Request:

curl --request GET \
  --url https://smsapi.voxtelesys.net/api/v1/longcodes/14029999402/list \
  --header 'authorization: Token token=176a78b0-8e81-4e56-9e3f-da67d17915bb'

Response: 200

{
  "page": 1,
  "page_size": 25,
  "page_count": 1,
  "count": 3,
  "results": {
    "verified": [
      "14021113333",
      "14021114444"
    ],
    "single": [
      "14021112222"
    ]
  }
}

This endpoint retrieves a list of MSISDNs that are subscribed to the specified longcode. MSISDNs are grouped by list status and can be queried based upon dates, statuses, or a particular msisdn. In case of date filtering, the date refers to the time at which the msisdn entered its current status.

HTTP Request

GET /longcodes/{longcode}/list

Query Parameter	Type	Required	Description	Example
page	integer	false	page number starting from 1; default = 1	`1`
page_size	integer	false	number of msisdns to retrieve per page; default = 25	`50`
start_date	string	false	retrieve msisdns at or after this date time; must be ISO-8601 format	`2018-03-01 08:00 -0600`
end_date	string	false	retrieve msisdns at or before this date time; must be ISO-8601 format	`2018-03-28 08:00 -0600`
status	string	false	retrieve msisdns with this status; must be opt-out, init, single, double, or verified	`single`

Retrieve subscriber

Request:

curl --request GET \
  --url https://smsapi.voxtelesys.net/api/v1/longcodes/14029999402/list/14021112222 \
  --header 'authorization: Token token=176a78b0-8e81-4e56-9e3f-da67d17915bb'

Response: 200

{
  "msisdn": "14021112222",
  "status": "single",
  "modified_at": "2019-03-06T02:02:01Z"
}

This endpoint retrieves the specified subscriber.

HTTP Request

GET /longcodes/{longcode}/list/{msisdn}

URL Parameter	Type	Required	Description	Example
msisdn	string	true	msisdn subscribed to longcode	`4024434559`

Update subscriber

Request:

curl --request PUT \
  --url https://smsapi.voxtelesys.net/api/v1/longcodes/14029999402/list/14021112222 \
  --header 'authorization: Token token=176a78b0-8e81-4e56-9e3f-da67d17915bb' \
  --header 'content-type: application/json' \
  --data '{
    "status": "opt-out"
  }'

Response: 204

This endpoint updates the status of the specified subscriber.

HTTP Request

PUT /longcodes/{longcode}/list/{msisdn}

URL Parameter	Type	Required	Description	Example
msisdn	string	true	msisdn subscribed to longcode	`4024434559`

Create subscriber

curl --request POST \
  --url https://smsapi.voxtelesys.net/api/v1/longcodes/14029999402/list \
  --header 'authorization: Token token=176a78b0-8e81-4e56-9e3f-da67d17915bb' \
  --header 'content-type: application/json' \
  --data '{
    "msisdn": "14021112222",
    "status": "opt-out"
  }'

Response: 200

{
  "msisdn": "14021112222",
  "status": "opt-out",
  "modified_at": "2019-03-06T02:02:01Z"
}

This endpoint creates a new subscriber associated with the provided longcode.

HTTP Request

POST /longcodes/{longcode}/list

Body Param	Type	Required	Description	Example
msisdn	string	true	msisdn to subscribe to longcode	`4024434559`
status	string	true	must be opt-out, init, single, double, or verified	`single`

Delete subscriber

Request:

curl --request DELETE \
  --url https://smsapi.voxtelesys.net/api/v1/longcodes/14029999402/list/14021112222 \
  --header 'authorization: Token token=176a78b0-8e81-4e56-9e3f-da67d17915bb'

Response: 204

The endpoint deletes the specified subscriber.

HTTP Request

DELETE /longcodes/{longcode}/list/{msisdn}

URL Parameter	Type	Required	Description	Example
msisdn	string	true	msisdn subscribed to longcode	`4024434559`

SMS Batches

The SMS Batches namespace provides the methods necessary to delivery and manage one-to-one and one-to-many SMS messaging. Batches can be scheduled to start at a specific time, and likewise expire. Additionally, batches support parameterization of the message body.

Batch statuses

Each SMS batch has a status field to indicate the state that it is in. The list of possible statuses is provided below:

Status	Type	Description
pre-processing	Intermediate	Batch is being validated.
in-progress	Intermediate	Batch has been validated and is actively sending messages.
paused	Intermediate	Batch has been paused by user; no messages sent while in this state.
scheduled	Intermediate	Batch has been successfully loaded, and will be sent out at the specified `send_at` time.
canceled	Final	Batch was canceled by user or canceled during pre-processing.
completed	Final	Batch completed successfully.
expired	Final	Batch expired before it was completed. All queued messages are deleted and no further messaging is sent from this batch.

List sms batches

Request:

curl --request GET \
  --url https://smsapi.voxtelesys.net/api/v1/sms \
  --header 'authorization: Token token=176a78b0-8e81-4e56-9e3f-da67d17915bb'

Response: 200

{
  "page": 1,
  "page_size": 30,
  "page_count": 1,
  "count": 1,
  "results": [
    {
      "id": "BPBPqNgILE2urR4S",
      "from": "14024431550",
      "to": ["4024431550","4024431551","4024439159"],
      "body": "Hi ${name}, your package is delivering to ${address} and should arrive around ${time}.",
      "parameters": {
        "definition": ["name","address","time"],
        "default": ["Customer",0,0],
        "4024431550": ["John","1111 Westroads Street","12:30 PM"],
        "4024431551": ["Luke","2222 Eastroads Plaza","1:00 PM"],
        "4024439159": ["Sarah","3333 Southroads Lane","4:45 PM"]
      },
      "send_at": "2019-02-20T04:18:56Z",
      "expire_at": "2019-02-23T04:18:56Z",
      "modified_at": "2019-02-20T04:19:02Z",
      "check_opt_in": false,
      "check_opt_out": true,
      "status": "pre-processing"
    }
  ]
}

This endpoint retrieves a list of SMS batches.

HTTP Request

GET /sms

Query Parameter	Type	Required	Description	Example
page	integer	false	page number starting from 1; default = 1	`1`
page_size	integer	false	number of batches to retrieve per page; default = 25	`50`
start_date	string	false	retrieve batches at or after this date time; must be ISO-8601 format	`2018-03-01 08:00 -0600`
end_date	string	false	retrieve batches at or before this date time; must be ISO-8601 format	`2018-03-28 08:00 -0600`
status	string	false	retrieve batches with this status	`in-progress`
from	string	false	retrieve batches originated from this number	`4029999402`
sub_account_id	string	false	retrieve messages associated with this sub account	`1011`
fields	string	false	returns a partial response with specified fields	`status,from,body`

Retrieve an sms batch

Request:

curl --request GET \
  --url https://smsapi.voxtelesys.net/api/v1/sms/BPBPqNgILE2urR4S \
  --header 'authorization: Token token=176a78b0-8e81-4e56-9e3f-da67d17915bb'

Response: 200

{
  "id": "BPBPqNgILE2urR4S",
  "from": "14024431550",
  "to": ["4024431550","4024431551","4024439159"],
  "body": "Hi ${name}, your package is delivering to ${address} and should arrive around ${time}.",
  "parameters": {
    "definition": ["name","address","time"],
    "default": ["Customer",0,0],
    "4024431550": ["John","1111 Westroads Street","12:30 PM"],
    "4024431551": ["Luke","2222 Eastroads Plaza","1:00 PM"],
    "4024439159": ["Sarah","3333 Southroads Lane","4:45 PM"]
  },
  "send_at": "2019-02-20T04:18:56Z",
  "expire_at": "2019-02-23T04:18:56Z",
  "modified_at": "2019-02-20T04:19:02Z",
  "check_opt_in": false,
  "check_opt_out": true,
  "status": "pre-processing"
}

This endpoint retrieves a specified SMS batch.

HTTP Request

GET /sms/{id}

URL Parameter	Type	Required	Description	Example
id	string	true	ID of SMS batch	`BPBPqNgILE2urR4S`

Send an sms batch

Request:

curl --request POST \
  --url https://smsapi.voxtelesys.net/api/v1/sms \
  --header 'authorization: Token token=176a78b0-8e81-4e56-9e3f-da67d17915bb' \
  --header 'content-type: application/json' \
  --data '{
    "to": ["4024431550","4024431551","4024439159"],
    "from": "14024431550",
    "body": "Hi ${name}, your package is delivering to ${address} and should arrive around ${time}.",
    "parameters": {
      "definition": ["name","address","time"],
      "default": ["Customer",0,0],
      "4024431550": ["John","1111 Westroads Street","12:30 PM"],
      "4024431551": ["Luke","2222 Eastroads Plaza","1:00 PM"],
      "4024439159": ["Sarah","3333 Southroads Lane","4:45 PM"]
    }
  }'

Response: 200

{
  "id": "BPBPqNgILE2urR4S",
  "from": "14024431550",
  "to": ["4024431550","4024431551","4024439159"],
  "body": "Hi ${name}, your package is delivering to ${address} and should arrive around ${time}.",
  "parameters": {
    "definition": ["name","address","time"],
    "default": ["Customer",0,0],
    "4024431550": ["John","1111 Westroads Street","12:30 PM"],
    "4024431551": ["Luke","2222 Eastroads Plaza","1:00 PM"],
    "4024439159": ["Sarah","3333 Southroads Lane","4:45 PM"]
  },
  "send_at": "2019-02-20T04:18:56Z",
  "expire_at": "2019-02-23T04:18:56Z",
  "modified_at": "2019-02-20T04:19:02Z",
  "check_opt_in": false,
  "check_opt_out": true,
  "status": "pre-processing"
}

This endpoint creates a new SMS batch.

Parameterization

When creating an SMS batch, it is often required to customize parts of a message on a per recipient basis. Parameterization allows you to do just that!

When defining the message body, just insert as many parameter keys as is required. A parameter key is defined by entering ${parameter key} in the message body, where "parameter key" is the name of the parameter. For each specified parameter key, a recipient and parameter value must also be provided.

For example, the message body "Your appointment is scheduled for ${time}." contains the parameter key "time". When sending the batch, this parameter key would be replaced with the defined value.

Parameter values are then provided per recipient, or default values are provided. When providing parameter values, there are three component that must be addressed:

definition: Specifies the order in which parameter values will be provided in the "default" and "msisdn" arrays. Must be an array of unique parameter keys.

default: Specifies the default values. The default value is used if an associated MSISDN array is not provided. Array size must be the same as "definition", where an integer of 0 represents NULL or not provided.

msisdn: Specifies the parameter values to use for the specified MSISDN. Again, array size must be the same as "definition", where an integer of 0 represents NULL or not provided.

If a target MSISDN is missing a parameter, then the message will fail that MSISDN but not the entire batch.

HTTP Request

POST /sms

Body Param	Type	Required	Description	Example
to	array	true	list of msisdn	`["4024431550","4024431551","4024439159"]`
from	string	true	originator of message	`14029999402`
body	string	true	message body	`Hello world, this is a test message!`
parameters	object	false	object to hold params	see sample request
parameters.definition	array	false	order of params	`["name","address","time"]`
parameters.default	array	false	default params	`["Customer",0,0]`
parameters.{msisdn}	array	false	params for specific msisdn	`["John","1111 Westroads Street","12:30 PM"]`
send_at	string	false	date to start campaign; must be in ISO-8601 date format; default to start immediately	`2018-01-01 8:00:00 -0600`
expire_at	string	false	date to expire campaign; must be in ISO-8601 date format; default to 3 days from start_date	`2018-01-01 16:00:00 -0600`
check_opt_in	boolean	false	only send to opted-in msisdns	`false`
check_opt_out	boolean	false	do not send to opted-out msisdns	`false`
add_to_list	string	false	list to add msisdns to; must be init, single, double, or verified	`init`

Manage an sms batch

Request:

curl --request PUT \
  --url https://smsapi.voxtelesys.net/api/v1/sms/BPBPqNgILE2urR4S \
  --header 'authorization: Token token=176a78b0-8e81-4e56-9e3f-da67d17915bb'
  --header 'content-type: application/json' \
  --data '{
    "status": "pause"
  }

Response: 204

This endpoint allows you to start, pause, or cancel the specified SMS batch.

HTTP Request

PUT /sms/{id}

URL Parameter	Type	Required	Description	Example
id	string	true	ID of SMS batch	`BPBPqNgILE2urR4S`

Body Param	Type	Required	Description	Example
body	string	true	must be start, pause, or cancel	`pause`

Retrieve a delivery report

Request:

curl --request GET \
  --url https://smsapi.voxtelesys.net/api/v1/sms/BPBPqNgILE2urR4S/delivery_report?type=detailed \
  --header 'authorization: Token token=176a78b0-8e81-4e56-9e3f-da67d17915bb'

Response: 200

{
  "batch_id": "Z0S0jQOf8_hl9YRt",
  "batch_status": "in-progress",
  "count": 3,
  "results": [
    {
      "status": "queued",
      "count": 3,
      "to": [
        "14024439159",
        "14024431551",
        "14024431550"
      ]
    }
  ]
}

This endpoint retrieves a specified delivery report.

HTTP Request

GET /sms/{id}/delivery_report

URL Parameter	Type	Required	Description	Example
id	string	true	ID of SMS batch	`BPBPqNgILE2urR4S`

Query Parameter	Type	Required	Description	Example
type	string	false	report type; must be detailed or summary	`summary`

Errors

The SMS REST API uses the following HTTP error codes:

Code	Description
401	Unauthorized -- The provided token, request IP, and/or account are not valid. Use the `/authorize/login` to obtain a valid token.
404	Not Found -- The request URL and/or HTTP method is not valid.
422	Unprocessable Entity -- The request data and/or parameters are not valid.
500	Internal Server Error -- An error occurred within the server. Please contact Voxtelesys with the provided `error_id` to resolve this error.

SMS API Introduction

Base URL

Authentication

Persistent tokens

Short-lived tokens

Login Request

Messages

Message statuses

Retrieve inbound messages

HTTP Request

Retrieve outbound messages

HTTP Request

Applications

Actions

mo_callback

dr_callback

auto_reply

opt_in

opt_out

two_fact_auth

Create an application

HTTP Request

Replace an application

HTTP Request

Modify an application

HTTP Request

List applications

HTTP Request

Retrieve an application

HTTP Request

Delete an application

Callbacks

Longcodes

List longcodes

HTTP Request

Retrieve a longcode

HTTP Request

Update a longcode

HTTP Request

Two factor authentication

HTTP Request

HTTP Request

Longcode List Management

Retrieve subscriber list

HTTP Request

Retrieve subscriber

HTTP Request

Update subscriber

HTTP Request

Create subscriber

HTTP Request

Delete subscriber

HTTP Request

SMS Batches

Batch statuses

List sms batches

HTTP Request

Retrieve an sms batch

HTTP Request

Send an sms batch

Parameterization

HTTP Request

Manage an sms batch

HTTP Request

Retrieve a delivery report

HTTP Request

Errors