NAV Navbar
curl
  • Introduction
  • Account
  • Users
  • Lists
  • Subscribers
  • Keywords
  • Messages
  • Inbox
  • Texts
  • Stats
  • Webhooks
  • 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, 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.

    Limited character set

    Text messages are limited to the GSM 7-bit character set. If you try to send a text message using characters that aren't in this set, you will receive a 422 response from the API.

    160 character limit

    Text messages by design are limited to 160 characters. However, we are able to send outgoing texts up to 320 characters in length. In these cases, we split your text into two parts and the carriers concatenate it. The end result is your subscriber receives a single, long text message.

    Special characters & double counting

    There are 8 characters in the GSM 7-bit character set that are part of an extension and require more than 7-bits to encode, and therefore take up two characters from the 160 character limit. These special characters are listed below. If your text contains any of these characters, you must count them twice when ensuring you are under the character 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 will only be made in exceptional circumstances, such as security issues or bug fixes.

    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:

    2020-05-13

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

    2020-04-30

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

    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:

    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:

    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:

    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": "2016-07-01",
            "plan": {
                "name": "$29",
                "cost": 29,
                "credits": 500,
                "keywords": 2
            },
            "stats": {
                "timezone": "UTC",
                "opt_ins": {
                    "past_7_days": {
                        "total": 115,
                        "chart": {
                            "day": {
                                "2016-06-01": 15,
                                "2016-06-02": 12,
                                "2016-06-03": 10,
                                "2016-06-04": 20,
                                "2016-06-05": 23,
                                "2016-06-06": 21,
                                "2016-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": "2016-07-01",
            "plan": {
                "name": "$29",
                "cost": 29,
                "credits": 500,
                "keywords": 2
            },
            "stats": {
                "opt_ins": {
                    "past_7_days": {
                        "total": 115,
                        "chart": {
                            "timezone": "UTC",
                            "day": {
                                "2016-06-01": 15,
                                "2016-06-02": 12,
                                "2016-06-03": 10,
                                "2016-06-04": 20,
                                "2016-06-05": 23,
                                "2016-06-06": 21,
                                "2016-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",
                "email_notifications": {
                    "incoming_reply": true,
                    "opt_in": true
                },
                "timezone": "America/New_York",
                "owner": true
            },
            {
                "email": "sue@theearly.church",
                "name": "Sue",
                "email_notifications": {
                    "incoming_reply": false,
                    "opt_in": false
                },
                "timezone": "America/New_York",
                "owner": false
            }
        ]
    }
    

    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",
            "email_notifications": {
                "incoming_reply": false,
                "opt_in": false
            },
            "timezone": "America/New_York",
            "owner": false
        }
    }
    

    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,
                "pco_list_id": null
            },
            {
                "id": 1001,
                "name": "Staff",
                "subscriber_count": 30,
                "pco_list_id": null
            }
        ]
    }
    

    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.

    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,
            "pco_list_id": null
        }
    }
    

    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
        }
    }
    

    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
        }
    }
    

    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"
      -d "force_delete=1"
    

    The above command returns:

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

    This endpoint deletes the specified list.

    HTTP Request

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

    Parameters

    Parameter Type Required Default Description
    force_delete bool false 0 If the list contains subscribers, this parameter must be passed and set to 1. Any subscribers who are only present in this list will be deleted.

    View Subscribers For a List

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

    The above command returns:

    {
        "count": 20,
        "total": 2000,
        "current_page": 1,
        "pages": 100,
        "limit": 20,
        "data": [
            {
                "mobile_number": "+12005550000",
                "status": "ACTIVE",
                "first": "Jane",
                "last": "Doe",
                "full_name": "Jane Doe",
                "email": null,
                "created_at": "2019-01-01T12:00:00+00:00",
                "updated_at": "2019-01-01T12:00:00+00:00",
                "joined_at": "2019-01-01T12:00:00+00:00",
                "opted_in_at": "2019-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,
                "created_at": "2019-01-01T12:00:00+00:00",
                "updated_at": "2019-01-01T12:00:00+00:00",
                "joined_at": "2019-01-01T12:00:00+00:00",
                "opted_in_at": "2019-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.
    full_name string false null Search by full name. (Partial match is acceptable.)
    first string false null Search by first name. (Partial match is acceptable.)
    last string false null Search by last name. (Partial match is acceptable.)
    mobile_number string false null Search by mobile number. (Partial match is acceptable.)
    operator string false 'or' If passing multiple search parameters, the operator to use. May be set to or or and.

    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,
            "created_at": "2019-01-01T12:00:00+00:00",
            "updated_at": "2019-01-01T12:00:00+00:00",
            "joined_at": "2019-01-01T12:00:00+00:00",
            "opted_in_at": "2019-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>

    Subscribers

    View All Subscribers

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

    The above command returns:

    {
        "count": 20,
        "total": 2030,
        "current_page": 1,
        "pages": 202,
        "limit": 20,
        "data": [
            {
                "mobile_number": "+12005551000",
                "status": "ACTIVE",
                "first": "Jane",
                "last": "Doe",
                "full_name": "Jane Doe",
                "email": null,
                "lists": [
                    {
                        "id": 1000,
                        "name": "Entire Church",
                        "joined_at": "2019-01-01T12:00:00+00:00"
                    }
                ],
                "created_at": "2019-01-01T12:00:00+00:00",
                "updated_at": "2019-01-01T12:00:00+00:00",
                "opted_in_at": "2019-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,
                "lists": [
                    {
                        "id": 1000,
                        "name": "Entire Church",
                        "joined_at": "2019-01-01T12:00:00+00:00"
                    }
                ],
              "created_at": "2019-01-01T12:00:00+00:00",
              "updated_at": "2019-01-01T12:00:00+00:00",
              "opted_in_at": "2019-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.
    status string false active Filter subscribers based on their status. Accepted options are active, inactive, optout, and any.
    full_name string false null Search by full name. (Partial match is acceptable.)
    first string false null Search by first name. (Partial match is acceptable.)
    last string false null Search by last name. (Partial match is acceptable.)
    mobile_number string false null Search by mobile number. (Partial match is acceptable.)
    operator string false 'or' If passing multiple search parameters, the operator to use. May be set to or or and.

    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,
            "lists": [
                {
                    "id": 1000,
                    "name": "Entire Church",
                    "joined_at": "2019-01-01T12:00:00+00:00"
                }
            ],
            "created_at": "2019-01-01T12:00:00+00:00",
            "updated_at": "2019-01-01T12:00:00+00:00",
            "opted_in_at": "2019-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"
      -d "mobile_number=+12005551002"
      -d "lists=1000,1001"
    

    The above command returns:

    {
        "data": {
            "mobile_number": "+12005551002",
            "status": "INACTIVE",
            "first": null,
            "last": null,
            "full_name": null,
            "email": null,
            "lists": [
                {
                    "id": 1000,
                    "name": "Entire Church",
                    "joined_at": "2019-01-01T12:00:00+00:00"
                },
                {
                    "id": 1001,
                    "name": "Staff",
                    "joined_at": "2019-01-01T12:00:00+00:00"
                }
            ],
            "created_at": "2019-01-01T12:00:00+00:00",
            "updated_at": "2019-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 string true null Comma-separated string of list IDs to add the subscriber to.
    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. 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. Can contain only GSM 7-bit characters. Together, the autoresponse_header and autoresponse_body cannot exceed 318 characters. Required if autoresponse_header is supplied.
    double_optin boolean false true Whether to send a confirmation text before opting-in the subscriber. *This parameter can be used only after your account receives approval. Contact support if you need this functionality.
    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.

    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",
            "lists": [
                {
                    "id": 1000,
                    "name": "Entire Church",
                    "joined_at": "2019-01-01T12:00:00+00:00"
                },
                {
                    "id": 1001,
                    "name": "Staff",
                    "joined_at": "2019-01-01T12:00:00+00:00"
                }
            ],
            "created_at": "2019-01-01T12:00:00+00:00",
            "updated_at": "2020-01-01T12:30:00+00:00",
            "opted_in_at": "2019-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 string false Comma-separated string of list IDs. If you pass this parameter, the subscriber will be added to the lists you specify and removed from all other lists. (Lists that are locked will be ignored.)

    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>

    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",
                "shortcode": "55498",
                "autoresponse": {
                    "enabled": false,
                    "text": {
                        "full": null,
                        "header": null,
                        "body": null
                    },
                    "setting": null
                },
                "opt_in": {
                    "enabled": false,
                    "lists": []
                },
                "workflow": {
                    "header": "The Early Church",
                    "timezone": "America/New_York",
                    "steps": [
                        {
                            "id": 1,
                            "delay_minutes": 0,
                            "delay_hours": 0,
                            "delay_days": 0,
                            "delay_weeks": 0,
                            "on_day_of_week": 0,
                            "at_time": 0,
                            "action": {
                                "type": "optin",
                                "lists": [
                                    {
                                        "id": 1000,
                                        "name": "Entire Church"
                                    }
                                ]
                            },
                            "should_pause": false
                        },
                        {
                            "id": 2,
                            "delay_minutes": 0,
                            "delay_hours": 0,
                            "delay_days": 0,
                            "delay_weeks": 0,
                            "on_day_of_week": 0,
                            "at_time": 0,
                            "action": {
                                "type": "autoresponse",
                                "text": "Thanks for joining!",
                                "send_only_first_use": false,
                                "send_only_multiple_use": false,
                                "send_only_new_subscriber": false,
                                "send_only_existing_subscriber": false
                            },
                            "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.

    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",
            "shortcode": "55498",
            "autoresponse": {
                "enabled": false,
                "text": {
                    "full": null,
                    "header": null,
                    "body": null
                },
                "setting": null
            },
            "opt_in": {
                "enabled": false,
                "lists": []
            },
            "workflow": {
                "header": "The Early Church",
                "timezone": "America/New_York",
                "steps": [
                    {
                        "id": 1,
                        "delay_minutes": 0,
                        "delay_hours": 0,
                        "delay_days": 0,
                        "delay_weeks": 0,
                        "on_day_of_week": 0,
                        "at_time": 0,
                        "action": {
                            "type": "optin",
                            "lists": [
                                {
                                    "id": 1000,
                                    "name": "Entire Church"
                                }
                            ]
                        },
                        "should_pause": false
                    },
                    {
                        "id": 2,
                        "delay_minutes": 0,
                        "delay_hours": 0,
                        "delay_days": 0,
                        "delay_weeks": 0,
                        "on_day_of_week": 0,
                        "at_time": 0,
                        "action": {
                            "type": "autoresponse",
                            "text": "Thanks for joining!",
                            "send_only_first_use": false,
                            "send_only_multiple_use": false,
                            "send_only_new_subscriber": false,
                            "send_only_existing_subscriber": false
                        },
                        "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",
            "shortcode": "55498",
            "autoresponse": {
                "enabled": false,
                "text": {
                    "full": null,
                    "header": null,
                    "body": null
                },
                "setting": null
            },
            "opt_in": {
                "enabled": false,
                "lists": []
            },
            "workflow": {
                "header": "The Early Church Youth",
                "timezone": "America/New_York",
                "steps": [
                    {
                        "id": 1,
                        "delay_minutes": 0,
                        "delay_hours": 0,
                        "delay_days": 0,
                        "delay_weeks": 0,
                        "on_day_of_week": 0,
                        "at_time": 0,
                        "action": {
                            "type": "optin",
                            "lists": [
                                {
                                    "id": 1000,
                                    "name": "Entire Church"
                                },
                                {
                                     "id": 1001,
                                     "name": "Staff"
                                 }
                            ]
                        },
                        "should_pause": false
                    },
                    {
                        "id": 2,
                        "delay_minutes": 0,
                        "delay_hours": 0,
                        "delay_days": 0,
                        "delay_weeks": 0,
                        "on_day_of_week": 0,
                        "at_time": 0,
                        "action": {
                            "type": "autoresponse",
                            "text": "Thanks for joining!",
                            "send_only_first_use": false,
                            "send_only_multiple_use": false,
                            "send_only_new_subscriber": false,
                            "send_only_existing_subscriber": false
                        },
                        "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).
    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 string false null Comma-separated string of list IDs to add the subscriber to. Required if enable_opt_in is 1.
    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. Can contain only GSM 7-bit characters. Together, the autoresponse_header and autoresponse_body cannot exceed 318 characters. 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.

    Update a Keyword

    curl -X PATCH "https://api.getclearstream.com/v1/keywords/2"
      -H "X-Api-Key: ABCDEFG123"
      -d "enable_opt_in=1"
      -d "opt_in_lists=1000"
      -d "enable_autoresponse=0"
    

    The above command returns:

    {
        "data": {
            "id": 2,
            "name": "earlyyouth",
            "shortcode": "55498",
            "autoresponse": {
                "enabled": false,
                "text": {
                    "full": null,
                    "header": null,
                    "body": null
                },
                "setting": null
            },
            "opt_in": {
                "enabled": false,
                "lists": []
            },
            "workflow": {
                "header": "The Early Church Youth",
                "timezone": "America/New_York",
                "steps": [
                    {
                        "id": 1,
                        "delay_minutes": 0,
                        "delay_hours": 0,
                        "delay_days": 0,
                        "delay_weeks": 0,
                        "on_day_of_week": 0,
                        "at_time": 0,
                        "action": {
                            "type": "optin",
                            "lists": [
                                {
                                    "id": 1000,
                                    "name": "Entire Church"
                                },
                                {
                                     "id": 1001,
                                     "name": "Staff"
                                 }
                            ]
                        },
                        "should_pause": false
                    },
                    {
                        "id": 2,
                        "delay_minutes": 0,
                        "delay_hours": 0,
                        "delay_days": 0,
                        "delay_weeks": 0,
                        "on_day_of_week": 0,
                        "at_time": 0,
                        "action": {
                            "type": "autoresponse",
                            "text": "Thanks for joining!",
                            "send_only_first_use": false,
                            "send_only_multiple_use": false,
                            "send_only_new_subscriber": false,
                            "send_only_existing_subscriber": false
                        },
                        "should_pause": false
                    }
                ]
            },
            "stats": {
                "opt_ins": {
                    "total": 0
                },
                "uses": {
                    "total": 0
                }
            }
        }
    }
    

    This endpoint updates the specified keyword.

    HTTP Request

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

    Parameters

    Parameter Type Required Default Description
    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 string false null Comma-separated string of list IDs to add the subscriber to. Required if enable_opt_in is 1.
    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. Can contain only GSM 7-bit characters. Together, the autoresponse_header and autoresponse_body cannot exceed 318 characters. 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>

    Messages

    View All Messages

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

    The above command returns:

    {
        "count": 12,
        "total": 12,
        "current_page": 1,
        "pages": 1,
        "limit": 20,
        "data": [
            {
                "id": 30010,
                "status": "SENT",
                "sent_at": "2016-06-12T10:04:06+00:00",
                "completed_at": "2016-06-12T05:04:06+00:00",
                "text": {
                    "header": "The Early Church",
                    "body": "The service starts in 30 minutes!"
                },
                "lists": [
                    {
                        "id": 1000,
                        "name": "Entire Church"
                    }
                ],
                "stats": {
                    "recipients": 2000,
                    "failures": 0,
                    "throughput": 250,
                    "replies": 10,
                    "opt_outs": 50
                },
                "social": {
                    "twitter": {
                        "enabled": false,
                        "id": null,
                        "url": null
                    },
                    "facebook": {
                        "enabled": false,
                        "id": null,
                        "url": null
                    }
                }
            },
            {
                "id": 30000,
                "status": "SENT",
                "sent_at": "2016-06-09T21:48:09+00:00",
                "completed_at": "2016-06-09T21:48:10+00:00",
                "text": {
                    "header": "The Early Church",
                    "body": "Need prayer? Just reply and we will pray!"
                },
                "lists": [
                    {
                        "id": 1000,
                        "name": "Entire Church"
                    }
                ],
                "stats": {
                    "recipients": 2000,
                    "failures": 0,
                    "throughput": 250,
                    "replies": 5,
                    "opt_outs": 25
                },
                "social": {
                    "twitter": {
                        "enabled": false,
                        "id": null,
                        "url": null
                    },
                    "facebook": {
                        "enabled": false,
                        "id": null,
                        "url": 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.

    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",
            "sent_at": "2016-06-09T21:48:09+00:00",
            "completed_at": "2016-06-09T21:48:10+00:00",
            "text": {
                "header": "The Early Church",
                "body": "Need prayer? Just reply and we will pray!"
            },
            "lists": [
                {
                    "id": 1000,
                    "name": "Entire Church"
                }
            ],
            "stats": {
                "recipients": 2000,
                "failures": 0,
                "throughput": 250,
                "replies": 5,
                "opt_outs": 25
            },
            "social": {
                "twitter": {
                    "enabled": false,
                    "id": null,
                    "url": null
                },
                "facebook": {
                    "enabled": false,
                    "id": null,
                    "url": 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",
            "sent_at": "2016-06-13T17:09:48+00:00",
            "completed_at": null,
            "text": {
                "header": "The Early Church",
                "body": "See you in the morning at 10AM!"
            },
            "lists": [
                {
                    "id": 1000,
                    "name": "Entire Church"
                }
            ],
            "stats": {
                "recipients": 2000,
                "failures": 0,
                "throughput": 0,
                "replies": 0,
                "opt_outs": 0
            },
            "social": {
                "twitter": {
                    "enabled": false,
                    "id": null,
                    "url": null
                },
                "facebook": {
                    "enabled": false,
                    "id": null,
                    "url": 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 true null Header for the message. Should be the name of your church or organization. Can contain only GSM 7-bit characters.
    message_body string true null Body for the message. Can contain only GSM 7-bit characters. Together, the message_header and message_body cannot exceed 318 characters.
    lists string false null Comma-separated string of list IDs to receive the message. Required, unless you pass the subscribers parameter.
    subscribers string false null Comma-separated string of active subscriber's mobile numbers (in E.164 format) to receive the message. Required if you do not pass the lists parameter. Note that if you pass both the lists and subscribers parameters, the subscribers parameter will be ignored.
    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.
    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": 5,
        "total": 5,
        "current_page": 1,
        "pages": 1,
        "limit": 30,
        "unread": 1,
        "data": [
            {
                "id": 80000,
                "unread": true,
                "reply_count": 1,
                "replied_at": "2016-06-10T02:48:31+00:00",
                "subscriber": {
                    "mobile_number": "+12005551000",
                    "status": "ACTIVE",
                    "first": "Jane",
                    "last": "Doe",
                    "email": null
                },
                "related_message": {
                    "id": 1000,
                    "sent_at": "2016-06-10T02:00:00+00:00",
                    "text": {
                        "header": "The Early Church",
                        "body": "See you in the morning at 10AM!"
                    }
                },
                "recent_replies": [
                    {
                        "id": 120000,
                        "text": "Thanks!",
                        "status": "RECEIVED",
                        "incoming": true,
                        "user": [],
                        "sent_at": "2016-06-10T02:48:31+00:00"
                    }
                ],
                "created_at": "2016-06-10T02:48:31+00:00",
                "updated_at": "2016-06-10T02:48:31+00:00",
                "archived_at": null
            },
            {
                "id": 77000,
                "unread": false,
                "reply_count": 3,
                "replied_at": "2016-06-09T21:43:43+00:00",
                "subscriber": {
                    "mobile_number": "+12005551001",
                    "status": "ACTIVE",
                    "first": "John",
                    "last": "Doe",
                    "email": 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"
                        },
                        "sent_at": "2016-05-18T05:23:15+00:00"
                    },
                    {
                        "id": 117999,
                        "text": ":)",
                        "status": "SENT",
                        "incoming": false,
                        "user": {
                            "id": 700,
                            "name": "Robert",
                            "email": "robert@theearly.church"
                        },
                        "sent_at": "2016-05-18T05:23:10+00:00"
                    },
                    {
                        "id": 117980,
                        "text": "Thanks! I'll be there!",
                        "status": "RECEIVED",
                        "incoming": true,
                        "user": [],
                        "sent_at": "2016-05-18T05:21:00+00:00"
                    }
                ],
                "created_at": "2016-05-18T05:21:00+00:00",
                "updated_at": "2016-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.
    text string false null Search for threads containing text.
    full_name string false null Search for threads by subscriber's name. (Partial match is acceptable.)
    mobile_number string false null Search for threads by subscriber's mobile number. (Partial match is acceptable.)
    archived string false not_archived Filter threads based on their archived status. Accepted options are archived, not_archived, and any.

    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": "2016-06-10T02:48:31+00:00",
            "subscriber": {
                "mobile_number": "+12005551000",
                "status": "ACTIVE",
                "first": "Jane",
                "last": "Doe",
                "email": null
            },
            "related_message": {
                "id": 1000,
                "sent_at": "2016-06-10T02:00:00+00:00",
                "text": {
                    "header": "The Early Church",
                    "body": "Can't wait to see you tomorrow at 10AM!"
                }
            },
            "recent_replies": [
                {
                    "id": 120000,
                    "text": "Thanks!",
                    "status": "RECEIVED",
                    "incoming": true,
                    "user": [],
                    "sent_at": "2016-06-10T02:48:31+00:00"
                }
            ],
            "created_at": "2016-06-10T02:48:31+00:00",
            "updated_at": "2016-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": [],
                "sent_at": "2016-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"
            },
            "sent_at": "2016-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. Can contain only GSM 7-bit characters. Cannot exceed 320 characters.

    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": "2016-06-10T02:48:31+00:00",
            "subscriber": {
                "mobile_number": "+12001001234",
                "status": "INACTIVE",
                "first": null,
                "last": null,
                "email": 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"
                    },
                    "sent_at": "2016-06-10T02:48:31+00:00"
                }
            ],
            "created_at": "2016-06-10T02:48:31+00:00",
            "updated_at": "2016-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. Can contain only GSM 7-bit characters. Together, the reply_header and reply_body cannot exceed 278 characters.
    longcode string false The number of the longcode to use for this thread. If supplied, must be in E.164 format. By default, the thread will be started using your account's shortcode. If your account doesn't have shortcode access, your account's longcode will be used.

    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

    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": "2020-01-10T02:48:31+00:00",
            "text": "Early Church: Hey thanks for visiting Sunday!",
            "to": "+12001001234",
            "from": "97000",
            "media": []
        }
    }
    

    This endpoint is a simple way to send a text message to a number. 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 true The mobile number to send a 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.
    text_body string true Body of the text. Can contain only GSM 7-bit characters. Together, the text_header and text_body cannot exceed 318 characters.
    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.
    override_optouts boolean false Whether to send the text even if the subscriber is opted-out. By passing this parameter, an opted-out subscriber's status will be changed to INACTIVE and they will receive the text. *This option is only available for accounts using a dedicated shortcode.

    Stats

    These endpoint expose statistical data about your account which you can use for performance analysis. Each endpoint requires 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).

    Total Subscribers

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

    The above command returns:

    {
        "meta": {
            "start": "2020-01-01T00:00:00+00:00",
            "end": "2020-01-07T23:59:59+00:00",
            "timezone": "UTC",
            "delimiter": "day"
        },
        "charts": {
            "subscribers": [
                [
                    "2020-01-01 00:00:00",
                    250
                ],
                [
                    "2020-01-02 00:00:00",
                    255
                ],
                [
                    "2020-01-03 00:00:00",
                    267
                ],
                [
                    "2020-01-04 00:00:00",
                    270
                ],
                [
                    "2020-01-05 00:00:00",
                    285
                ],
                [
                    "2020-01-06 00:00:00",
                    290
                ],
                [
                    "2020-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
    start string true null The start date in YYYY-MM-DD format.
    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: 2019-01-01"
      -d "end: 2019-01-03"
      -d "include_charts: 1"
    

    The above command returns:

    {
        "meta": {
            "start": "2020-01-01T00:00:00+00:00",
            "end": "2020-01-03T23:59:59+00:00",
            "timezone": "UTC",
            "delimiter": "day"
        },
        "totals": {
            "opt_ins": {
                "count": 15
            },
            "opt_outs": {
                "count": 2
            }
        },
        "charts": {
            "opt_ins": [
                [
                    "2020-01-01 00:00:00",
                    5
                ],
                [
                    "2020-01-02 00:00:00",
                    7
                ],
                [
                    "2020-01-03 00:00:00",
                    3
                ]
            ],
            "opt_outs": [
                [
                    "2020-01-01 00:00:00",
                    1
                ],
                [
                    "2020-01-02 00:00:00",
                    1
                ],
                [
                    "2020-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
    start string true null The start date in YYYY-MM-DD format.
    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.
    include_charts boolean false 0 Whether to include the charts property with daily/monthly statistics.
    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: 2019-01-01"
      -d "end: 2019-01-03"
      -d "include_charts: 1"
    

    The above command returns:

    {
        "meta": {
            "start": "2020-01-01T00:00:00+00:00",
            "end": "2020-01-03T23:59:59+00:00",
            "timezone": "UTC",
            "delimiter": "day"
        },
        "totals": {
            "incoming": {
                "count": 15
            },
            "outgoing": {
                "count": 2
            }
        },
        "charts": {
            "incoming": [
                [
                    "2020-01-01 00:00:00",
                    5
                ],
                [
                    "2020-01-02 00:00:00",
                    7
                ],
                [
                    "2020-01-03 00:00:00",
                    3
                ]
            ],
            "outgoing": [
                [
                    "2020-01-01 00:00:00",
                    1
                ],
                [
                    "2020-01-02 00:00:00",
                    1
                ],
                [
                    "2020-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
    start string true null The start date in YYYY-MM-DD format.
    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.
    include_charts boolean false 0 Whether to include the charts property with daily/monthly statistics.
    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: 2019-01-01"
      -d "end: 2019-01-03"
      -d "include_charts: 1"
    

    The above command returns:

    {
        "meta": {
            "start": "2020-01-01T00:00:00+00:00",
            "end": "2020-01-03T23:59:59+00:00",
            "timezone": "UTC",
            "delimiter": "day"
        },
        "totals": {
            "uses": {
                "count": 105
            }
        },
        "charts": {
            "uses": [
                [
                    "2020-01-01 00:00:00",
                    43
                ],
                [
                    "2020-01-02 00:00:00",
                    15
                ],
                [
                    "2020-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
    start string true null The start date in YYYY-MM-DD format.
    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.
    include_charts boolean false 0 Whether to include the charts property with daily/monthly statistics.
    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: 2019-01-01"
      -d "end: 2019-01-03"
      -d "include_charts: 1"
    

    The above command returns:

    {
        "meta": {
            "start": "2020-01-01T00:00:00+00:00",
            "end": "2020-01-03T23:59:59+00:00",
            "timezone": "UTC",
            "delimiter": "day"
        },
        "totals": {
            "uses": {
                "count": 25
            }
        },
        "charts": {
            "uses": [
                [
                    "2020-01-01 00:00:00",
                    17
                ],
                [
                    "2020-01-02 00:00:00",
                    3
                ],
                [
                    "2020-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
    start string true null The start date in YYYY-MM-DD format.
    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.
    include_charts boolean false 0 Whether to include the charts property with daily/monthly statistics.
    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": "2020-01-01T10:30:15+00:00",
            "end": "2020-01-01T10:35:15+00:00",
            "timezone": "UTC",
            "delimiter": "minute"
        },
        "totals": {
            "replies": {
                "count": 18
            }
        },
        "charts": {
            "uses": [
                [
                    "2020-01-01 10:30:15",
                    9
                ],
                [
                    "2020-01-01 10:31:15",
                    3
                ],
                [
                    "2020-01-01 10:32:15",
                    5
                ],
                [
                    "2020-01-01 10:33:15",
                    1
                ],
                [
                    "2020-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.
    include_charts boolean false 0 Whether to include the charts property with statistics.
    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 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.

    Keyword Used

    This event sends the following data:

    {
        "created_at": "2016-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: http://bit.ly/1PACYez",
            "override_optouts": 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. Can contain only GSM 7-bit characters. Together, the header and body cannot exceed 318 characters.
    response[override_optouts] boolean false Whether to send the text even if the subscriber is opted-out. By passing this parameter, an opted-out subscriber's status will be changed to INACTIVE and they will receive the text. *This option is only available for accounts using a dedicated shortcode.

    Message Report

    This event sends the following data:

    {
        "created_at": "2019-01-01T10:02:00+00:00",
        "event": "message.report",
        "production": true,
        "data": {
            "message": {
                "id": 1249380,
                "status": "SENT",
                "sent_at": "2019-01-01T09:30:00+00:00",
                "completed_at": "2019-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!"
                },
                "lists": [
                    {
                        "id": 193029,
                        "name": "Master List"
                    }
                ],
                "subscribers": [],
                "stats": {
                    "recipients": 5300,
                    "failures": 15,
                    "replies": 22,
                    "opt_outs": 19
                }
            }
        }
    }
    

    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": "2019-01-01T10:02:00+00:00",
        "event": "text.received",
        "production": true,
        "data": {
            "id": 128401298392,
            "status": "RECEIVED",
            "sent_at": "2019-01-01T10:02:00+00:00",
            "text": "Thanks so much!",
            "to": "97000",
            "from": "+12005551234",
            "account": {
                "id": 1000
            }
        }
    }
    

    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: http://bit.ly/1PACYez",
            "override_optouts": 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. Can contain only GSM 7-bit characters. Together, the header and body cannot exceed 318 characters.
    response[override_optouts] boolean false Whether to send the text even if the subscriber is opted-out. By passing this parameter, an opted-out subscriber's status will be changed to INACTIVE and they will receive the text. *This option is only available for accounts using a dedicated shortcode.

    Text Failed to Send

    This event sends the following data:

    {
        "created_at": "2019-01-01T10:02:00+00:00",
        "event": "text.failed",
        "production": true,
        "data": {
            "id": 1284018929,
            "status": "FAILED",
            "sent_at": "2019-01-01T10:02:00+00:00",
            "text": "Hey we have a great service coming up tomorrow!",
            "to": "+12005551234",
            "from": "97000",
            "account": {
                "id": 1000
            }
        }
    }
    

    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.