================ 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.