Settings
There is a lot for an administrator to customise in a Teamwire organisation. While there are dedicated endpoints for domains, logos, global app settings, email templates and the LDAP synchronisation process, settings encompass various miscellaneous options such as communication restrictions.
Manage Teamwire Organisation settings
Return organisation settings
GET /v<api_version>/admin/settings/<organisation_id>/
Access restrictions
- Admins and Superadmins must have the allow_view_settings permission.
- Admins can request the settings of their own organisation only.
- Superadmins can request the the settings of 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. |
| organisation_id | Number | Yes | All admins | The ID of the organisation to retrieve the settings for. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. The organisation settings are 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.) an organisation ID was specified and the calling admin is not a Superadmin. |
| 404 (Not found) | The request failed because the organisation could not be found. |
| 409 (Conflict) | The request failed because the organisation has been disabled. |
If the request was successful, a single JSON object with the following elements is returned:
| Name | Type | Visible to | Description |
|---|---|---|---|
privacy_mode |
String | All admins | The organisation’s privacy mode. One of Address book only, Internal and external, Internal only or Groups only. |
allow_user_reg |
Boolean | All admins | Whether new users are allowed to register. |
allow_query |
Boolean | All admins | Whether users are allowed to be found by users of other organisations. |
sync_group_members_only |
Boolean | All admins | Whether contact synchronisation is limited to group members in privacy modes “Internal only” and “Internal and external”. |
send_read_receipts |
Boolean | All admins | Whether to send read receipts or not. |
enable_user_login |
Boolean | All admins | Whether users are allowed to login with email address and login password. |
enable_webclient |
Boolean | All admins | Whether users are allowed to luse webclient |
enable_onboarding_bot |
Boolean | All admins | Whether display on-boarding bot to new registerusers. |
enable_admin_role_to_onboarding_bot |
Boolean | All admins | Whether on-boarding bot should have admin role on the chat. |
onboarding_bot_app_id |
String | All admins | On-boarding bot app ID. |
registration_token |
String | All admins | A string of up to 128 characters representing the organisation’s registration token, if configured. |
require_registration_token |
Boolean | All admins | Whether new users require the registration token to be able to register. |
messages_retention_period |
Number | All admins | The period in days to retain messages in the database until they will be deleted (0 = keep forever). |
connector_retention_period |
Number | All admins | The period in days to retain sessions in the database until they will be deleted. |
devices_per_user |
Integer | All admins | Limits connected devices per user (0 = unlimited). |
force_resync |
Boolean | All admins | Force clients to resync their contacts |
user_lower_case_required |
Boolean | All admins | User password must contain at least one lower case characters. |
user_max_failed_attempts |
Integer | All admins | Maximum number of failed attempts to login to the application. |
user_number_required |
Boolean | All admins | User password must contain at least one number. |
user_password_duration |
Integer | All admins | User password validation (days). Default value -1 mean password valid for ever. |
user_symbol_required |
Boolean | All admins | User password must contain at least one symbol. |
user_upper_case_required |
Boolean | All admins | User password must contain at least one upper case character. |
Set organisation settings
PUT /v<api_version>/admin/settings/<organisation_id>/
Access restrictions
- Admins and Superadmins must have the allow_modify_settings permission.
- Admins can update the settings of their own organisation only.
- Superadmins can update the settings of 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. |
| organisation_id | Number | Yes | All admins | The ID of the organisation to set the settings for. |
PUT data
Parameters are supplied as a JSON object with the following elements:
| Name | Type | Visible to | Description |
|---|---|---|---|
privacy_mode |
String | All admins | The organisation’s privacy mode. One of Address book only, Internal and external, Internal only or Groups only. |
allow_user_reg |
Boolean | All admins | Whether new users are allowed to register. |
allow_query |
Boolean | All admins | Whether users are allowed to be found by users of other organisations. |
sync_group_members_only |
Boolean | All admins | Whether contact synchronisation is limited to group members in privacy modes “Internal only” and “Internal and external”. |
send_read_receipts |
Boolean | All admins | Whether to send read receipts or not. |
enable_user_login |
Boolean | All admins | Whether users are allowed to login with email address and login password. |
enable_webclient |
Boolean | All admins | Whether users are allowed to luse webclient |
enable_onboarding_bot |
Boolean | All admins | Whether display on-boarding bot to new registerusers. |
enable_admin_role_to_onboarding_bot |
Boolean | All admins | Whether on-boarding bot should have admin role on the chat. |
onboarding_bot_app_id |
String | All admins | On-boarding bot app ID. |
registration_token |
String | All admins | A string of up to 128 characters representing the organisation’s registration token, if configured. |
require_registration_token |
Boolean | All admins | Whether new users require the registration token to be able to register. |
messages_retention_period |
Number | All admins | The period in days to retain messages in the database until they will be deleted (0 = keep forever). |
connector_retention_period |
Number | All admins | The period in days to retain sessions in the database until they will be deleted. |
devices_per_user |
Integer | All admins | Limits connected devices per user (0 = unlimited). |
force_resync |
Boolean | All admins | Force clients to resync their contacts |
user_lower_case_required |
Boolean | All admins | User password must contain at least one lower case characters. |
user_max_failed_attempts |
Integer | All admins | Maximum number of failed attempts to login to the application. |
user_number_required |
Boolean | All admins | User password must contain at least one number. |
user_password_duration |
Integer | All admins | User password validation (days). Default value -1 mean password valid for ever. |
user_symbol_required |
Boolean | All admins | User password must contain at least one symbol. |
user_upper_case_required |
Boolean | All admins | User password must contain at least one upper case character. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. The organisation settings have been updated. |
| 400 (Bad request) | The request failed because an invalid parameter was supplied. Inspect the error message for details. |
| 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.) an organisation ID was specified and the calling admin is not a Superadmin. |
| 404 (Not found) | The request failed because the organisation could not be found or organisation is from different backend federation. |
| 409 (Conflict) | The request failed because the organisation has been disabled. |