API Documentation for Developers

GovDelivery Interactive Text allows you to build, schedule, and send interactive text message conversations to connect with the public. The RESTful JSON API allows you to automate many aspects of the system including:

  • Importing new participants, including data fields (referred to as tokens) that can be used to customize messages
  • Managing participants individually or in groups
  • Sending or scheduling polls or messages
  • Viewing response details

The API is in development and subject to change.

General notes

Authentication

All requests must include an authorization token. Use your login credentials to obtain an API token using the method described below. Use the API token to authenticate all subsequent requests.

Errors

Errors are returned using standard HTTP error codes. Additional information is returned in the body of the response.

Important Terms

  • Participants: Every phone number is represented as a Participant. This includes people who have responded to your surveys, as well as those you have uploaded. Participants can be assigned to Groups for segmentation.
  • Groups: Groups are used to organize Participants, primarily for sending outbound polls and messages.
  • Tokens: Tokens enable you to assign specific metadata to participants, to be used in customizing messages or polls.
  • Polls: Polls are a sequence of automated messages and questions. They can be used to send texts that do not require a response, or texts triggered by specific conditions such as a combination of previous responses.
  • Mailings: A Mailing is a scheduled send for a poll Mailings can be sent to a pre-defined group, or to a list of raw phone numbers
  • Responses: A response is an individual text message reply to a question

Authorization

POST /api/users/sign_in

Returns authorization token to be used with future requests.

Parameters:

email
string
password
password
curl -X POST -H "Content-Type: application/json" \ -d '{"password":"your_password", "email":"you@example.com"}' \ https://textizen.com/api/users/sign_in

Groups

GET /api/groups

List groups.

curl -X GET -H "Content-Type: application/json" \ -d '{"auth_token":"your_token"}' \ https://textizen.com/api/groups

GET /api/groups/{id}

Show detailed information about a group with the given ID.

curl -X GET -H "Content-Type: application/json" \ -d '{"auth_token":"your_token"}' \ https://textizen.com/api/groups/72

POST /api/groups

Create a new group.

Parameters:

group
name
string
curl -X POST -H "Content-Type: application/json" \ -d '{"group":{"name":"my group name"},"auth_token":"your_token"}' \ https://textizen.com/api/groups

PUT /api/groups/{id}

Update an existing group.

curl -X PUT -H "Content-Type: application/json" \ -d '{"group":{"name":"my updated group name"},"auth_token":"your_token"}' \ https://textizen.com/api/groups/2

Participants

GET /api/participants

List participants.

curl -X GET -H "Content-Type: application/json" \ -d '{"auth_token":"your_token"}' \ https://textizen.com/api/participants

GET /api/participants/{id}

Show detailed information about a participant with the given ID.

curl -X GET -H "Content-Type: application/json" \ -d '{"auth_token":"your_token"}' \ https://textizen.com/api/participants/58

POST /api/participants

Create new participant.

Parameters:

participant
phone_number
string
name
string
campaign_id optional
integer
curl -X POST -H "Content-Type: application/json" \ -d '{"participant":{"name":"Jane Q Public", "phone_number":"14155551212"},"campaign_id":"1","auth_token":"your_token"}' \ https://textizen.com/api/participants

PUT /api/participants/{id}

Update a participant.

Parameters

participant
phone_number
string
name
string
curl -X PUT -H "Content-Type: application/json" \ -d '{"name":"Katherine Goble Johnson", "phone_number": "14155551213", "auth_token":"your_token"}' \ https://textizen.com/api/participants/71

POST /api/participants/{id}/subscriptions

Add a participant to a group.

Parameters:

subscription
group_id
integer
curl -X POST -H "Content-Type: application/json" \ -d '{"group_id":"2", "auth_token":"your_token"}' \ https://textizen.com/api/participants/58/subscriptions

PUT /api/participants/{id}/subscriptions/unsubscribe

Remove a participant from a group.

Parameters:

group_id
integer
curl -X PUT -H "Content-Type: application/json" \ -d '{"group_id":"2", "auth_token":"your_token"}' \ https://textizen.com/api/participants/58/subscriptions/unsubscribe

GET /api/participants/{id}/tokens

List tokens for a participant.

Parameters:

campaign_id
integer
curl -X GET -H "Content-Type: application/json" \ -d '{"campaign_id":"1", "auth_token":"your_token"}' \ https://textizen.com/api/participants/58/tokens

PUT /api/participants/{id}/tokens

Set tokens for use in customized messages to a participant.

Parameters:

campaign_id
integer
tokens
keys
key value pairs of token values to be set on the participant
curl -X PUT -H "Content-Type: application/json" \ -d '{"campaign_id":"1", "tokens":{"token_key":"token_value"}, "auth_token":"your_token"}' \ https://textizen.com/api/participants/58/tokens

DELETE /api/participants/{id}/tokens

Remove tokens from a participant.

Parameters:

campaign_id
integer
tokens
string containing tokens to be removed, separated by commas
curl -X DELETE -H "Content-Type: application/json" \ -d '{"campaign_id":"1", "tokens":"abcd123", "auth_token":"your_token"}' \ https://textizen.com/api/participants/58/tokens

Polls

GET /api/polls

List polls.

curl -X GET -H "Content-Type: application/json" \ -d '{"auth_token":"your_token"}' \ https://textizen.com/api/polls

GET /api/polls/{id}

Show detailed information about a poll with the given ID, including questions and responses.

curl -X GET -H "Content-Type: application/json" \ -d '{"auth_token":"your_token"}' \ https://textizen.com/api/polls/3

POST /api/polls

Create a new poll.

Parameters:

poll
title
string
confirmation optional
text
error_message
text
language
string
public optional
boolean
active
boolean
type optional
string
curl -X POST -H "Content-Type: application/json" \ -d '{"title":"my poll", "confirmation":"confirmation text", "error_message":"Error happened", "language":"en", "public":"true", "active":"true", "auth_token":"your_token"}' \ https://textizen.com/api/polls

Mailings

GET /api/polls/{id}/mailings

List mailings for a followup poll.

curl -X GET -H "Content-Type: application/json" \ -d '{"auth_token":"your_token"}' \ https://textizen.com/api/polls/1/mailings

GET /api/mailings/{id}

Show detailed information about a mailing with the given ID.

curl -X GET -H "Content-Type: application/json" \ -d '{"auth_token":"your_token"}' \ https://textizen.com/api/mailings/1

POST /api/polls/{id}/mailings

Create a new mailing for the specified poll.

Parameters:

mailing
send_at
datetime
group_ids optional
array
phone_numbers_list optional
string containing phone numbers, separated by commas
curl -X POST -H "Content-Type: application/json" \ -d '{"send_at":"2017-03-14T19:26:53.895", "group_ids":[1,77], "phone_numbers_list":"14155551212,16515551212", "auth_token":"your_token"}' \ https://textizen.com/api/polls/1/mailings

PUT /api/mailings/{id}

Update existing mailing.

Parameters:

mailing
send_at
datetime
group_ids optional
array
phone_numbers_list optional
string containing phone numbers, separated by commas
curl -X PUT -H "Content-Type: application/json" \ -d '{"send_at":"2017-03-14T19:26:53.895", "group_ids":[1,77], "phone_numbers_list":"14155551212,16515551212", "auth_token":"your_token"}' \ https://textizen.com/api/mailings/2

Responses

GET /api/responses/{id}

Show detailed information about a given response.

curl -X GET -H "Content-Type: application/json" \ -d '{"auth_token":"your_token"}' \ https://textizen.com/api/responses/30

User

GET /api/user

Get current user's information.

curl -X GET -H "Content-Type: application/json" \ -d '{"auth_token":"your_token"}' \ https://textizen.com/api/user