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.
We will also be releasing language wrappers for the API, to facilitate development. If you have a specific language that you would like to see included, please get in touch.
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: ABCDEFG123
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. |
Account
View Account
curl "https://api.getclearstream.com/v1/account"
-H "X-Api-Key: ABCDEFG123"
The above command returns:
{
"data": {
"business": "Blue Sushi",
"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. |
Update Account
curl -X PATCH "https://api.getclearstream.com/v1/account"
-H "X-Api-Key: ABCDEFG123"
-d "business=Red Sushi"
The above command returns:
{
"data": {
"business": "Red Sushi",
"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 business. |
| 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@blue.sushi",
"name": "Robert",
"email_notifications": {
"incoming_reply": true,
"opt_in": true
},
"timezone": "America/New_York",
"owner": true
},
{
"email": "sue@blue.sushi",
"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@blue.sushi"
-H "X-Api-Key: ABCDEFG123"
The above command returns:
{
"data": {
"email": "sue@blue.sushi",
"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": "Customers",
"subscriber_count": 2000
},
{
"id": 1001,
"name": "Employees",
"subscriber_count": 30
}
]
}
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": "Customers",
"subscriber_count": 2000
}
}
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
}
}
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
}
}
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",
"email": null
},
{
"mobile_number": "+12005550001",
"status": "ACTIVE",
"first": "John",
"last": "Doe",
"email": 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 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. |
| 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. |
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",
"email": null,
"lists": [
{
"id": 1000,
"name": "Customers"
}
]
},
{
"mobile_number": "+12005551001",
"status": "ACTIVE",
"first": "John",
"last": "Doe",
"email": null,
"lists": [
{
"id": 1000,
"name": "Customers"
}
]
},
...
]
}
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 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. |
| 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",
"email": null,
"lists": [
{
"id": 1000,
"name": "Customers"
}
]
}
}
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,
"email": null,
"lists": [
{
"id": 1000,
"name": "Customers"
},
{
"id": 1001,
"name": "Employees"
}
]
}
}
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 | Description |
|---|---|---|---|
| mobile_number | string | true | The mobile number of the subscriber to create. Must be in E.164 format. |
| lists | string | true | Comma-separated string of list IDs to add the subscriber to. |
| first | string | false | The first name of the subscriber. |
| last | string | false | The last name of the subscriber. |
| string | false | The email address of the subscriber. | |
| autoresponse_header | string | false | Header for the auto-response text that a subscriber should receive after confirming their opt-in. Should be the name of your business or organization. Can contain only GSM 7-bit characters. Required if autoresponse_body is supplied. |
| autoresponse_body | string | false | Body for the auto-response 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 158 characters. Required if autoresponse_header is supplied. |
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@blue.sushi"
The above command returns:
{
"data": {
"mobile_number": "+12005551002",
"status": "ACTIVE",
"first": "Bob",
"last": "Doe",
"email": "bob@blue.sushi",
"lists": [
{
"id": 1000,
"name": "Customers"
},
{
"id": 1001,
"name": "Employees"
}
]
}
}
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. |
| string | false | The email address of the subscriber. |
Delete 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 deletes the specified subscriber, opting them out of 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": [
{
"name": "bluesushi",
"shortcode": "55498",
"autoresponse": {
"enabled": true,
"text": {
"header": "Blue Sushi",
"body": "Thanks for joining!"
},
"setting": "ALWAYS"
},
"opt_in": {
"enabled": true,
"lists": [
{
"id": 1000,
"name": "Customers"
}
]
},
"stats": {
"opt_ins": {
"total": 2000
}
}
}
]
}
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/bluesushi"
-H "X-Api-Key: ABCDEFG123"
The above command returns:
{
"data": {
"name": "bluesushi",
"shortcode": "55498",
"autoresponse": {
"enabled": true,
"text": {
"header": "Blue Sushi",
"body": "Thanks for joining!"
},
"setting": "ALWAYS"
},
"opt_in": {
"enabled": true,
"lists": [
{
"id": 1000,
"name": "Customers"
}
]
},
"stats": {
"opt_ins": {
"total": 2000
}
}
}
}
This endpoint retrieves details for the specified keyword.
HTTP Request
GET https://api.getclearstream.com/v1/keywords/<name>
Create a Keyword
curl -X POST "https://api.getclearstream.com/v1/keywords"
-H "X-Api-Key: ABCDEFG123"
-d "name=redsushi"
-d "enable_opt_in=1"
-d "opt_in_lists=1000,1001"
-d "enable_autoresponse=1"
-d "autoresponse_header=Red Sushi"
-d "autoresponse_body=Thanks for joining!"
-d "autoresponse_setting=ALWAYS"
The above command returns:
{
"data": {
"name": "redsushi",
"shortcode": "55498",
"autoresponse": {
"enabled": true,
"text": {
"header": "Red Sushi",
"body": "Thanks for joining!"
},
"setting": "ALWAYS"
},
"opt_in": {
"enabled": true,
"lists": [
{
"id": 1000,
"name": "Customers"
},
{
"id": 1001,
"name": "Employees"
}
]
},
"stats": {
"opt_ins": {
"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 auto-response text when a subscriber texts this keyword. Must be a 1 or 0. |
| autoresponse_header | string | false | null | Header for the auto-response text. Should be the name of your business or organization. Can contain only GSM 7-bit characters. Required if enable_autoresponse is 1. |
| autoresponse_body | string | false | null | Body for the auto-response text. Can contain only GSM 7-bit characters. Together, the autoresponse_header and autoresponse_body cannot exceed 158 characters. Required if enable_autoresponse is 1. |
| autoresponse_setting | string | false | null | When to send the auto-response 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/redsushi"
-H "X-Api-Key: ABCDEFG123"
-d "enable_opt_in=1"
-d "opt_in_lists=1000"
-d "enable_autoresponse=0"
The above command returns:
{
"data": {
"name": "redsushi",
"shortcode": "55498"
"autoresponse": {
"enabled": false,
"text": {
"header": null,
"body": null
},
"setting": null
},
"opt_in": {
"enabled": true,
"lists": [
{
"id": 1000,
"name": "Customers"
}
]
},
"stats": {
"opt_ins": {
"total": 0
}
}
}
}
This endpoint updates the specified keyword.
HTTP Request
PATCH https://api.getclearstream.com/v1/keywords/<name>
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 auto-response text when a subscriber texts this keyword. Must be a 1 or 0. |
| autoresponse_header | string | false | null | Header for the auto-response text. Should be the name of your business or organization. Can contain only GSM 7-bit characters. Required if enable_autoresponse is 1. |
| autoresponse_body | string | false | null | Body for the auto-response text. Can contain only GSM 7-bit characters. Together, the autoresponse_header and autoresponse_body cannot exceed 158 characters. Required if enable_autoresponse is 1. |
| autoresponse_setting | string | false | null | When to send the auto-response 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/redsushi"
-H "X-Api-Key: ABCDEFG123"
The above command returns:
{
"deleted": true,
"name": "redsushi"
}
This endpoint deletes the specified keyword.
HTTP Request
DELETE https://api.getclearstream.com/v1/keywords/<name>
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:06Z",
"completed_at": "2016-06-12T05:04:06Z",
"text": {
"header": "Blue Sushi",
"body": "Come buy sushi at 50% off for the next 30 minutes!"
},
"lists": [
{
"id": 1000,
"name": "Customers"
}
],
"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:09Z",
"completed_at": "2016-06-09T21:48:10Z",
"text": {
"header": "Blue Sushi",
"body": "Hungy for sushi? Try our new Lava Roll for just $9!"
},
"lists": [
{
"id": 1000,
"name": "Customers"
}
],
"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:09Z",
"completed_at": "2016-06-09T21:48:10Z",
"text": {
"header": "Blue Sushi",
"body": "Hungy for sushi? Try our new Lava Roll for just $9!"
},
"lists": [
{
"id": 1000,
"name": "Customers"
}
],
"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=Blue Sushi"
-d "message_body=Come in now for 50% off all rolls!"
-d "lists=1000"
The above command returns:
{
"data": {
"id": 30002,
"status": "QUEUED",
"sent_at": "2016-06-13T17:09:48Z",
"completed_at": null,
"text": {
"header": "Blue Sushi",
"body": "Come in now for 50% off all rolls!"
},
"lists": [
{
"id": 1000,
"name": "Customers"
}
],
"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 business 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 158 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:31Z",
"subscriber": {
"mobile_number": "+12005551000",
"status": "ACTIVE",
"first": "Jane",
"last": "Doe",
"email": null
},
"recent_replies": [
{
"id": 120000,
"text": "Thanks!",
"status": "RECEIVED",
"incoming": true,
"user": [],
"sent_at": "2016-06-10T02:48:31Z"
}
]
},
{
"id": 77000,
"unread": false,
"reply_count": 3,
"replied_at": "2016-06-09T21:43:43Z",
"subscriber": {
"mobile_number": "+12005551001",
"status": "ACTIVE",
"first": "John",
"last": "Doe",
"email": null
},
"recent_replies": [
{
"id": 118000,
"text": "Happy to hear!",
"status": "SENT",
"incoming": false,
"user": {
"id": 700,
"name": "Robert",
"email": "robert@blue.sushi"
},
"sent_at": "2016-05-18T05:23:15Z"
},
{
"id": 117999,
"text": ":)",
"status": "SENT",
"incoming": false,
"user": {
"id": 700,
"name": "Robert",
"email": "robert@blue.sushi"
},
"sent_at": "2016-05-18T05:23:10Z"
},
{
"id": 117980,
"text": "Thanks! I'll be in soon!",
"status": "RECEIVED",
"incoming": true,
"user": [],
"sent_at": "2016-05-18T05:21:00Z"
}
]
},
...
]
}
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. |
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:31Z",
"subscriber": {
"mobile_number": "+12005551000",
"status": "ACTIVE",
"first": "Jane",
"last": "Doe",
"email": null
},
"recent_replies": [
{
"id": 120000,
"text": "Thanks!",
"status": "RECEIVED",
"incoming": true,
"user": [],
"sent_at": "2016-06-10T02:48:31Z"
}
]
}
}
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:31Z"
}
]
}
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@blue.sushi"
},
"sent_at": "2016-06-10T02:50:00Z"
}
}
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 160 characters. |
Delete 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 deletes the specified thread.
HTTP Request
DELETE https://api.getclearstream.com/v1/threads/<id>
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 received properly. 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.
Keyword Used
This event sends the following data:
{
"created_at": "2016-06-12T10:00:00Z",
"event": "keyword.used",
"data": {
"keyword": {
"name": "bluesushi",
"shortcode": "55498"
},
"thread": {
"id": 152390
},
"reply": {
"id": 935094,
"text": "bluesushi Great meal!"
},
"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": "Blue Sushi",
"body": "Thanks for joining! Here's your custom URL: http://bit.ly/1PACYez"
}
}
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 business 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 158 characters. |
Message Report
This event sends the following data:
{
"created_at": "2019-01-01T10:02:00Z",
"event": "message.report",
"data": {
"message": {
"id": 1249380,
"status": "SENT",
"sent_at": "2019-01-01T09:30:00Z",
"completed_at": "2019-01-01T09:32:00Z",
"text" : {
"full": "Blue Sushi: We have a really great weekend coming up! Stay tuned!",
"header": "Blue Sushi",
"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.