Interactive Text

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.

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

Campaigns

GET /api/campaigns

List campaigns.

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

GET /api/campaigns/{id}

Show detailed information about a campaign with the given ID.

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

POST /api/campaigns

Create new campaign.

Parameters:

campaign

title: string
description: string
info_message optional: string
webhook_url optional: string
exchange optional: string

organization_id

integer

curl -X POST -H "Content-Type: application/json" \
-d '{"campaign":{"title":"Our new campaign","description":"A new campaign to gauge interest in our services","info_message":"Hello! Reply QUIT to unsubscribe.","webhook_url":"https://our.agency.gov/webhook","exchange":"867"},"organization_id":"1","auth_token":"your_token"}' \
https://textizen.com/api/campaigns

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 '{"subscription":{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.

group_id: integer

curl -X PUT -H "Content-Type: application/json" \
-d '{"subscription":{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.

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.

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 '{"poll":{"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 '{"mailing":{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 '{"mailing":{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

API Documentation for Developers

General notes

Authentication

Errors

Important Terms

Authorization

POST /api/users/sign_in

Groups

GET /api/groups

GET /api/groups/{id}

POST /api/groups

PUT /api/groups/{id}

Campaigns

GET /api/campaigns

GET /api/campaigns/{id}

POST /api/campaigns

Participants

GET /api/participants

GET /api/participants/{id}

POST /api/participants

PUT /api/participants/{id}

POST /api/participants/{id}/subscriptions

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

GET /api/participants/{id}/tokens

PUT /api/participants/{id}/tokens

DELETE /api/participants/{id}/tokens

Polls

GET /api/polls

GET /api/polls/{id}

POST /api/polls

Mailings

GET /api/polls/{id}/mailings

GET /api/mailings/{id}

POST /api/polls/{id}/mailings

PUT /api/mailings/{id}

Responses

GET /api/responses/{id}

User

GET /api/user

Company

Keep In Touch