Groups¶
The Groups resource allows you to:
- Add a group via POST
- Collect group data via GET
- Add and remove contacts to/from a group via POST, on the nested Contacts resource
- Edit a group via PUT
- Delete a group via DELETE
Adding a Group¶
To add a new group you make a POST request to the Groups resource.
The POST url is: https://api.sendhub.com/v1/groups/?username=USERNAME&api_key=APIKEY
Where:
- USERNAME - is your SendHub username.
- APIKEY - is your api key which can be found on the settings page.
You’ll also need to pass Headers and Data.
Headers:
Content-Type: application/json
Data:
For example to create the groups ‘Regulars’ you would POST:
{
"name": "Regulars",
"slug": "regulars",
"text_to_subscribe": true
}
Note
Slug does not need to match the group name.
Slug is listed as ‘Keyword’ on SendHub.com and allows contacts to add themselves to a group by texting the keyword to your SendHub number, if ‘text_to_subscribe’ is set to true.
Therefore, to add a group through the API using cURL:
curl -H "Content-Type: application/json" -X POST --data '{"name": "Regulars", "slug": "regulars","text_to_subscribe": true }' 'https://api.sendhub.com/v1/groups/?username=USERNAME&api_key=APIKEY'
If your group is accepted you’ll get a 201 Created status and a data response similar to this:
{
"date_created": "2012-05-31T18:18:23.172930",
"date_modified": "2012-05-31T18:18:23.172965",
"id": "12",
"name": "Regulars",
"resource_uri": "/api/v1/groups/12/",
"size": null,
"slug": "regulars",
"text_to_subscribe": true
}
Available Fields:
| Name | Explanation |
|---|---|
| id | The group’s unique identifier. Read only. |
| name | The group’s name. |
| slug | The group’s keyword. |
| text_to_subscribe | Boolean. If true contacts can join the group by texting the slug to your SendHub number. |
| size | Total contacts in the group. Null on group creation. |
| resource_uri | The uri for this group. Read only. |
| date_created | The UTC time this group was created. Read only. |
| date_modified | The UTC time this group was last changed. Read only. |
Collect Groups List¶
To collect a list of your groups you make a GET request to the Groups resource:
https://api.sendhub.com/v1/groups/?username=USERNAME&api_key=APIKEY
If your request is accepted you’ll get a 200 Ok status and a data response similar to this:
{
"meta": {
"limit": 20,
"next": null,
"offset": 0,
"previous": null,
"total_count": 2
},
"objects": [
{
"date_created": "2012-05-31T18:18:23.172930",
"date_modified": "2012-05-31T18:18:23.172965",
"id": "1000",
"name": "demo",
"resource_uri": "/api/v1/groups/1000/",
"size": 1,
"slug": "demo",
"text_to_subscribe": true
},
{
"date_created": "2012-05-31T18:18:23.172930",
"date_modified": "2012-05-31T18:18:23.172965",
"id": "1001",
"name": "customers",
"resource_uri": "/api/v1/groups/1001/",
"size": 0,
"slug": "customers",
"text_to_subscribe": false
}
]
}
Available Fields:
| Name | Explanation |
|---|---|
| limit | The number of groups displayed on a page. |
| next | The path to the next page of groups, if available. |
| offset | The starting group for the current page. |
| previous | The path to the previous page of the groups list, if available. |
| total_count | The total number of groups. |
| objects | The list of groups. |
Collect a Single Group’s Data¶
To collect a group’s data you make a GET request to the Groups resource, with the group’s id:
https://api.sendhub.com/v1/groups/ID/?username=USERNAME&api_key=APIKEY
Where:
- ID - is the group’s id. This can be obtained from the id or resource_uri field.
If your request is accepted you’ll get a 200 Ok status and a data response similar to this:
{
"date_created": "2012-05-31T18:18:23.172930",
"date_modified": "2012-05-31T18:18:23.172965",
"id": "1220",
"name": "Regulars",
"resource_uri": "/api/v1/groups/1220/",
"size": 2,
"slug": "regulars",
"text_to_subscribe": true
}
Collect a Group’s Contacts¶
To collect a group’s cpntact list you make a GET request to the Groups resource, adding ‘/contacts’ to url:
https://api.sendhub.com/v1/groups/ID/contacts?username=USERNAME&api_key=APIKEY
Where:
- ID - is the group’s id. This can be obtained from the id or resource_uri field.
If your request is accepted you’ll get a 200 Ok status and a data response similar to this:
{
"meta": {
"limit": 20,
"next": null,
"offset": 0,
"previous": null,
"total_count": 2
},
"objects": [
{
"blocked": false,
"date_created": "2012-05-31T17:44:17.406108",
"date_modified": "2012-05-31T17:44:17.406139",
"groups": [
"/api/v1/groups/1220/"
],
"id": "22081",
"name": "John Doe",
"number": "+6501234567",
"resource_uri": "/api/v1/contacts/22081/"
},
{
"blocked": false,
"date_created": "2012-05-31T17:44:17.406108",
"date_modified": "2012-05-31T17:44:17.406139",
"groups": [
"/api/v1/groups/1220/"
],
"id": "22411",
"name": "Jesse Doe",
"number": "+16507654321",
"resource_uri": "/api/v1/contacts/22411/"
}
]
}
Adding and Removing Contacts¶
To add or remove contacts from a Group, make a POST request to the Groups resource, with the group’s id , adding ‘/contacts’ to url:
https://api.sendhub.com/v1/groups/ID/contacts/?username=USERNAME&api_key=APIKEY
Where:
- ID - is the group’s id. This can be obtained from the id or resource_uri field.
You’ll also need to pass Headers and Data.
Headers:
Content-Type: application/json
Data:
Add a contact, remove 2 contacts.
{
"add": [
22081
],
"remove": [
22411,
22412
]
}
Note
Adding or removing contacts to/from a group will update each contact’s date_modified timestamp.
Available Fields:
| Name | Explanation |
|---|---|
| add | The list of contact ids to be added to the group. |
| remove | The list of contacts ids to be removed from the group. |
Editing a Group¶
To edit a group you make a PUT request to the Groups resource, with the group’s id.
https://api.sendhub.com/v1/groups/ID?username=USERNAME&api_key=APIKEY
Where:
- ID - is the group’s id. This can be obtained from the id or resource_uri field.
You’ll also need to pass Headers and Data.
Headers:
Content-Type: application/json
Data:
The following request changes the name of the group from ‘Regulars’ to ‘Best Customers’ but retains the same keyword/slug.
{
"id": "1220",
"name": "Best Customers",
"slug": "regulars"
"text_to_subscribe": true
}
Note
If you do not include ‘text_to_subscribe’ in your data, it will be set to false by the PUT.
If your request is accepted you’ll get a 202 Accepted status and a data response similar to this:
{
"date_created": "2012-05-31T18:18:23.172930",
"date_modified": "2012-05-31T19:29:41.59932",
"id": "1220",
"name": "Regulars",
"resource_uri": "/api/v1/groups/1220/",
"size": 2,
"slug": "regulars",
"text_to_subscribe": true
}
Note
ID and name are required fields for group editing.
Note
Editing group information will update the date_modified field to the current time.
Deleting a Group¶
To delete a group you make a DELETE request to the Groups resource, with the group’s id.
https://api.sendhub.com/v1/groups/ID/?username=USERNAME&api_key=APIKEY
Where:
- ID - is the group’s id. This can be obtained from the id or resource_uri field.
Therefore, to delete a contact through the API using cURL:
curl -H "Content-Type: application/json" -X DELETE 'https://api.sendhub.com/v1/groups/ID/?username=USERNAME&api_key=APIKEY'
If your request is accepted you’ll get a 204 No Content status, indicating the contact has been successfully deleted.