Groups
A Teamwire group represents a collection of Teamwire users created by a Teamwire admin or the LDAP synchronisation process. It is non-exclusive in that users can be members of multiple groups at the same time.
Manage groups
Create a new group
POST /v<api_version>/admin/groups/
Access restrictions
- Admins and Superadmins must have the allow_modify_groups permission.
- Admins can create groups in their own organisation only.
- Superadmins can create groups in any organisation.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
POST data
Parameters are supplied as a JSON object with the following elements:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
title |
String | No | All admins | The title for the new group. |
organisation_id |
Number | Yes | All admins | The ID of the organisation to create the group in. |
allow_federation |
Boolean | Yes | Super Admin | Either created group will be federated or not. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. Information about the created group is returned as a JSON object as described below. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled, b.) the admin is not a Superadmin and an organisation_id was specified that does not match the admin’s organisation, c.) the organisation’s privacy mode is set to Address book only which does not allow for creation of groups or d.) the admin is not a Superadmin and is_federated was positive. |
| 404 (Not found) | The request failed because there was no organisation with the specified organisation_id or organisation is from different backend federation. |
| 409 (Conflict) | The request failed because the organisation to create the group in has been disabled. |
If the request was successful, a single JSON object is returned with the following elements:
| Name | Type | Visible to | Description |
|---|---|---|---|
id |
Number | All admins | The group’s ID. |
title |
String | All admins | The group’s title. |
organisation_id |
Number | All admins | The ID of the organisation the group belongs to. |
origin |
String | All admins | The group’s origin, currently either Native (the group has been created through the Enterprise API) or LDAP (the group has been created by the LDAP synchronisation process). |
origin_id |
String | All admins | For an origin other than Native this is a reference to the associated group object within that origin, e.g. for an origin of LDAP this will be the DN of the LDAP group object the Teamwire group was created for. With native groups this will be an empty string. |
member_count |
Number | All admins | This will always be 0 since the group has only just been created. |
allow_federation |
Bool | All admins | This will be mostly set as False, only circle dedicated to communicate with different backend should be set positive. |
Return a list of groups or details about a particular group
GET /v<api_version>/admin/groups/
GET /v<api_version>/admin/groups/<group_id>/
Access restrictions
- Admins and Superadmins must have the allow_view_groups permission.
- Admins can request details of groups in their own organisation only.
- Superadmins can request details of groups in any organisation.
- If no group_id is specified:
- admins will receive a list of groups in their own organisation only.
- Superadmins will receive a list of groups in all organisations.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| group_id | Integer | Yes | All admins | The ID of a particular group for which details should be returned. |
HTTP header parameters
The following parameters are specified as part of the HTTP request header:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
if_modified_since |
Timestamp | Yes | All admins | If specified, only groups modified since the given timestamp will be returned. The timestamp must adhere to the standard HTTP format of “day name, day month year hour:minute:second GMT”. Unlike with HTTP, however, if no groups were modified the response code will stay 200 but the returned JSON list will be empty. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful, group(s) information will be returned as a JSON object as described below. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled or b.) the admin is not a Superadmin and a group was specified that does not belong to the admin’s organisation. |
| 404 (Not found) | The request failed because there was no group with this ID or groups belongs to different backend in the federated. |
| 406 (Not acceptable) | The request failed because the group is neither a Teamwire-native group nor an LDAP group. Note that LDAP groups do not allow for modification through the Enterprise API. |
| 409 (Conflict) | The request failed because the organisation the group(s) belong(s) to has been disabled. |
If a group ID was specified and the request was successful, a JSON object is returned with the following elements:
| Name | Type | Visible to | Description |
|---|---|---|---|
id |
Number | All admins | The group’s ID. |
deleted |
Boolean | All admins | This element will only be present and have the value True if the requested group has been deleted. In this case the following fields must be ignored because they will not contain valid data. |
title |
String | All admins | The group’s title. |
organisation_id |
Number | All admins | The ID of the organisation the group belongs to. |
origin |
String | All admins | The group’s origin, currently either “Native” (the group has been created through the Enterprise API) or “LDAP” (the group has been created by the LDAP synchronisation process). |
origin_id |
String | All admins | For an origin other than Native this is a reference to the associated group object within that origin, e.g. for an origin of LDAP this will be the DN of the LDAP group the Teamwire group was created for. With native groups this will be an empty string. |
members |
Array | All admins | An array of IDs of users (strings) that are member of this group. |
If the special keyword “all” was specified and the request was successful, the JSON structure returned is an array of objects with the following elements:
| Name | Type | Visible to | Description |
|---|---|---|---|
id |
Number | All admins | The group’s ID. |
deleted |
Boolean | All admins | This element will only be present and have the value True if the requested group has been deleted. In this case the following fields must be ignored because they will not contain valid data. |
title |
String | All admins | The group’s title. |
organisation_id |
Number | All admins | The ID of the organisation the group belongs to. |
is_public |
Bool | All admins | The group’s is_public flag |
origin |
String | All admins | The group’s origin, currently either “Native” (the group has been created through the Enterprise API) or “LDAP” (the group has been created by the LDAP synchronisation process). |
origin_id |
String | All admins | For an origin other than Native this is a reference to the associated group object within that origin, e.g. for an origin of LDAP this will be the DN of the LDAP group the Teamwire group was created for. With native groups this will be an empty string. |
member_count |
Number | All admins | The number of users in this group. |
Update an existing group
PUT /v<api_version>/admin/groups/<group_id>/
Access restrictions
- Admins and Superadmins must have the allow_modify_groups permission.
- Admins can update groups in their own organisation only.
- Superadmins can update groups in any organisation.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| group_id | Integer | No | All admins | The ID of the group to update. |
PUT data
Parameters are supplied as a JSON object with the following elements:
| Name | Type | Optional? | For use by | Description |
|---|---|---|---|---|
title |
String | Yes | All admins | The new title for the group. |
| `is_public | Bool | Yes | All admins | Public flag. Public groups aim to allow any user in the organization to send messages to these groups, even if they are not member of. |
allow_federation |
Bool | Yes | Super Admin | Either created group will be federated or not. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful, updated group information will be returned as a JSON object as described below. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled or b.) the admin is not a Superadmin and a group was specified that does not belong to the admin’s organisation. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled, b.) the admin is not a Superadmin and an organisation_id was specified that does not match the admin’s organisation, or c.) the admin is not a Superadmin and is_federated was positive. |
| 404 (Not found) | The request failed because there was no group with this ID or group is from different backend federation. |
| 406 (Not acceptable) | The request failed because the group is not a Teamwire-native group, i.e. it has a different origin that does not allow for modification through the Enterprise API. |
| 406 (Not acceptable) | The request failed because the group is Teamwire-native public group, and user tries to make it private again. |
| 409 (Conflict) | The request failed because the organisation the group belongs to has been disabled. |
If the request was successful, a JSON object is returned with the following elements:
| Name | Type | Visible to | Description |
|---|---|---|---|
id |
Number | All admins | The group’s ID. |
title |
String | All admins | The group’s title. |
organisation_id |
Number | All admins | The ID of the organisation the group belongs to. |
is_public |
Bool | All admins | The group’s is_public flag |
origin |
String | All admins | The group’s origin, currently either “Native” (the group has been created through the Enterprise API) or “LDAP” (the group has been created by the LDAP synchronisation process). |
origin_id |
String | All admins | For an origin other than Native this is a reference to the associated group object within that origin, e.g. for an origin of LDAP this will be the DN of the LDAP group the Teamwire group was created for. With native groups this will be an empty string. |
members |
Array | All admins | An array of IDs of users (strings) that are member of this group. |
allow_federation |
Bollean | All admins | This will be mostly set as False, only circle dedicated to communicate with different backend should be set positive. |
Delete a group
DELETE /v<api_version>/admin/groups/<group_id>/
Calling this endpoint will only delete the group itself, i.e. it will not delete the users in the group.
Access restrictions
- Admins and Superadmins must have the allow_modify_groups permission.
- Admins can delete groups in their own organisation only.
- Superadmins can delete groups in any organisation.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| group_id | Integer | No | All admins | The ID of the group to delete. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful, the group has been deleted. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled, b.) the admin is not a Superadmin and an organisation_id was specified that does not match the admin’s organisation, or c.) the admin is not a Superadmin and is_federated was positive. |
| 404 (Not found) | The request failed because there was no group with this ID or group is from different backend federation. |
| 406 (Not acceptable) | The request failed because the group is not a Teamwire-native group, i.e. it has a different origin that does not allow for deletion through the Enterprise API. |
| 409 (Conflict) | The request failed because the organisation the group belongs to has been disabled. |
Manage group memberships
Add users to a group
POST /v<api_version>/admin/groups/<group_id>/members/
Access restrictions
- Admins and Superadmins must have the allow_modify_groups permission.
- Admins can add users to groups in their own organisation only.
- Superadmins can add users to groups in any organisation.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| group_id | Integer | No | All admins | The ID of the group to add users to. |
POST data
Parameters are supplied as a JSON object with the following elements:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
users |
Array | No | All admins | A JSON array of strings representing the user IDs to be added to the group. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful, the users have been added to the group. |
| 400 (Bad request) | The request failed because either a.) no user IDs were specified or b.) the array of user IDs contained at least one invalid user ID (e.g. a user that does not exist or a user that is not in the admin’s organisation and the admin is not a Superadmin). |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled or b.) b.) the admin is not a Superadmin and a group was specified that does not belong to the admin’s organisation. |
| 404 (Not found) | The request failed because there was no group with this ID or group is from different backend federation. |
| 406 (Not acceptable) | The request failed because the group is not a Teamwire-native group, i.e. it has a different origin that does not allow for modification through the Enterprise API. |
| 409 (Conflict) | The request failed because the organisation the group belongs to has been disabled. |
Remove a user from a group
DELETE /v<api_version>/admin/groups/<group_id>/members/<user_id>/
Access restrictions
- Admins and Superadmins must have the allow_modify_groups permission.
- Admins can remove users from groups in their own organisation only.
- Superadmins can remove users from groups in any organisation.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| group_id | Integer | No | All admins | The ID of the group to remove the user from. |
| user_id | String | No | All admins | The ID of the user to remove from the group. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful, the user has been removed from the group. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled or b.) the admin is not a Superadmin and a group was specified that does not belong to the admin’s organisation. |
| 404 (Not found) | The request failed because either the user or group could not be found or user or group is from different backend federation. |
| 406 (Not acceptable) | The request failed because the group is not a Teamwire-native group, i.e. it has a different origin that does not allow for modification through the Enterprise API. |
| 409 (Conflict) | The request failed because the organisation the group belongs to has been disabled. |