Introduction

Welcome to the documentation for the Clearstream API. You can use our API to integrate third-party tools and applications with your Clearstream account.

Our API is under active development, and we plan to release more functionality. If there are specific features that you need, please contact our support department.

Adherence to our terms & conditions is a requirement for using our API.

Basics

The Clearstream API is organized following REST standards. All requests return properly-formatted JSON.

All API endpoints begin with: https://api.getclearstream.com/v1/

Authentication

# With curl, you can pass your API key as a header:
curl "https://api.getclearstream.com/v1/account"
  -H "X-Api-Key: ABCDEFG123"

Clearstream uses API keys in order to grant access to the API. You can register an API key from inside your account.

You should keep your API keys private, and store them securely. API keys have full access to your account and are 'owned' by the account owner. Therefore, all actions that are tied to a specific user, such as sending replies, are performed as if the account owner were performing them.

Your API key must be included in all API requests to the server in a header that looks like the following:

X-Api-Key: YOUR-API-KEY

API keys are tied to a single account and only have access to that account. However, owners of accounts with subaccounts have the ability to create API keys that can also access subaccounts. To specify which account/subaccount to use when interacting with the API, include the following header in the request:

X-Account-Id: YOUR-ACCOUNT-ID

Errors

If a request returns an HTTP status code of 200 (or anything in the 2xx range), you can assume the request was properly received and processed.

Otherwise, there was an error. The table below shows the possible errors and what they mean.

Status	Meaning
400	Bad Request -- There was something wrong with your request.
401	Unauthorized -- Your API key is incorrect.
403	Forbidden -- You do not have access to the requested resource.
404	Not Found -- The specified resource could not be found.
405	Method Not Allowed -- You tried to access a resource with an invalid method.
422	Unprocessable Entity -- Your request did not pass validation. Check the parameters you passed.
429	Too Many Requests -- You've made too many API requests in a short time.
500	Internal Server Error -- There was an issue on our end. Try your request again.
503	Service Unavailable -- The API is offline for maintenance. Try again later.

Rate Limits

Most endpoints have a rate limit of 120 requests per 60 seconds. If a request returns an HTTP status code of 429, you have hit the rate limit and should throttle your requests.

Text Messages

Text messaging as a technology has certain idiosyncrasies, which you should be aware of when using the API.

Allowed characters

Text messages can include essentially any character in the USC-2 character set, including emojis. Keep in mind that using characters outside the GSM 7-bit character set (such as emojis or non-English characters) reduces the character limit and may use more credits (see below).

Character limits & credits

A standard text message under 160 characters uses 1 credit. Longer texts or texts containing certain characters may use more credits.

The maximum length of a text message is 765 characters. However, if the text includes any character outside the GSM 7-bit character set (such as emojis or non-English characters) the maximum length is 335 characters.

See the charts below, or use this handy calculator we created.

Text Messages Containing Plain Text Only (GSM-7)

Number of characters	Credits used
0-160	1
161-306	2
307-459	3
460-612	4
613-765	5

Text Messages Containing Special Characters (USC-2)

Number of characters	Credits used
0-70	1
71-134	2
135-201	3
202-268	4
269-335	5

MMS

A text with an image (MMS) will always use 3 credits, regardless of its length.

Double Counting

Some characters, such as newer emojis and certain GSM 7-bit characters (shown below), require more bytes to encode and therefore are counted twice. We recommend using our handy calculator if you need to ensure your text message stays under a certain limit.

Character	Name	Length
^	Caret	2
|	Vertical Bar	2
{	Curly Bracket Open	2
}	Curly Bracket Close	2
[	Square Backet Open	2
]	Square Bracket Close	2
~	Tilde	2
\	Backslash	2

Changelog

We routinely make additions to the API based on customer requests. Breaking changes to documented API endpoints and data will only be made in exceptional circumstances, such as security issues or bug fixes.

2024-12-10

The created_at and updated_at filters were added to the view all subscribers endpoint.

2024-01-03

When viewing an archived keyword, you can now see when that keyword was archived.

2024-01-03

When sending a message, subscribers now fails if none of the mobile numbers are valid. If at least one mobile number is valid, the message will be sent to the valid numbers only.

2023-04-27

The attribute contacts was added to the message endpoints. It represents contacts that were directly attached to the message. Each contact row has the following attributes: id, first, last, email, and mobile_nummber.

2023-04-25

When viewing your account, total_subscribers now returns a count of all subscribers regardless of status. Previously, only active contacts were counted.

2023-04-13

The type and filename attributes were added to the upload media endpoint.

2023-04-05

The following changes were made to the message.report webhook: * A new type field was added to the message object. It can be either SMS, MMS, or EMAIL. * A new email field was added to the message object. When type is EMAIL, this field will contain the subject of the email: "email": ["subject": "string"]. Otherwise, it will be null. * text and number are null when type is EMAIL. * email is null when type is either SMS or MMS.

2023-03-15

The parameter message_header is no longer required when using the send message endpoint if number is a longcode or dedicated shortcode.

2023-02-14

The following endpoints now accept and prefer an array of list IDs:

• The update a subscriber endpoint lists parameter accepts an array of list IDs.
• The send a message endpoint lists parameter accepts an array of list IDs.
• The create a keyword endpoint opt_in_lists parameter accepts an array of list IDs. And it is no longer required when the keyword opts-in subscribers.

2023-01-26

The parameter media_url was added to the send message endpoint as an alternative method of sending a message with an image.

2023-01-25

The attributes type, text.full, and media were added to related_message attributes of thread endpoints.

2023-01-24

The attributes pco_person_id, ccb_profile_id, and rock_person_id were added to all subscriber endpoints.

2023-01-17

The recipients attribute of message stats now refers to the total number of recipients. (Previously, it counted only successfully delivered texts.)

A new successful attribute has been added to indicate successful deliveries. The following endpoints/webhooks are affected:

• View All Messages
• View a Message
• Message Report

2023-01-10

The create a subscriber endpoint lists parameter now accepts and prefers an array of list IDs.

2023-01-09

A new endpoint was added to allow uploading an image. This endpoint can be used in conjunction with the send message endpoint to send a message with an image:

• Upload Media

2022-10-19

The attribute thread was added to the text.received webhook.

2022-06-29

The parameter number was added to the create keyword endpoint to allow specifying the number to use for the keyword.

2022-06-28

The create thread endpoint longcode parameter was renamed to number to allow specifying either a longcode or shortcode. (To avoid a breaking change, longcode is still accepted.)

2022-05-25

The send a text endpoint now supports sending to multiple numbers.

2022-03-29

The behavior of the parameter override_optouts was changed for the send a text endpoint, as well as for the Incoming Text and Keyword Used webhook responses. Passing override_optouts=true will no longer change the status of an existing subscriber.

2022-03-03

The parameter include_subaccounts was added to the opt-out subscriber endpoint to allow easily opting-out a subscriber from all accounts.

2022-01-25

The attribute subscriber was added to the Incoming Text webhook payload.

2022-01-22

The parameter status was added to the update subscriber endpoint to allow easily updating the opt-in status of an existing subscriber.

2021-12-23

A new endpoint was added to allow creating & updating multiple subscribers in a single request:

• Create/Update Multiple Subscribers

2021-12-06

The parameter use_default_header is now accepted in JSON responses to the Incoming Text and Keyword Used webhooks.

2021-11-28

The parameter use_default_header was added to the send message endpoint and send text endpoint to allow sending texts with an account's default header, rather than passing it in the request.

2021-07-20

A new endpoint was added to get the numbers an account can send from:

• View All Numbers

The attribute locked was added to the view all lists and view a list endpoints. Lists can also now be filtered by whether they are locked.

The lists parameter is now optional for the create a subscriber endpoint. Subscribers can now be created and opted-in without being added to a list.

Customer support approval is no longer needed to disable the double opt-in process for the create a subscriber endpoint .

2021-07-01

The parameter number was added to the send message endpoint to allow specifying the number to use when sending a message.

2021-04-20

The attribute media was added to the text.received, text.failed, and message.report webhooks. The attribute user was added to the message endpoints. The attribute user was updated to return null instead of an empty array for the inbox endpoints.

2021-04-13

The attributes ccb_group_id, rock_group_id, last_synced_at, and created_at were added to all list endpoints. The undocumented linked_to attribute was removed from all list endpoints.

2021-03-02

The character limit for outgoing texts was raised and support for emojis & non-English characters was added. Review character limits & credits.

2021-02-24

The parameter force_delete was removed from the delete list endpoint as subscriber statuses are no longer affected when deleting a list. The attribute credits_used was added to messages.

2021-02-17

The datetime attribute updated_at for a subscriber was adjusted to update whenever a subscriber is added to or removed from a list, whether through the API or web app.

2020-11-11

Webhook requests now include a simple way to authenticate the request.

2020-11-03

The Incoming Text webhook may now ingest a JSON response to trigger a text message reply.

The boolean attribute production was added to all webhook payloads.

2020-09-29

The parameter override_optouts was changed to default to false for the create subscriber endpoint.

2020-08-12

The parameters double_optin and override_optouts were added to the create subscriber endpoint.

2020-05-28

Rate limits were increased to 120 requests per minute for most endpoints.

2020-05-20

API keys may now optionally access subaccounts.

2020-05-14

A new endpoint was added to facilitate sending one-off text messages to phone numbers that may or may not be subscribed:

• Send a Text

2020-05-13

Two new webhooks were added to be notified of incoming texts and failed outgoing texts:

• Incoming Text
• Text Failed To Send

2020-04-30

A new endpoint was added to get statistics about replies to a specific message:

• Message Replies

2020-04-27

A unique_numbers parameter was added to the statistics endpoints to restrict statistical data to unique mobile numbers. An archived parameter was added to the threads endpoint to allow accessing archived threads.

2020-03-18

Two new endpoints were added to facilitate adding/removing subscribers to/from lists:

• Add Subscriber to a List
• Remove Subscriber from a List

A lists parameter was added to the update subscriber endpoint to allow updating a subscriber's lists.

2020-01-14

A new endpoint was added to allow creating a new thread:

• Create a Thread

The parameters text, full_name, and mobile_number were added to the threads endpoint to improve search capability.

2019-12-10

The attribute joined_at was added to the list subscribers endpoint and subscribers endpoint. The attributes opted_in_at and opted_out_at were added to the subscribers endpoint.

2019-10-28

Five new endpoints were added for accessing statistical data:

• Total Subscribers
• Opt-ins & Opt-outs
• Incoming & Outgoing Texts
• Keyword Uses (All)
• Keyword Uses (Single)

2019-05-08

The character limit for sending a message was increased to 320.

Account

View Account

curl "https://api.getclearstream.com/v1/account"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "data": {
    "business": "The Early Church",
    "status": "ACTIVE",
    "phone": "+12005551234",
    "credits": 2000,
    "total_subscribers": 2030,
    "collect_emails": false,
    "next_billing_date": "2022-07-01",
    "plan": {
      "name": "$29",
      "cost": 29,
      "credits": 500,
      "keywords": 2
    },
    "stats": {
      "timezone": "UTC",
      "opt_ins": {
        "past_7_days": {
          "total": 115,
          "chart": {
            "day": {
              "2022-06-01": 15,
              "2022-06-02": 12,
              "2022-06-03": 10,
              "2022-06-04": 20,
              "2022-06-05": 23,
              "2022-06-06": 21,
              "2022-06-07": 14
            }
          }
        },
        "past_month": {
          "total": 430
        }
      },
      "opt_outs": {
        "total": 250,
        "rate": 0.05
      },
      "messages": {
        "total": 120,
        "this_week": {
          "total": 2
        },
        "this_month": {
          "total": 4
        },
        "this_year": {
          "total": 40
        }
      }
    }
  }
}

This endpoint retrieves your account details.

HTTP Request

GET https://api.getclearstream.com/v1/account

Parameters

Parameter	Type	Required	Default	Description
timezone	string	false	UTC	If specified, statistical data respects the given timezone. Must be a valid, supported timezone.
include_stats	boolean	false	true	Whether to include the stats property with statistics.

Update Account

curl -X PATCH "https://api.getclearstream.com/v1/account"
  -H "X-Api-Key: ABCDEFG123"
  -d "business=The Early Church Youth"

The above command returns:

{
  "data": {
    "business": "The Early Church Youth",
    "status": "ACTIVE",
    "phone": "+12005551234",
    "credits": 2000,
    "total_subscribers": 2030,
    "collect_emails": false,
    "next_billing_date": "2022-07-01",
    "plan": {
      "name": "$29",
      "cost": 29,
      "credits": 500,
      "keywords": 2
    },
    "stats": {
      "opt_ins": {
        "past_7_days": {
          "total": 115,
          "chart": {
            "timezone": "UTC",
            "day": {
              "2022-06-01": 15,
              "2022-06-02": 12,
              "2022-06-03": 10,
              "2022-06-04": 20,
              "2022-06-05": 23,
              "2022-06-06": 21,
              "2022-06-07": 14
            }
          }
        },
        "past_month": {
          "total": 430
        }
      },
      "opt_outs": {
        "total": 250,
        "rate": 0.05
      },
      "messages": {
        "total": 120,
        "this_week": {
          "total": 2
        },
        "this_month": {
          "total": 4
        },
        "this_year": {
          "total": 40
        }
      }
    }
  }
}

This endpoint updates your basic account information. Only the parameters that are passed are updated.

HTTP Request

PATCH https://api.getclearstream.com/v1/account

Parameters

Parameter	Type	Required	Description
business	string	false	The name of your church or organization.
phone	string	false	Phone number for your account.
collect_emails	bool	false	Whether your account should automatically collect email addresses from incoming texts.

Users

View All Users

curl "https://api.getclearstream.com/v1/users"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "data": [
    {
      "email": "robert@theearly.church",
      "name": "Robert",
      "image": null,
      "email_notifications": {
        "incoming_reply": true,
        "opt_in": true,
        "opt_out": false,
        "keyword_use": false,
        "message_fail": false,
        "weekly_report": false
      },
      "push_notifications": {
        "incoming_reply": true
      },
      "timezone": "America/New_York",
      "owner": true,
      "role": "owner"
    },
    {
      "email": "sue@theearly.church",
      "name": "Sue",
      "image": null,
      "email_notifications": {
        "incoming_reply": true,
        "opt_in": true,
        "opt_out": false,
        "keyword_use": false,
        "message_fail": false,
        "weekly_report": false
      },
      "push_notifications": {
        "incoming_reply": true
      },
      "timezone": "America/New_York",
      "owner": false,
      "role": "editor"
    }
  ]
}

This endpoint retrieves a listing of all users of your account.

HTTP Request

GET https://api.getclearstream.com/v1/users

View a User

curl "https://api.getclearstream.com/v1/users/sue@theearly.church"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "data": {
    "email": "sue@theearly.church",
    "name": "Sue",
    "image": null,
    "email_notifications": {
      "incoming_reply": true,
      "opt_in": true,
      "opt_out": false,
      "keyword_use": false,
      "message_fail": false,
      "weekly_report": false
    },
    "push_notifications": {
      "incoming_reply": true
    },
    "timezone": "America/New_York",
    "owner": false,
    "role": "editor"
  }
}

This endpoint retrieves details for the specified user.

HTTP Request

GET https://api.getclearstream.com/v1/users/<email>

Lists

View All Lists

curl "https://api.getclearstream.com/v1/lists"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "count": 2,
  "total": 2,
  "current_page": 1,
  "pages": 1,
  "limit": 100,
  "data": [
    {
      "id": 1000,
      "name": "Entire Church",
      "subscriber_count": 2000,
      "locked": false,
      "pco_list_id": null,
      "ccb_group_id": null,
      "rock_group_id": null,
      "last_synced_at": null,
      "created_at": "2022-01-01T10:00:09+00:00"
    },
    {
      "id": 1001,
      "name": "Group Leaders (imported from PCO)",
      "subscriber_count": 30,
      "locked": true,
      "pco_list_id": "100",
      "ccb_group_id": null,
      "rock_group_id": null,
      "last_synced_at": "2022-01-02T10:00:10+00:00",
      "created_at": "2022-01-01T10:00:10+00:00"
    },
    {
      "id": 1002,
      "name": "New To Church (imported from CCB)",
      "subscriber_count": 180,
      "locked": true,
      "pco_list_id": null,
      "ccb_group_id": "200",
      "rock_group_id": null,
      "last_synced_at": "2022-01-01T11:00:00+00:00",
      "created_at": "2022-01-01T10:00:11+00:00"
    },
    {
      "id": 1003,
      "name": "Parents of Toddlers (imported from Rock RMS)",
      "subscriber_count": 520,
      "locked": true,
      "pco_list_id": null,
      "ccb_group_id": null,
      "rock_group_id": "300",
      "last_synced_at": "2022-01-02T11:00:12+00:00",
      "created_at": "2022-01-01T10:00:12+00:00"
    }
  ]
}

This endpoint retrieves a listing of all lists in your account. Results are paginated. You may cycle through the pages by adjusting the page and limit parameters.

HTTP Request

GET https://api.getclearstream.com/v1/lists

Parameters

Parameter	Type	Required	Default	Description
limit	integer	false	100	Limit the number of results per page.
page	integer	false	1	The page to show.
filter[locked]	string	false	any	Filter lists based on their locked status. Accepted options are locked, not_locked, and any.
filter[name]	string	false	null	Search by list name. (Partial match is acceptable.)

View a List

curl "https://api.getclearstream.com/v1/lists/1000"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "data": {
    "id": 1000,
    "name": "Entire Church",
    "subscriber_count": 2000,
    "locked": false,
    "pco_list_id": null,
    "ccb_group_id": null,
    "rock_group_id": null,
    "last_synced_at": null,
    "created_at": "2022-01-01T10:00:09+00:00"
  }
}

This endpoint retrieves details for the specified list.

HTTP Request

GET https://api.getclearstream.com/v1/lists/<id>

Create a List

curl -X POST "https://api.getclearstream.com/v1/lists"
  -H "X-Api-Key: ABCDEFG123"
  -d "name=New List"

The above command returns:

{
  "data": {
    "id": 1002,
    "name": "New List",
    "subscriber_count": 0,
    "pco_list_id": null,
    "ccb_group_id": null,
    "rock_group_id": null,
    "last_synced_at": null,
    "created_at": "2022-01-01T10:00:09+00:00"
  }
}

This endpoint creates a new list.

HTTP Request

POST https://api.getclearstream.com/v1/lists

Parameters

Parameter	Type	Required	Description
name	string	true	The name of the list to create. Must be unique for your account.

Update a List

curl -X PATCH "https://api.getclearstream.com/v1/lists/1002"
  -H "X-Api-Key: ABCDEFG123"
  -d "name=Updated List"

The above command returns:

{
  "data": {
    "id": 1002,
    "name": "Updated List",
    "subscriber_count": 0,
    "pco_list_id": null,
    "ccb_group_id": null,
    "rock_group_id": null,
    "last_synced_at": null,
    "created_at": "2022-01-01T10:00:09+00:00"
  }
}

This endpoint updates the specified list.

HTTP Request

PATCH https://api.getclearstream.com/v1/lists/<id>

Parameters

Parameter	Type	Required	Description
name	string	true	The name of the list. Must be unique for your account.

Delete a List

curl -X DELETE "https://api.getclearstream.com/v1/lists/1002"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "deleted": true,
  "id": 1002
}

This endpoint deletes the specified list. Deleting a list does not affect the opt-in status of subscribers that were in the list.

HTTP Request

DELETE https://api.getclearstream.com/v1/lists/<id>

View Subscribers For a List

curl "https://api.getclearstream.com/v1/lists/1000/subscribers"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "count": 2,
  "total": 2,
  "current_page": 1,
  "pages": 1,
  "limit": 20,
  "data": [
    {
      "mobile_number": "+12005550000",
      "status": "ACTIVE",
      "first": "Jane",
      "last": "Doe",
      "full_name": "Jane Doe",
      "email": null,
      "source": null,
      "source_category": "Api",
      "pco_person_id": null,
      "ccb_profile_id": null,
      "rock_person_id": null,
      "created_at": "2022-01-01T12:00:00+00:00",
      "updated_at": "2022-01-01T12:00:00+00:00",
      "joined_at": "2022-01-01T12:00:00+00:00",
      "opted_in_at": "2022-01-01T12:00:00+00:00",
      "opted_out_at": null
    },
    {
      "mobile_number": "+12005550001",
      "status": "ACTIVE",
      "first": "John",
      "last": "Doe",
      "full_name": "John Doe",
      "email": null,
      "source": null,
      "source_category": "Integration",
      "pco_person_id": null,
      "ccb_profile_id": null,
      "rock_person_id": null,
      "created_at": "2022-01-01T12:00:00+00:00",
      "updated_at": "2022-01-01T12:00:00+00:00",
      "joined_at": "2022-01-01T12:00:00+00:00",
      "opted_in_at": "2022-01-01T12:00:00+00:00",
      "opted_out_at": null
    }
  ]
}

This endpoint retrieves details for the subscribers contained in the specified list. Results are paginated. You may cycle through the pages by adjusting the page and limit parameters. You may also perform a search by passing any combination of first, last, full_name, and mobile_number parameters.

HTTP Request

GET https://api.getclearstream.com/v1/lists/<id>/subscribers

Parameters

Parameter	Type	Required	Default	Description
limit	integer	false	20	Limit the number of results per page.
page	integer	false	1	The page to show.
filter[full_name]	string	false	null	Search by full name. (Partial match is acceptable.)
filter[first]	string	false	null	Search by first name. (Partial match is acceptable.)
filter[last]	string	false	null	Search by last name. (Partial match is acceptable.)
filter[mobile_number]	string	false	null	Search by mobile number. (Partial match is acceptable.)
filter[status]	string	false	null	Search by status. Accepted values are ACTIVE, OPTOUT, INACTIVE, and ANY.
operator	string	false	'or'	If passing multiple search parameters, the operator to use. May be set to or or and.
sort	string	false	null	Accepted values are full_name, -full_name, joined_at, -joined_at, created_at, -created_at. By default records are sorted in ascending order. You can use the - prefix to sort descendingly.

Add Subscriber To a List

curl -X POST "https://api.getclearstream.com/v1/lists/1000/subscribers"
  -H "X-Api-Key: ABCDEFG123"
  -d "mobile_number=+12005550000"

The above command returns:

{
  "data": {
    "mobile_number": "+12005550000",
    "status": "ACTIVE",
    "first": "Jane",
    "last": "Doe",
    "full_name": "Jane Doe",
    "email": null,
    "source_category": "Manual",
    "pco_person_id": null,
    "ccb_profile_id": null,
    "rock_person_id": null,
    "created_at": "2022-01-01T12:00:00+00:00",
    "updated_at": "2022-01-01T12:00:00+00:00",
    "joined_at": "2022-01-01T12:00:00+00:00",
    "opted_in_at": "2022-01-01T12:00:00+00:00",
    "opted_out_at": null
  }
}

This endpoint adds an already existing subscriber to the specified list.

HTTP Request

POST https://api.getclearstream.com/v1/lists/<id>/subscribers

Parameters

Parameter	Type	Required	Description
mobile_number	string	true	The mobile number of the subscriber to add to the list. Should be in E.164 format.

Remove Subscriber from a List

curl -X DELETE "https://api.getclearstream.com/v1/lists/1000/subscribers/+12005550000"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "deleted": true,
  "mobile_number": "+12005550000",
  "list_id": 1000
}

This endpoint removes an existing subscriber from the specified list.

HTTP Request

DELETE https://api.getclearstream.com/v1/lists/<id>/subscribers/<number>

Tags

View All Tags

curl "https://api.getclearstream.com/v1/tags"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "count": 2,
  "total": 2,
  "current_page": 1,
  "pages": 1,
  "limit": 100,
  "data": [
    {
      "id": 2345,
      "name": "Volunteer",
      "subscriber_count": 14
    },
    {
      "id": 3001,
      "name": "Visitor",
      "subscriber_count": 42
    }
  ]
}

This endpoint retrieves details of all the tags in your account. Results are paginated. You may cycle through the pages by adjusting the page and limit parameters.

HTTP Request

GET https://api.getclearstream.com/v1/tags

Parameters

Parameter	Type	Required	Default	Description
limit	integer	false	100	Limit the number of results per page.
page	integer	false	1	The page to show.
filter[name]	string	false	null	Search by tag name. (Partial match is acceptable.)

Create a Tag

curl -X POST "https://api.getclearstream.com/v1/tags"
  -H "X-Api-Key: ABCDEFG123"
  -d "name=New Tag"

The above command returns:

{
  "data": {
    "id": 1003,
    "name": "New Tag"
  }
}

This endpoint creates a new tag.

HTTP Request

POST https://api.getclearstream.com/v1/tags

Parameters

Parameter	Type	Required	Description
name	string	true	The name of the tag to create. Must be unique for your account.

Add Tag To Subscribers

curl -X POST "https://api.getclearstream.com/v1/tags/2345/subscribers"
  -H "X-Api-Key: ABCDEFG123"
  -d "mobile_numbers[]=+12005550000"

The above command returns:

{
  "data": {
    "id": 2345,
    "name": "Volunteer",
    "subscribers_tagged": 1
  }
}

This endpoint adds the specified tag to existing subscribers.

HTTP Request

POST https://api.getclearstream.com/v1/tags/<id>/subscribers

Parameters

Parameter	Type	Required	Description
mobile_numbers	array	true	The mobile numbers of the subscribers to tag. Should be in E.164 format.

Subscribers

View All Subscribers

curl "https://api.getclearstream.com/v1/subscribers"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "count": 2,
  "total": 2,
  "current_page": 1,
  "pages": 1,
  "limit": 20,
  "data": [
    {
      "mobile_number": "+12005551000",
      "status": "ACTIVE",
      "first": "Jane",
      "last": "Doe",
      "full_name": "Jane Doe",
      "email": null,
      "avatar_url": null,
      "source": {
        "id": 12345,
        "name": "earlychurch",
        "header": "The Early Church",
        "shortcode": "55498",
        "longcode": null,
        "type": "shortcode",
        "autoresponse": {
          "enabled": false,
          "text": {
            "full": null,
            "header": null,
            "body": null
          },
          "setting": null
        },
        "opt_in": {
          "enabled": true,
          "lists": []
        },
        "stats": {
          "opt_ins": {
            "total": 100
          },
          "uses": {
            "total": 100
          }
        }
      },
      "source_category": "Keyword",
      "pco_person_id": 12345,
      "ccb_profile_id": null,
      "rock_person_id": null,
      "lists": [
        {
          "id": 1000,
          "name": "Entire Church",
          "joined_at": "2022-01-01T12:00:00+00:00"
        }
      ],
      "tags": [
        {
          "id": 2345,
          "name": "Volunteer"
        }
      ],
      "created_at": "2022-01-01T12:00:00+00:00",
      "updated_at": "2022-01-01T12:00:00+00:00",
      "opted_in_at": "2022-01-01T12:00:00+00:00",
      "opted_out_at": null
    },
    {
      "mobile_number": "+12005551001",
      "status": "ACTIVE",
      "first": "John",
      "last": "Doe",
      "full_name": "John Doe",
      "email": null,
      "avatar_url": null,
      "source": null,
      "source_category": "Manual",
      "pco_person_id": null,
      "ccb_profile_id": null,
      "rock_person_id": null,
      "lists": [
        {
          "id": 1000,
          "name": "Entire Church",
          "joined_at": "2022-01-01T12:00:00+00:00"
        }
      ],
      "tags": [],
      "created_at": "2022-01-01T12:00:00+00:00",
      "updated_at": "2022-01-01T12:00:00+00:00",
      "opted_in_at": "2022-01-01T12:00:00+00:00",
      "opted_out_at": null
    }
  ]
}

This endpoint retrieves details of all subscribers in your account. Results are paginated. You may cycle through the pages by adjusting the page and limit parameters. You may also perform a search by passing any combination of first, last, full_name, and mobile_number parameters.

HTTP Request

GET https://api.getclearstream.com/v1/subscribers

Parameters

Parameter	Type	Required	Default	Description
limit	integer	false	20	Limit the number of results per page.
page	integer	false	1	The page to show.
filter[full_name]	string	false	null	Search by full name. (Partial match is acceptable.)
filter[first]	string	false	null	Search by first name. (Partial match is acceptable.)
filter[last]	string	false	null	Search by last name. (Partial match is acceptable.)
filter[mobile_number]	string	false	null	Search by mobile number. (Partial match is acceptable.)
filter[status]	string	false	ACTIVE	Search by status. Accepted values are ACTIVE, OPTOUT, INACTIVE, and ANY.
filter[created_at]	string	false	null	Search subscribers created on a specific date and time. Accepted value is an ISO 8601 formatted date: 2024-01-01T10:00:00+00:00.
filter[created_at][gt]	string	false	null	Search subscribers created after a specific date and time. Accepted value is an ISO 8601 formatted date: 2024-01-01T10:00:00+00:00.
filter[created_at][gte]	string	false	null	Search subscribers created on or after a specific date and time. Accepted value is an ISO 8601 formatted date: 2024-01-01T10:00:00+00:00.
filter[created_at][lt]	string	false	null	Search subscribers created before a specific date and time. Accepted value is an ISO 8601 formatted date: 2024-01-01T10:00:00+00:00.
filter[created_at][lte]	string	false	null	Search subscribers created on or before a specific date and time. Accepted value is an ISO 8601 formatted date: 2024-01-01T10:00:00+00:00.
filter[updated_at]	string	false	null	Search subscribers updated on a specific date and time. Accepted value is an ISO 8601 formatted date: 2024-01-01T10:00:00+00:00.
filter[updated_at][gt]	string	false	null	Search subscribers updated after a specific date and time. Accepted value is an ISO 8601 formatted date: 2024-01-01T10:00:00+00:00.
filter[updated_at][gte]	string	false	null	Search subscribers updated on or after a specific date and time. Accepted value is an ISO 8601 formatted date: 2024-01-01T10:00:00+00:00.
filter[updated_at][lt]	string	false	null	Search subscribers updated before a specific date and time. Accepted value is an ISO 8601 formatted date: 2024-01-01T10:00:00+00:00.
filter[updated_at][lte]	string	false	null	Search subscribers updated on or before a specific date and time. Accepted value is an ISO 8601 formatted date: 2024-01-01T10:00:00+00:00.
operator	string	false	'or'	If passing multiple search parameters, the operator to use. May be set to or or and.
sort	string	false	null	Accepted values are full_name, -full_name, created_at, -created_at. By default records are sorted in ascending order. You can use the - prefix to sort descendingly.

View a Subscriber

curl "https://api.getclearstream.com/v1/subscribers/+12005551000"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "data": {
    "mobile_number": "+12005551000",
    "status": "ACTIVE",
    "first": "Jane",
    "last": "Doe",
    "full_name": "Jane Doe",
    "email": null,
    "avatar_url": "https://avatars.planningcenteronline.com/uploads/person/119365302-1672672902/avatar.1.gif",
    "source": {
      "id": 12345,
      "name": "earlychurch",
      "header": "The Early Church",
      "shortcode": "55498",
      "longcode": null,
      "type": "shortcode",
      "autoresponse": {
        "enabled": false,
        "text": {
          "full": null,
          "header": null,
          "body": null
        },
        "setting": null
      },
      "opt_in": {
        "enabled": true,
        "lists": []
      },
      "stats": {
        "opt_ins": {
          "total": 100
        },
        "uses": {
          "total": 100
        }
      }
    },
    "source_category": "Keyword",
    "pco_person_id": null,
    "ccb_profile_id": 123,
    "rock_person_id": null,
    "lists": [
      {
        "id": 1000,
        "name": "Entire Church",
        "joined_at": "2022-01-01T12:00:00+00:00"
      }
    ],
    "tags": [
      {
        "id": 2345,
        "name": "Volunteer"
      }
    ],
    "created_at": "2022-01-01T12:00:00+00:00",
    "updated_at": "2022-01-01T12:00:00+00:00",
    "opted_in_at": "2022-01-01T12:00:00+00:00",
    "opted_out_at": null
  }
}

This endpoint retrieves details for the specified subscriber.

HTTP Request

GET https://api.getclearstream.com/v1/subscribers/<number>

Create a Subscriber

curl -X POST "https://api.getclearstream.com/v1/subscribers"
  -H "X-Api-Key: ABCDEFG123"
  -H "Content-Type: application/json"
  -d '{
    "mobile_number":"+12005551002",
    "lists":[1000,1001]
  }'

The above command returns:

{
  "data": {
    "mobile_number": "+12005551002",
    "status": "INACTIVE",
    "first": null,
    "last": null,
    "full_name": null,
    "email": null,
    "avatar_url": null,
    "source_category": "Api",
    "pco_person_id": null,
    "ccb_profile_id": null,
    "rock_person_id": null,
    "lists": [
      {
        "id": 1000,
        "name": "Entire Church",
        "joined_at": "2022-01-01T12:00:00+00:00"
      },
      {
        "id": 1001,
        "name": "Staff",
        "joined_at": "2022-01-01T12:00:00+00:00"
      }
    ],
    "tags": [],
    "created_at": "2022-01-01T12:00:00+00:00",
    "updated_at": "2022-01-01T12:00:00+00:00",
    "opted_in_at": null,
    "opted_out_at": null
  }
}

This endpoint creates a new subscriber and adds them to the specified list(s).

HTTP Request

POST https://api.getclearstream.com/v1/subscribers

Parameters

Parameter	Type	Required	Default	Description
mobile_number	string	true	null	The mobile number of the subscriber to create. Must be in E.164 format.
lists	array, string	false	null	An array of list IDs to add the subscriber to is preferred. Alternatively, a comma-separated string of list IDs is accepted.
first	string	false	null	The first name of the subscriber.
last	string	false	null	The last name of the subscriber.
email	string	false	null	The email address of the subscriber.
autoresponse_header	string	false	null	Header for the autoresponse text that a subscriber should receive after confirming their opt-in. If double_optin is false the autoresponse text will send immediately. Should be the name of your church or organization. Can contain only GSM 7-bit characters. Required if autoresponse_body is supplied.
autoresponse_body	string	false	null	Body for the autoresponse text that a subscriber should receive after confirming their opt-in. If double_optin is false the autoresponse text will send immediately. Together, the autoresponse_header and autoresponse_body cannot exceed the text message character limit. Required if autoresponse_header is supplied.
double_optin	boolean	false	true	Whether to send a confirmation text before opting-in the subscriber.
override_optouts	boolean	false	false	Whether to opt-in the subscriber even if they are opted-out. *This option is only available for accounts using a dedicated shortcode.
overwrite_attributes	boolean	false	false	Whether to overwrite the subscriber's attributes if one with the provided mobile number exists.

Update a Subscriber

curl -X PATCH "https://api.getclearstream.com/v1/subscribers/+12005551002"
  -H "X-Api-Key: ABCDEFG123"
  -d "first=Bob"
  -d "last=Doe"
  -d "email=bob@theearly.church"

The above command returns:

{
  "data": {
    "mobile_number": "+12005551002",
    "status": "ACTIVE",
    "first": "Bob",
    "last": "Doe",
    "full_name": "Boe Doe",
    "email": "bob@theearly.church",
    "avatar_url": null,
    "source_category": "Api",
    "pco_person_id": null,
    "ccb_profile_id": null,
    "rock_person_id": null,
    "lists": [
      {
        "id": 1000,
        "name": "Entire Church",
        "joined_at": "2022-01-01T12:00:00+00:00"
      },
      {
        "id": 1001,
        "name": "Staff",
        "joined_at": "2022-01-01T12:00:00+00:00"
      }
    ],
    "tags": [
      {
        "id": 2345,
        "name": "Volunteer"
      }
    ],
    "created_at": "2022-01-01T12:00:00+00:00",
    "updated_at": "2022-01-01T12:30:00+00:00",
    "opted_in_at": "2022-01-01T12:00:00+00:00",
    "opted_out_at": null
  }
}

This endpoint updates the specified subscriber.

HTTP Request

PATCH https://api.getclearstream.com/v1/subscribers/<number>

Parameters

Parameter	Type	Required	Description
first	string	false	The first name of the subscriber.
last	string	false	The last name of the subscriber.
email	string	false	The email address of the subscriber.
lists	array, string	false	An array of list IDs is preferred. Alternatively, a comma-separated string of list IDs is accepted. If you pass this parameter, the subscriber will be added to the specified lists and removed from all other lists. (Lists that are locked will be ignored.)
tags	array	false	An array of tag IDs. If you pass this parameter, the specified tags will be added to the subscriber and all other tags will be removed.
status	string	false	If you wish to update the subscriber's opt-in status, you can pass ACTIVE to opt them in, or OPTOUT to opt them out. *Note that opted-out subscriber can only be opted-in again via the API if your account uses a dedicated shortcode.

Opt-Out a Subscriber

curl -X DELETE "https://api.getclearstream.com/v1/subscribers/+12005551002"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "deleted": true,
  "mobile_number": "+12005551002"
}

This endpoint opts-out the specified subscriber and removes them from all lists.

HTTP Request

DELETE https://api.getclearstream.com/v1/subscribers/<number>

Parameters

Parameter	Type	Required	Default	Description
include_subaccounts	bool	false	false	If true, the subscriber will be opted-out of all subaccounts as well. *This parameter can only be used when making the request to the main account.

Create/Update Multiple Subscribers

curl -X POST "https://api.getclearstream.com/v1/subscribers/batch"
  -H "Content-Type: application/json"
  -H "X-Api-Key: ABCDEFG123"
  -d '{
  "data":[
    {
      "mobile_number":"+12005550000",
      "lists": [
        1000
      ]
    },
    {
      "mobile_number": "+12005551111",
      "first": "Jane",
      "last": "Doe",
      "email":"jane@gmail.com",
      "lists": [
        1000,
        1001
      ]
    }
  ],
  "sync_lists": true,
  "override_optouts": false
  }'

When successful, the above command returns an empty response with a 204 status code.

This endpoint allows you to create & update multiple subscribers in a single request. This endpoint is useful if you're trying to keep your Clearstream subscriber data in sync with an external database.

HTTP Request

POST https://api.getclearstream.com/v1/subscribers/batch

Parameters

Parameter	Type	Required	Default	Description
data	array	true	null	An array of objects containing the subscriber data.
data[*][mobile_number]	string	true	null	The mobile number of the subscriber. E.164 format is preferred, but most standard phone number formats are acceptable.
data[*][first]	string	false	--	The first name of the subscriber.
data[*][last]	string	false	--	The last name of the subscriber.
data[*][email]	string	false	--	The email address of the subscriber.
data[*][lists]	array	false	--	An array of list IDs to add the subscriber to. *See notes on the sync_lists parameter.
sync_lists	boolean	false	false	When set to false, the subscriber will simply be added to the lists in the lists array. This is the default behavior. When set to true, they will be removed from all lists and added to the lists in the lists array. If you pass an empty value for lists, the subscriber will be removed from all lists. Has no effect when lists is not present.
override_optouts	boolean	false	false	Whether to opt-in the subscriber even if they are opted-out. *This option is only available for accounts using a dedicated shortcode.

Keywords

View All Keywords

curl "https://api.getclearstream.com/v1/keywords"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "count": 1,
  "total": 1,
  "current_page": 1,
  "pages": 1,
  "limit": 20,
  "available": 2,
  "data": [
    {
      "id": 1,
      "name": "earlychurch",
      "header": "The Early Church",
      "shortcode": "55498",
      "created_at": "2024-01-01T10:00:09+00:00",
      "archived_at": null,
      "autoresponse": {
        "enabled": false,
        "text": {
          "full": null,
          "header": null,
          "body": null
        },
        "setting": null
      },
      "opt_in": {
        "enabled": true,
        "lists": []
      },
      "workflow": {
        "header": "The Early Church",
        "timezone": "America/New_York",
        "steps": [
          {
            "id": 1,
            "action": {
              "type": "add_to_list",
              "lists": [
                {
                  "id": 1000,
                  "name": "Entire Church"
                }
              ]
            },
            "should_pause": false
          },
          {
            "id": 2,
            "action": {
              "type": "autoresponse",
              "text": "Thanks for joining!"
            },
            "should_pause": false
          }
        ]
      },
      "stats": {
        "opt_ins": {
          "total": 2000
        },
        "uses": {
          "total": 2200
        }
      }
    }
  ]
}

This endpoint retrieves a listing of all active keywords in your account. Results are paginated. You may cycle through the pages by adjusting the page and limit parameters.

HTTP Request

GET https://api.getclearstream.com/v1/keywords

Parameters

Parameter	Type	Required	Default	Description
limit	integer	false	20	Limit the number of results per page.
page	integer	false	1	The page to show.
sort	string	false	null	Accepted values are uses, -uses, name, and -name. By default records are sorted in ascending order. You can use the - prefix to sort descendingly.
filter[search]	string	false	null	Search by name or its aliases.

View a Keyword

curl "https://api.getclearstream.com/v1/keywords/1"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "data": {
    "id": 1,
    "name": "earlychurch",
    "header": "The Early Church",
    "shortcode": "55498",
    "created_at": "2024-01-01T10:00:09+00:00",
    "archived_at": null,
    "autoresponse": {
      "enabled": false,
      "text": {
        "full": null,
        "header": null,
        "body": null
      },
      "setting": null
    },
    "opt_in": {
      "enabled": true,
      "lists": []
    },
    "workflow": {
      "header": "The Early Church",
      "timezone": "America/New_York",
      "steps": [
        {
          "id": 1,
          "action": {
            "type": "add_to_list",
            "lists": [
              {
                "id": 1000,
                "name": "Entire Church"
              }
            ]
          },
          "should_pause": false
        },
        {
          "id": 2,
          "action": {
            "type": "autoresponse",
            "text": "Thanks for joining!"
          },
          "should_pause": false
        }
      ]
    },
    "stats": {
      "opt_ins": {
        "total": 2000
      },
      "uses": {
        "total": 2200
      }
    }
  }
}

This endpoint retrieves details for the specified keyword.

HTTP Request

GET https://api.getclearstream.com/v1/keywords/<id>

Create a Keyword

curl -X POST "https://api.getclearstream.com/v1/keywords"
  -H "X-Api-Key: ABCDEFG123"
  -d "name=earlyyouth"
  -d "enable_opt_in=1"
  -d "opt_in_lists=1000,1001"
  -d "enable_autoresponse=1"
  -d "autoresponse_header=The Early Church Youth"
  -d "autoresponse_body=Thanks for joining!"
  -d "autoresponse_setting=ALWAYS"

The above command returns:

{
  "data": {
    "id": 2,
    "name": "earlyyouth",
    "header": "The Early Church Youth",
    "shortcode": "55498",
    "created_at": "2024-01-01T10:00:09+00:00",
    "archived_at": null,
    "autoresponse": {
      "enabled": false,
      "text": {
        "full": null,
        "header": null,
        "body": null
      },
      "setting": null
    },
    "opt_in": {
      "enabled": true,
      "lists": []
    },
    "workflow": {
      "header": "The Early Church Youth",
      "timezone": "America/New_York",
      "steps": [
        {
          "id": 1,
          "action": {
            "type": "add_to_list",
            "lists": [
              {
                "id": 1000,
                "name": "Entire Church"
              },
              {
                "id": 1001,
                "name": "Staff"
              }
            ]
          },
          "should_pause": false
        },
        {
          "id": 2,
          "action": {
            "type": "autoresponse",
            "text": "Thanks for joining!"
          },
          "should_pause": false
        }
      ]
    },
    "stats": {
      "opt_ins": {
        "total": 0
      },
      "uses": {
        "total": 0
      }
    }
  }
}

This endpoint creates a new keyword.

HTTP Request

POST https://api.getclearstream.com/v1/keywords

Parameters

Parameter	Type	Required	Default	Description
name	string	true	null	The name of your keyword. Must be 4-25 characters, and can contain only letters and numbers (no spaces).
number	string	false	The number to use for this keyword. If a longcode is supplied, must be in E.164 format. If not supplied, the keyword will be created using your account's default number.
enable_opt_in	boolean	false	0	Whether to opt-in subscribers when they text this keyword. Must be a 1 or 0.
opt_in_lists	array, string	false	null	An array of list IDs to add the subscriber to is preferred. Alternatively, a comma-separated string of list IDs is accepted.
enable_autoresponse	boolean	false	0	Whether to send an autoresponse text when a subscriber texts this keyword. Must be a 1 or 0.
autoresponse_header	string	false	null	Header for the autoresponse text. Should be the name of your church or organization. Can contain only GSM 7-bit characters. Required if enable_autoresponse is 1.
autoresponse_body	string	false	null	Body for the autoresponse text. Together, the autoresponse_header and autoresponse_body cannot exceed the text message character limit. Required if enable_autoresponse is 1.
autoresponse_setting	string	false	null	When to send the autoresponse text. Accepted values are ALWAYS, FIRST and NEW. Required if enable_autoresponse is 1.

Delete a Keyword

curl -X DELETE "https://api.getclearstream.com/v1/keywords/2"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "deleted": true,
  "name": "earlyyouth"
}

This endpoint deletes the specified keyword.

HTTP Request

DELETE https://api.getclearstream.com/v1/keywords/<id>

Automated Workflows

View All Automated Workflows

curl "https://api.getclearstream.com/v1/workflows"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "count": 1,
  "total": 1,
  "current_page": 1,
  "pages": 1,
  "limit": 20,
  "data": [
    {
      "id": 1,
      "name": "New Guest Workflow",
      "header": "The Early Church",
      "timezone": "America/New_York"
    }
  ]
}

This endpoint retrieves a listing of all automated workflows in your account. Results are paginated. You may cycle through the pages by adjusting the page and limit parameters.

HTTP Request

GET https://api.getclearstream.com/v1/workflows

Parameters

Parameter	Type	Required	Default	Description
limit	integer	false	20	Limit the number of results per page.
page	integer	false	1	The page to show.

Add Subscriber To an Automated Workflow

curl -X POST "https://api.getclearstream.com/v1/workflows/2000/subscribers"
  -H "X-Api-Key: ABCDEFG123"
  -d "mobile_number=+12005550000"

When successful, the above command returns an empty response with a 204 status code.

This endpoint adds an already existing subscriber to the specified automated workflow.

HTTP Request

POST https://api.getclearstream.com/v1/workflows/<id>/subscribers

Parameters

Parameter	Type	Required	Default	Description
mobile_number	string	true	--	The mobile number of the subscriber to add to the list. Should be in E.164 format.
prevent_repeats	bool	false	true	Exclude subscribers who have previously entered this workflow

Messages

View All Messages

curl "https://api.getclearstream.com/v1/messages"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "count": 2,
  "total": 2,
  "current_page": 1,
  "pages": 1,
  "limit": 20,
  "queued": 0,
  "sending": 0,
  "sent": 2,
  "scheduled": 0,
  "failed": 0,
  "draft": 0,
  "recurring": 0,
  "data": [
    {
      "id": 30010,
      "status": "SENT",
      "type": "SMS",
      "number": "94000",
      "sent_at": "2022-06-12T10:04:06+00:00",
      "completed_at": "2022-06-12T05:04:06+00:00",
      "text": {
        "full": "The Early Church: Welcome to church! Check out what's going on this week:\n\nhttps://video.clr.io/pqwthx",
        "header": "The Early Church",
        "body": "Welcome to church! Check out what's going on this week:"
      },
      "note": null,
      "poll": null,
      "video": {
        "id": 1500,
        "title": "Welcome to Church",
        "url": "https://video.clr.io/pqwthx",
        "thumbnail_url": "https://image.mux.com/qwLD6LNXSQhqJplp74bUPPM33w01J8h4XbBc01WXJGtnE/thumbnail.png?time=0&width=1200&height=675&fit_mode=smartcrop",
        "playback_url": "https://stream.mux.com/qwLD6LNXSQhqJplp74bUPPM33w01J8h4XbBc01WXJGtnE.m3u8",
        "duration": 60.0,
        "orientation": "PORTRAIT",
        "status": "READY",
        "created_at": "2022-03-07T20:10:30+00:00",
        "stats": {
          "total_clicks": 35
        }
      },
      "lists": [
        {
          "id": 1000,
          "name": "Entire Church"
        }
      ],
      "subscribers": [],
      "contacts": [],
      "stats": {
        "recipients": 2000,
        "successful": 1999,
        "failures": 1,
        "throughput": 250,
        "replies": 10,
        "opt_outs": 50,
        "credits_used": 1999
      },
      "user": {
        "id": 700,
        "name": "Robert",
        "email": "robert@theearly.church",
        "image": null
      },
      "social": {
        "twitter": {
          "enabled": false,
          "id": null,
          "url": null
        },
        "facebook": {
          "enabled": false,
          "id": null,
          "url": null
        }
      },
      "media": null
    },
    {
      "id": 30000,
      "status": "SENT",
      "type": "SMS",
      "number": "94000",
      "sent_at": "2022-06-09T21:48:09+00:00",
      "completed_at": "2022-06-09T21:48:10+00:00",
      "text": {
        "full": "The Early Church: Need prayer? Just reply and we will pray!",
        "header": "The Early Church",
        "body": "Need prayer? Just reply and we will pray!"
      },
      "note": null,
      "poll": null,
      "video": null,
      "lists": [
        {
          "id": 1000,
          "name": "Entire Church"
        }
      ],
      "subscribers": [],
      "contacts": [],
      "stats": {
        "recipients": 2000,
        "successful": 2000,
        "failures": 0,
        "throughput": 250,
        "replies": 5,
        "opt_outs": 25,
        "credits_used": 2000
      },
      "user": {
        "id": 700,
        "name": "Robert",
        "email": "robert@theearly.church",
        "image": null
      },
      "social": {
        "twitter": {
          "enabled": false,
          "id": null,
          "url": null
        },
        "facebook": {
          "enabled": false,
          "id": null,
          "url": null
        }
      },
      "media": null
    }
  ]
}

This endpoint retrieves a listing of all messages sent by your account. Results are paginated. You may cycle through the pages by adjusting the page and limit parameters.

HTTP Request

GET https://api.getclearstream.com/v1/messages

Parameters

Parameter	Type	Required	Default	Description
limit	integer	false	20	Limit the number of results per page.
page	integer	false	1	The page to show.
filter[user_id]	integer	false	null	Filter messages by user id.
filter[type]	string	false	null	Filter messages by type. Accepted values are SMS, MMS, and EMAIL.
filter[status]	string	false	null	Filter messages by status. Accepted values are SENT, SENDING, QUEUED, FAILED, SCHEDULED, DRAFT and RECURRING.
filter[search]	string	false	null	Search messages by text.
filter[number]	string	false	null	Search messages by outgoing number.
filter[sent_after]	string	false	null	Search messages sent after a specific date. Date should be in the following format Y-m-d\TH:i:sP.
filter[sent_before]	string	false	null	Search messages sent before a specific date. Date should be in the following format Y-m-d\TH:i:sP.

View a Message

curl "https://api.getclearstream.com/v1/messages/30000"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "data": {
    "id": 30000,
    "status": "SENT",
    "type": "SMS",
    "number": "94000",
    "sent_at": "2022-06-09T21:48:09+00:00",
    "completed_at": "2022-06-09T21:48:10+00:00",
    "text": {
      "full": "The Early Church: Need prayer? Just reply and we will pray!",
      "header": "The Early Church",
      "body": "Need prayer? Just reply and we will pray!"
    },
    "note": {
      "id": 100,
      "title": "Lorem ipsum",
      "url": "https://clrnote.com/uri",
      "word_count": 56,
      "text_preview": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. His singulis copiose responderi solet, sed quae perspicua sunt longa esse non debent. Quicquid porro animo cernimus, id omne oritur a...",
      "user": {
        "id": 700,
        "name": "Robert",
        "email": "robert@theearly.church",
        "image": null
      },
      "created_at": "2022-03-07T20:14:10+00:00"
    },
    "poll": null,
    "video": null,
    "lists": [
      {
        "id": 1000,
        "name": "Entire Church"
      }
    ],
    "subscribers": [],
    "contacts": [],
    "stats": {
      "recipients": 2000,
      "successful": 1998,
      "failures": 2,
      "throughput": 250,
      "replies": 5,
      "opt_outs": 25,
      "credits_used": 1998
    },
    "user": {
      "id": 700,
      "name": "Robert",
      "email": "robert@theearly.church",
      "image": null
    },
    "social": {
      "twitter": {
        "enabled": false,
        "id": null,
        "url": null
      },
      "facebook": {
        "enabled": false,
        "id": null,
        "url": null
      }
    },
    "media": null
  }
}

This endpoint retrieves details for the specified message.

HTTP Request

GET https://api.getclearstream.com/v1/messages/<id>

Send/Schedule A Message

curl -X POST "https://api.getclearstream.com/v1/messages"
  -H "X-Api-Key: ABCDEFG123"
  -d "message_header=The Early Church"
  -d "message_body=See you in the morning at 10AM!"
  -d "lists=1000"

The above command returns:

{
  "data": {
    "id": 30002,
    "status": "QUEUED",
    "type": "SMS",
    "number": "94000",
    "sent_at": "2022-06-13T17:09:48+00:00",
    "completed_at": null,
    "text": {
      "full": "The Early Church: See you in the morning at 10AM!",
      "header": "The Early Church",
      "body": "See you in the morning at 10AM!"
    },
    "note": null,
    "poll": null,
    "video": null,
    "lists": [
      {
        "id": 1000,
        "name": "Entire Church"
      }
    ],
    "subscribers": [],
    "contacts": [],
    "stats": {
      "recipients": 2000,
      "failures": 0,
      "throughput": 0,
      "replies": 0,
      "opt_outs": 0,
      "credits_used": 0
    },
    "user": {
      "id": 700,
      "name": "Robert",
      "email": "robert@theearly.church",
      "image": null
    },
    "social": {
      "twitter": {
        "enabled": false,
        "id": null,
        "url": null
      },
      "facebook": {
        "enabled": false,
        "id": null,
        "url": null
      }
    },
    "media": null
  }
}

This endpoint sends/schedules a new message.

HTTP Request

POST https://api.getclearstream.com/v1/messages

Parameters

Parameter	Type	Required	Default	Description
message_header	string	false*	null	Header for the message. Should be the name of your church or organization. We recommend always including a message header to comply with carrier guidelines. Can contain only GSM 7-bit characters. *Not required if use_default_header is true or sending with a longcode or dedicated shortcode.
message_body	string	true	null	Body for the message. Together, the message_header and message_body cannot exceed the text message character limit.
media_id	string	false	null	An image to include with the message. Get a media_id by uploading an image with the Media Upload endpoint. Your account must have MMS enabled.
media_url	string	false	null	URL of an image to include with the message. Only accepts JPEG or PNG images that are less than 8MB in size. You should provide either media_id or media_url. Your account must have MMS enabled.
video_id	string	false	null	A video to include with the message. A link to the video will be appended to the message body.
note_id	integer	false	null	A note to include with the message. A link to the note will be appended to the message body.
poll_id	integer	false	null	A poll to include with the message. Poll question and options will be appended to the message body. Message body is optional when attaching a poll to a message.
number	string	false	null	The number of the longcode or shortcode to send this message from. If a longcode is supplied, E.164 format is preferred. If no number is supplied, the message will be sent using your account's default number.
lists	string	false	null	An array of list IDs to receive the message is preferred. Alternatively, a comma-separated string of list IDs is accepted. Required, unless you pass the subscribers parameter.
subscribers	array, string	false	null	An array of active subscriber's mobile numbers (in E.164 format) to receive the message. Alternatively, a comma-separated string of mobile numbers (in E.164 format) is accepted. Required if you do not pass the lists parameter. Note that you can pass both the lists and subscribers parameters.
schedule	boolean	false	0	Whether the message should be scheduled to be sent at a future time.
datetime	string	false	null	The date and time to schedule the message for. Should be in the format YYYY-MM-DD HH:MM:SS. Required if schedule is set to 1.
timezone	string	false	null	The timezone for the datetime field. Must be a valid, supported timezone. Required if schedule is set to 1.
use_default_header	boolean	false	false	If true, your account's default header will be used instead of message_header.
send_to_fb	boolean	false	0	Whether to post to the Facebook page tied to your account.
send_to_tw	boolean	false	0	Whether to post to the Twitter account tied to your account.

Delete a Scheduled Message

curl -X DELETE "https://api.getclearstream.com/v1/messages/30000"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "deleted": true,
  "id": 30000
}

This endpoint deletes the specified scheduled message.

HTTP Request

DELETE https://api.getclearstream.com/v1/messages/<id>

Inbox

View All Threads

curl "https://api.getclearstream.com/v1/threads"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "count": 2,
  "total": 2,
  "current_page": 1,
  "pages": 1,
  "limit": 30,
  "unread": 1,
  "data": [
    {
      "id": 80000,
      "unread": true,
      "reply_count": 1,
      "replied_at": "2022-06-10T02:48:31+00:00",
      "subscriber": {
        "mobile_number": "+12005551000",
        "status": "ACTIVE",
        "first": "Jane",
        "last": "Doe",
        "email": null,
        "avatar_url": null
      },
      "related_message": {
        "id": 1000,
        "type": "MMS",
        "sent_at": "2022-06-10T02:00:00+00:00",
        "text": {
          "full": "The Early Church: See you in the morning at 10AM!",
          "header": "The Early Church",
          "body": "See you in the morning at 10AM!"
        },
        "media": {
          "id": 1500,
          "url": "https://clearstream.io/logo.png",
          "type": "image/png",
          "filename": "logo.png"
        }
      },
      "recent_replies": [
        {
          "id": 120000,
          "text": "Thanks!",
          "status": "RECEIVED",
          "incoming": true,
          "user": null,
          "sent_at": "2022-06-10T02:48:31+00:00"
        }
      ],
      "created_at": "2022-06-10T02:48:31+00:00",
      "updated_at": "2022-06-10T02:48:31+00:00",
      "archived_at": null
    },
    {
      "id": 77000,
      "unread": false,
      "reply_count": 3,
      "replied_at": "2022-06-09T21:43:43+00:00",
      "subscriber": {
        "mobile_number": "+12005551001",
        "status": "ACTIVE",
        "first": "John",
        "last": "Doe",
        "email": null,
        "avatar_url": null
      },
      "related_message": null,
      "recent_replies": [
        {
          "id": 118000,
          "text": "Happy to hear!",
          "status": "SENT",
          "incoming": false,
          "user": {
            "id": 700,
            "name": "Robert",
            "email": "robert@theearly.church",
            "image": null
          },
          "sent_at": "2022-05-18T05:23:15+00:00"
        },
        {
          "id": 117999,
          "text": ":)",
          "status": "SENT",
          "incoming": false,
          "user": {
            "id": 700,
            "name": "Robert",
            "email": "robert@theearly.church",
            "image": null
          },
          "sent_at": "2022-05-18T05:23:10+00:00"
        },
        {
          "id": 117980,
          "text": "Thanks! I'll be there!",
          "status": "RECEIVED",
          "incoming": true,
          "user": null,
          "sent_at": "2022-05-18T05:21:00+00:00"
        }
      ],
      "created_at": "2022-05-18T05:21:00+00:00",
      "updated_at": "2022-05-18T05:23:15+00:00",
      "archived_at": null
    }
  ]
}

This endpoint retrieves a listing of all threads in your account inbox. Results are paginated. You may cycle through the pages by adjusting the page and limit parameters.

HTTP Request

GET https://api.getclearstream.com/v1/threads

Parameters

Parameter	Type	Required	Default	Description
limit	integer	false	30	Limit the number of results per page.
page	integer	false	1	The page to show.
filter[text]	string	false	null	Search for threads containing text.
filter[full_name]	string	false	null	Search for threads by subscriber's name. (Partial match is acceptable.)
filter[mobile_number]	string	false	null	Search for threads by subscriber's mobile number. (Partial match is acceptable.)
filter[archived]	string	false	not_archived	Filter threads based on their archived status. Accepted options are archived, not_archived, and any.
filter[message_id]	integer	false	null	Search for threads associated with a message.

View a Thread

curl "https://api.getclearstream.com/v1/threads/80000"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "data": {
    "id": 80000,
    "unread": true,
    "reply_count": 1,
    "replied_at": "2022-06-10T02:48:31+00:00",
    "subscriber": {
      "mobile_number": "+12005551000",
      "status": "ACTIVE",
      "first": "Jane",
      "last": "Doe",
      "email": null,
      "avatar_url": null
    },
    "related_message": {
      "id": 1000,
      "type": "MMS",
      "sent_at": "2022-06-10T02:00:00+00:00",
      "text": {
        "full": "The Early Church: Can't wait to see you tomorrow at 10AM!",
        "header": "The Early Church",
        "body": "Can't wait to see you tomorrow at 10AM!"
      },
      "media": {
        "id": 1000,
        "url": "https://clearstream.io/logo.png",
        "type": "image/png",
        "filename": "logo.png"
      }
    },
    "recent_replies": [
      {
        "id": 120000,
        "text": "Thanks!",
        "status": "RECEIVED",
        "incoming": true,
        "user": null,
        "sent_at": "2022-06-10T02:48:31+00:00"
      }
    ],
    "created_at": "2022-06-10T02:48:31+00:00",
    "updated_at": "2022-06-10T02:48:31+00:00",
    "archived_at": null
  }
}

This endpoint retrieves details for the specified thread.

HTTP Request

GET https://api.getclearstream.com/v1/threads/<id>

View a Thread's Replies

curl "https://api.getclearstream.com/v1/threads/80000/replies"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "count": 1,
  "total": 1,
  "current_page": 1,
  "pages": 1,
  "limit": 30,
  "data": [
    {
      "id": 120000,
      "text": "Thanks!",
      "status": "RECEIVED",
      "incoming": true,
      "user": null,
      "sent_at": "2022-06-10T02:48:31+00:00"
    }
  ]
}

This endpoint retrieves a listing of the replies for the specified thread. Results are paginated. You may cycle through the pages by adjusting the page and limit parameters.

HTTP Request

GET https://api.getclearstream.com/v1/threads/<id>/replies

Parameters

Parameter	Type	Required	Default	Description
limit	integer	false	30	Limit the number of results per page.
page	integer	false	1	The page to show.

Send a Reply

curl -X POST "https://api.getclearstream.com/v1/threads/80000/replies"
  -H "X-Api-Key: ABCDEFG123"
  -d "text=Awesome!"

The above command returns:

{
  "data": {
    "id": 120001,
    "text": "Awesome!",
    "status": "QUEUED",
    "incoming": false,
    "user": {
      "id": 700,
      "name": "Robert",
      "email": "robert@theearly.church",
      "image": null
    },
    "sent_at": "2022-06-10T02:50:00+00:00"
  }
}

This endpoint sends a new reply to the subscriber associated with the specified thread.

HTTP Request

POST https://api.getclearstream.com/v1/threads/<id>/replies

Parameters

Parameter	Type	Required	Default	Description
text	string	true	null	Text for the reply.

Create a Thread

curl -X POST "https://api.getclearstream.com/v1/threads"
  -H "X-Api-Key: ABCDEFG123"
  -d "mobile_number=+12001001234"
  -d "reply_header=Early Church"
  -d "reply_body=Hey thanks for visiting Sunday!"

The above command returns:

{
  "data": {
    "id": 80001,
    "unread": false,
    "reply_count": 1,
    "replied_at": "2022-06-10T02:48:31+00:00",
    "subscriber": {
      "mobile_number": "+12001001234",
      "status": "INACTIVE",
      "first": null,
      "last": null,
      "email": null,
      "avatar_url": null
    },
    "related_message": null,
    "recent_replies": [
      {
        "id": 120001,
        "text": "Early Church: Hey thanks for visiting Sunday!",
        "status": "QUEUED",
        "incoming": false,
        "user": {
          "id": 700,
          "name": "Robert",
          "email": "robert@theearly.church",
          "image": null
        },
        "sent_at": "2022-06-10T02:48:31+00:00"
      }
    ],
    "created_at": "2022-06-10T02:48:31+00:00",
    "updated_at": "2022-06-10T02:48:31+00:00",
    "archived_at": null
  }
}

This endpoint creates a new thread and reply. This is a good way to start a texting conversation with a subscriber or send a single text to a number.

HTTP Request

POST https://api.getclearstream.com/v1/threads

Parameters

Parameter	Type	Required	Description
mobile_number	string	true	The mobile number to start a thread with. E.164 format is preferred, but most standard phone number formats are acceptable.
reply_header	string	true	Header for the reply. Should be the name of your church or organization. Can contain only GSM 7-bit characters.
reply_body	string	true	Body text for the reply. Together, the reply_header and reply_body cannot exceed the text message character limit.
number	string	false	The number to use for this thread. If a longcode is supplied, must be in E.164 format. If not supplied, the thread will be started using your account's default number.

Archive a Thread

curl -X DELETE "https://api.getclearstream.com/v1/threads/80000"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "data": {
    "deleted": true,
    "id": 80000
  }
}

This endpoint archives the specified thread.

HTTP Request

DELETE https://api.getclearstream.com/v1/threads/<id>

Texts

Send a Text

Sending a text to a single number:

curl -X POST "https://api.getclearstream.com/v1/texts"
  -H "X-Api-Key: ABCDEFG123"
  -d "to=+12001001234"
  -d "from=97000"
  -d "text_header=Early Church"
  -d "text_body=Hey thanks for visiting Sunday!"

The above command returns:

{
  "data": {
    "id": 1200495019243,
    "status": "QUEUED",
    "queued_at": "2022-01-10T02:48:31+00:00",
    "text": "Early Church: Hey thanks for visiting Sunday!",
    "to": "+12001001234",
    "from": "97000",
    "media": []
  }
}

Sending a text to multiple numbers:

curl -X POST "https://api.getclearstream.com/v1/texts"
  -H "X-Api-Key: ABCDEFG123"
  -d '{
  "to": [
     "+12001001234",
     "+12001001235",
     "+12001001236"
  ],
  "from":"97000",
  "text_header":"Early Church",
  "text_body":"Hey thanks for visiting Sunday!"
  }'

The above command returns:

{
  "data": {
    "id": null,
    "status": "QUEUED",
    "queued_at": "2022-01-10T02:48:31+00:00",
    "text": "Early Church: Hey thanks for visiting Sunday!",
    "to": [
      "+12001001234",
      "+12001001235",
      "+12001001236"
    ],
    "skipped": [],
    "from": "97000",
    "media": []
  }
}

This endpoint is a simple way to send a text message to one or more numbers. This is useful for one-off texts that don't need to be stored in your inbox.

HTTP Request

POST https://api.getclearstream.com/v1/texts

Parameters

Parameter	Type	Required	Description
to	string|array	true	One or more mobile numbers to send the text to. E.164 format is preferred, but most standard phone number formats are acceptable.
from	string	false	The number of the longcode or shortcode to send this text from. If a longcode is supplied, E.164 format is preferred. By default, the text will be sent using your account's shortcode. If your account doesn't have shortcode access, your account's longcode will be used.
text_header	string	true*	Header for the text. Should be the name of your church or organization. Can contain only GSM 7-bit characters. *This field is optional if sending from a longcode or dedicated shortcode, or if use_default_header is true.
text_body	string	true	Body of the text. Together, the text_header and text_body cannot exceed the text message character limit.
media_url	string	false	A URL to an image to include with the text. Only JPG and PNG formats are accepted, and the image must be less than 5MB. Your account also must have MMS enabled.
use_default_header	boolean	false	If true, your account's default header will be used instead of text_header.
override_optouts	boolean	false	Whether to send the text even if the subscriber is opted-out. *This option is only available for accounts using a dedicated shortcode.

Numbers

View all numbers

curl "https://api.getclearstream.com/v1/numbers"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "data": [
    {
      "id": 3,
      "type": "shortcode",
      "number": "97000",
      "default": true,
      "can_send_texts": true,
      "is_header_required": true
    },
    {
      "id": 1653,
      "type": "longcode",
      "number": "+14120654816",
      "default": false,
      "can_send_texts": true,
      "is_header_required": false
    }
  ]
}

This endpoint retrieves a listing of all numbers (shortcodes and longcodes) your account can send from.

HTTP Request

GET https://api.getclearstream.com/v1/numbers

Media

Upload Media

curl -X POST "https://api.getclearstream.com/v1/media/upload"
  -H "X-Api-Key: ABCDEFG123"
  -F "media=@/path/to/image.jpg"

The above command returns:

{
  "data": {
    "id": 1000,
    "url": "https://clearstream.io/logo.jpg",
    "type": "image/jpeg",
    "filename": "image.jpg"
  }
}

This endpoint uploads an image. The returned id can be used as a media_id parameter on the send message endpoint.

HTTP Request

POST https://api.getclearstream.com/v1/media/upload

Parameters

Parameter	Type	Required	Default	Description
media	file	true	null	Only accepts JPEG or PNG images that are less than 8MB in size.

Stats

These endpoint expose statistical data about your account which you can use for performance analysis. Most endpoints require you to specify a date range.

Most endpoints allow you to optionally include chart data, which is useful for constructing charts that show performance over time. Chart data, depending on the endpoint, can be delimited by minute, hour, day, or month, which means the statistical data is divided into smaller time periods.

Additionally, most endpoints allow you to pass a unique_numbers parameter, which means a unique mobile number will be counted at most once for the specified metric. This parameter is useful if you want to know how many unique mobile numbers used a keyword or replied to a message, for example. For chart data, the unique_numbers parameter means a unique mobile number will be counted at most once per delimited time period (minute, hour, day, or month).

General Account Stats

curl "https://api.getclearstream.com/v1/stats/account"
  -H "X-Api-Key: ABCDEFG123"

The above command returns:

{
  "data": {
    "contacts_count": 250,
    "sms_opted_in_contacts_count": 225,
    "email_opted_in_contacts_count": 170,
    "lists_count": 7,
    "tags_count": 5,
    "keywords_count": 9,
    "last_week_new_contacts_count": 12
  }
}

This endpoint retrieves general statistics about your account. The data returned includes the total number of contacts, the number of contacts opted in to SMS and email, the number of lists, the number of tags, the number of keywords, and the number of new contacts added in the last week.

HTTP Request

GET https://api.getclearstream.com/v1/stats/account

Total Subscribers

curl "https://api.getclearstream.com/v1/stats/subscribers"
  -H "X-Api-Key: ABCDEFG123"
  -d "start: 2022-01-01"
  -d "end: 2022-01-07"

The above command returns:

{
  "meta": {
    "start": "2022-01-01T00:00:00+00:00",
    "end": "2022-01-07T23:59:59+00:00",
    "timezone": "UTC",
    "delimiter": "day"
  },
  "charts": {
    "subscribers": [
      [
        "2022-01-01 00:00:00",
        250
      ],
      [
        "2022-01-02 00:00:00",
        255
      ],
      [
        "2022-01-03 00:00:00",
        267
      ],
      [
        "2022-01-04 00:00:00",
        270
      ],
      [
        "2022-01-05 00:00:00",
        285
      ],
      [
        "2022-01-06 00:00:00",
        290
      ],
      [
        "2022-01-07 00:00:00",
        291
      ]
    ]
  }
}

This endpoint retrieves daily or monthly statistics for the total number of active subscribers in your account during the specified date range.

HTTP Request

GET https://api.getclearstream.com/v1/stats/subscribers

Parameters

Parameter	Type	Required	Default	Description
filter[start]	string	true	null	The start date in YYYY-MM-DD format.
filter[end]	string	true	null	The end date in YYYY-MM-DD format.
timezone	string	false	UTC	If specified, statistical data respects the given timezone. Must be a valid, supported timezone.
delimiter	string	false	day	The delimiter for the chart data. Can be either be day or month.

Opt-ins & Opt-outs

curl "https://api.getclearstream.com/v1/stats/opts"
  -H "X-Api-Key: ABCDEFG123"
  -d "start: 2022-01-01"
  -d "end: 2022-01-03"
  -d "include_charts: 1"

The above command returns:

{
  "meta": {
    "start": "2022-01-01T00:00:00+00:00",
    "end": "2022-01-03T23:59:59+00:00",
    "timezone": "UTC",
    "delimiter": "day"
  },
  "totals": {
    "opt_ins": {
      "count": 15
    },
    "opt_outs": {
      "count": 2
    }
  },
  "charts": {
    "opt_ins": [
      [
        "2022-01-01 00:00:00",
        5
      ],
      [
        "2022-01-02 00:00:00",
        7
      ],
      [
        "2022-01-03 00:00:00",
        3
      ]
    ],
    "opt_outs": [
      [
        "2022-01-01 00:00:00",
        1
      ],
      [
        "2022-01-02 00:00:00",
        1
      ],
      [
        "2022-01-03 00:00:00",
        0
      ]
    ]
  }
}

This endpoint retrieves statistics for the total number of opt-ins and opt-outs for your account during the specified date range.

HTTP Request

GET https://api.getclearstream.com/v1/stats/opts

Parameters

Parameter	Type	Required	Default	Description
filter[start]	string	true	null	The start date in YYYY-MM-DD format.
filter[end]	string	true	null	The end date in YYYY-MM-DD format.
timezone	string	false	UTC	If specified, statistical data respects the given timezone. Must be a valid, supported timezone.
filter[include_charts]	boolean	false	0	Whether to include the charts property with daily/monthly statistics.
filter[unique_numbers]	boolean	false	0	Whether to count a unique mobile number at most once when calculating stats.
delimiter	string	false	day	The delimiter for the chart data. Can be either be day or month.

Incoming & Outgoing Texts

curl "https://api.getclearstream.com/v1/stats/texts"
  -H "X-Api-Key: ABCDEFG123"
  -d "start: 2022-01-01"
  -d "end: 2022-01-03"
  -d "include_charts: 1"

The above command returns:

{
  "meta": {
    "start": "2022-01-01T00:00:00+00:00",
    "end": "2022-01-03T23:59:59+00:00",
    "timezone": "UTC",
    "delimiter": "day"
  },
  "totals": {
    "incoming": {
      "count": 15
    },
    "outgoing": {
      "count": 2
    }
  },
  "charts": {
    "incoming": [
      [
        "2022-01-01 00:00:00",
        5
      ],
      [
        "2022-01-02 00:00:00",
        7
      ],
      [
        "2022-01-03 00:00:00",
        3
      ]
    ],
    "outgoing": [
      [
        "2022-01-01 00:00:00",
        1
      ],
      [
        "2022-01-02 00:00:00",
        1
      ],
      [
        "2022-01-03 00:00:00",
        0
      ]
    ]
  }
}

This endpoint retrieves statistics for the total number of incoming & outgoing texts for your account during the specified date range. Every kind of text that is associated with your account is counted, including messages, replies, workflow texts, keyword uses, etc.

HTTP Request

GET https://api.getclearstream.com/v1/stats/texts

Parameters

Parameter	Type	Required	Default	Description
filter[start]	string	true	null	The start date in YYYY-MM-DD format.
filter[end]	string	true	null	The end date in YYYY-MM-DD format.
timezone	string	false	UTC	If specified, statistical data respects the given timezone. Must be a valid, supported timezone.
filter[include_charts]	boolean	false	0	Whether to include the charts property with daily/monthly statistics.
filter[unique_numbers]	boolean	false	0	Whether to count a unique mobile number at most once when calculating stats.
delimiter	string	false	day	The delimiter for the chart data. Can be either be day or month.

Keyword Uses (All)

curl "https://api.getclearstream.com/v1/stats/keywords"
  -H "X-Api-Key: ABCDEFG123"
  -d "start: 2022-01-01"
  -d "end: 2022-01-03"
  -d "include_charts: 1"

The above command returns:

{
  "meta": {
    "start": "2022-01-01T00:00:00+00:00",
    "end": "2022-01-03T23:59:59+00:00",
    "timezone": "UTC",
    "delimiter": "day"
  },
  "totals": {
    "uses": {
      "count": 105
    }
  },
  "charts": {
    "uses": [
      [
        "2022-01-01 00:00:00",
        43
      ],
      [
        "2022-01-02 00:00:00",
        15
      ],
      [
        "2022-01-03 00:00:00",
        47
      ]
    ]
  }
}

This endpoint retrieves statistics for the total number of uses of all the keywords in your account during the specified date range.

HTTP Request

GET https://api.getclearstream.com/v1/stats/keywords

Parameters

Parameter	Type	Required	Default	Description
filter[start]	string	true	null	The start date in YYYY-MM-DD format.
filter[end]	string	true	null	The end date in YYYY-MM-DD format.
timezone	string	false	UTC	If specified, statistical data respects the given timezone. Must be a valid, supported timezone.
filter[include_charts]	boolean	false	0	Whether to include the charts property with daily/monthly statistics.
filter[unique_numbers]	boolean	false	0	Whether to count a unique mobile number at most once when calculating stats.
delimiter	string	false	day	The delimiter for the chart data. Can be either be day or month.

Keyword Uses (Single)

curl "https://api.getclearstream.com/v1/stats/keywords/1"
  -H "X-Api-Key: ABCDEFG123"
  -d "start: 2022-01-01"
  -d "end: 2022-01-03"
  -d "include_charts: 1"

The above command returns:

{
  "meta": {
    "start": "2022-01-01T00:00:00+00:00",
    "end": "2022-01-03T23:59:59+00:00",
    "timezone": "UTC",
    "delimiter": "day"
  },
  "totals": {
    "uses": {
      "count": 25
    }
  },
  "charts": {
    "uses": [
      [
        "2022-01-01 00:00:00",
        17
      ],
      [
        "2022-01-02 00:00:00",
        3
      ],
      [
        "2022-01-03 00:00:00",
        5
      ]
    ]
  }
}

This endpoint retrieves statistics for the total number of uses of a single keyword in your account during the specified date range.

HTTP Request

GET https://api.getclearstream.com/v1/stats/keywords/<id>

Parameters

Parameter	Type	Required	Default	Description
filter[start]	string	true	null	The start date in YYYY-MM-DD format.
filter[end]	string	true	null	The end date in YYYY-MM-DD format.
timezone	string	false	UTC	If specified, statistical data respects the given timezone. Must be a valid, supported timezone.
filter[include_charts]	boolean	false	0	Whether to include the charts property with daily/monthly statistics.
filter[unique_numbers]	boolean	false	0	Whether to count a unique mobile number at most once when calculating stats.
delimiter	string	false	day	The delimiter for the chart data. Can be either be day or month.

Message Replies

curl "https://api.getclearstream.com/v1/stats/messages/1/replies"
  -H "X-Api-Key: ABCDEFG123"
  -d "minutes: 5"
  -d "include_charts: 1"

The above command returns:

{
  "meta": {
    "start": "2022-01-01T10:30:15+00:00",
    "end": "2022-01-01T10:35:15+00:00",
    "timezone": "UTC",
    "delimiter": "minute"
  },
  "totals": {
    "replies": {
      "count": 18
    }
  },
  "charts": {
    "uses": [
      [
        "2022-01-01 10:30:15",
        9
      ],
      [
        "2022-01-01 10:31:15",
        3
      ],
      [
        "2022-01-01 10:32:15",
        5
      ],
      [
        "2022-01-01 10:33:15",
        1
      ],
      [
        "2022-01-01 10:34:15",
        0
      ]
    ]
  }
}

This endpoint retrieves statistics for the total number of replies to a single message in your account for a range of time after the message was sent.

HTTP Request

GET https://api.getclearstream.com/v1/stats/messages/<id>/replies

Parameters

Parameter	Type	Required	Default	Description
minutes	integer	true*	null	Set the range based on the number of minutes after the message was sent. *Required unless you pass either hours or days.
hours	integer	false	null	Set the range based on the number of hours after the message was sent.
days	integer	false	null	Set the range based on the number of days after the message was sent.
timezone	string	false	UTC	If specified, statistical data respects the given timezone. Must be a valid, supported timezone.
filter[include_charts]	boolean	false	0	Whether to include the charts property with statistics.
filter[unique_numbers]	boolean	false	0	Whether to count a unique mobile number at most once when calculating stats.

Webhooks

Webhooks are simply notifications sent out by Clearstream for certain events that happen in your account. For example, you can setup a webhook to notify you whenever someone uses one of your keywords, or responds to a message you sent out.

Webhooks are useful when you wish to be notified when something happens, rather than having to poll the API.

You can create a webhook from inside your account. When doing so, you will specify the URL you wish to receive the data, as well as the events that will trigger the webhook.

When triggered, webhooks will perform an HTTP POST containing JSON data to the URL endpoint you specified.

Your endpoint should respond with a HTTP status code of 2xx to indicate that the data was properly received. Certain events support returning data that will trigger further actions, such as sending a text message back to respond to an incoming text. In those cases, your request body should include appropriately formatted JSON specific for that event.

Below are the events that are currently available to trigger a webhook. If you need another type of event, please contact support.

Authenticating

Webhook requests include a header with an account-specific authentication key. This provides a simple way to verify that the webhook was sent by Clearstream.

X-Clearstream-Webhook-Key: YOUR-WEBHOOK-AUTHENTICATION-KEY

You can configure a webhook authentication key inside your account.

Retry Policy

By default, each webhook will only be attempted once. However, you can configure your webhooks to retry on failures by enabling the "Retry failed webhooks" option. This option is available when creating a webhook.

With "Retry failed webhooks" enabled, a webhook receiving a 4xx status code (except 406), a 5xx status code, or a network error will automatically attempt to resend the request. It will make up to five retry attempts at the following intervals: 1. First retry: 15 seconds later 2. Second retry: 60 seconds later 3. Third retry: 5 minutes later 4. Fourth and fifth retries: 15 minutes later

Keyword Used

This event sends the following data:

{
  "created_at": "2022-06-12T10:00:00+00:00",
  "event": "keyword.used",
  "production": true,
  "data": {
    "keyword": {
      "name": "earlychurch",
      "shortcode": "55498"
    },
    "thread": {
      "id": 152390
    },
    "reply": {
      "id": 935094,
      "text": "earlychurch is awesome"
    },
    "subscriber": {
      "mobile_number": "+12005551000",
      "status": "ACTIVE",
      "first": "Jane",
      "last": "Doe",
      "email": null
    }
  }
}

Whenever someone texts one of your keywords, this event is triggered. Details of the matching keyword and the subscriber that used the keyword is contained in the JSON payload. Additionally, if the incoming text contained more than just the keyword, details for the created reply (and thread) are included.

To send a text message response, simply include the following JSON in the body of your response:

{
  "response": {
    "header": "The Early Church",
    "body": "Thanks for texting! Here's your custom URL: https://bit.ly/1PACYez",
    "override_optouts": false,
    "use_default_header": false
  }
}

Response

If you wish to respond to the subscriber and send a text message back to them immediately, you may optionally return JSON containing that data.

Parameter	Type	Required	Description
response[header]	string	true	Header for the response text. Should be the name of your church or organization. Can contain only GSM 7-bit characters.
response[body]	string	true	Body for the response text. Together, the header and body cannot exceed the text message character limit.
response[override_optouts]	boolean	false	Whether to send the text even if the subscriber is opted-out. *This option is only available for accounts using a dedicated shortcode.
response[use_default_header]	boolean	false	Whether to use your account's default header instead of what is passed in header.

Message Report

This event sends the following data:

{
  "created_at": "2022-01-01T10:02:00+00:00",
  "event": "message.report",
  "production": true,
  "data": {
    "message": {
      "id": 1249380,
      "status": "SENT",
      "type": "MMS",
      "sent_at": "2022-01-01T09:30:00+00:00",
      "completed_at": "2022-01-01T09:32:00+00:00",
      "text": {
        "full": "The Early Church: We have a really great weekend coming up! Stay tuned!",
        "header": "The Early Church",
        "body": "We have a really great weekend coming up! Stay tuned!"
      },
      "email": null,
      "lists": [
        {
          "id": 193029,
          "name": "Master List"
        }
      ],
      "subscribers": [],
      "stats": {
        "recipients": 5300,
        "successful": 5285,
        "failures": 15,
        "replies": 22,
        "opt_outs": 19
      },
      "media": [
        {
          "url": "https://clearstream.io/logo.png",
          "mime_type": "image/png"
        }
      ]
    }
  }
}

Whenever a message is sent (or if it fails to send for some reason), this event is triggered. Details of the message, including stats about deliverability, replies, and opt-outs, are included in the JSON payload.

Incoming Text

This event sends the following data:

{
  "created_at": "2022-01-01T10:02:00+00:00",
  "event": "text.received",
  "production": true,
  "data": {
    "id": 128401298392,
    "status": "RECEIVED",
    "sent_at": "2022-01-01T10:02:00+00:00",
    "text": "Thanks so much!",
    "to": "97000",
    "from": "+12005551234",
    "subscriber": {
      "mobile_number": "+12005551234",
      "status": "ACTIVE",
      "first": "John",
      "last": "Doe",
      "email": null
    },
    "account": {
      "id": 1000
    },
    "thread": {
      "id": 325039
    },
    "media": [
      {
        "url": "https://clearstream.io/logo.png",
        "mime_type": "image/png"
      }
    ]
  }
}

Whenever an incoming text of any kind is received, this event is triggered.

To send a text message response, simply include the following JSON in the body of your response:

{
  "response": {
    "header": "The Early Church",
    "body": "Thanks for texting! Here's your custom URL: https://bit.ly/1PACYez",
    "override_optouts": false,
    "use_default_header": false
  }
}

Response

If you wish to respond to the subscriber and send a text message back to them immediately, you may optionally return JSON containing that data.

Parameter	Type	Required	Description
response[header]	string	true	Header for the response text. Should be the name of your church or organization. Can contain only GSM 7-bit characters.
response[body]	string	true	Body for the response text. Together, the header and body cannot exceed the text message character limit.
response[override_optouts]	boolean	false	Whether to send the text even if the subscriber is opted-out. *This option is only available for accounts using a dedicated shortcode.
response[use_default_header]	boolean	false	Whether to use your account's default header instead of what is passed in header.

Text Failed to Send

This event sends the following data:

{
  "created_at": "2022-01-01T10:02:00+00:00",
  "event": "text.failed",
  "production": true,
  "data": {
    "id": 1284018929,
    "status": "FAILED",
    "sent_at": "2022-01-01T10:02:00+00:00",
    "text": "Hey we have a great service coming up tomorrow!",
    "to": "+12005551234",
    "from": "97000",
    "account": {
      "id": 1000
    },
    "media": [
      {
        "url": "https://clearstream.io/logo.png",
        "mime_type": "image/png"
      }
    ]
  }
}

Whenever an outgoing text fails to send, this event is triggered. Details of the text including a unique ID and when delivery was attempted are included in the JSON payload.