Navbar
shell
  • SMS API Introduction
  • Authentication
  • Messages
  • Applications
  • Callbacks
  • Longcodes
  • Longcode List Management
  • SMS Batches
  • Errors
  • 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": ""
    }
    

    Login Request

    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

    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:

    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.