PUT/groups/{groupId}

Updates a group for an external key of the customer or for a resource ID. This API operation cannot update an external group.

  • If a group to be updated is a dynamic group, the specified members field is ignored because members are automatically added or deleted based on conditions.

Caution

  • To update a group which uses the Message Room features, you need to get the group information to check the relevant parameters and pass the results with this API operation, or use the "Update part of a group" API operation. The default value of each parameter is "false", so if the parameter values are not specified, the relevant features are not enabled.

Authorization

oauth2

OAuth 2.0 authentication.
For more information, see Authentication and Authorization.

Scope

directory
group

HTTP Request

PUThttps://www.worksapis.com/v1.0/groups/{groupId}

Path Parameters

ParameterTypeDescription
groupId string 

Group ID or external key.
External key in "externalKey:{externalKey}" format


required 

Header Parameters

HeadertypeDescription
Authorization string 

Bearer {token}


required 
Content-Type string 

application/json


required
example : application/json 

Request Body

PropertyTypeDescription
domainId integer 

Domain ID


required
format : int32 
groupName string 

Group name. It must be unique within the domain.


required
maxLength : 100 
description string 

Group description


maxLength : 300
nullable : true 
visible boolean 

Indicates whether to make the group visible. It indicates whether to make the group visible in search results for users who are not managers or members.


default : true 
useServiceNotification boolean 

Indicates whether to send service notifications.


default : false 
serviceManageable boolean 

Indicates whether a group master can change whether to use the service.


default : true 
groupExternalKey string 

Group external key


maxLength : 100
nullable : true 
administrators array (GroupAdministrator) 

List of group masters


required
minItems : 1 
members array (GroupMember) 

List of group members


required 
useMessage boolean 

Indicates whether to use the Message Room features.

  • If it is set to "false", the chat history of all the members is deleted and the Message Room features (Note, Calendar, Folder, and Task) are disabled after 30 days.
  • Set this parameter to "true" again within 30 days to recover the previous data. Setting it to "true" after 30 days cannot recover the previous data; it only creates a new message room.

default : false 
useNote boolean 

Indicates whether to use the Message Room Note feature.

  • If it is set to "false", the feature is disabled. To view the previous data, set this parameter to "true".
  • This parameter is available only if useMessage is "true".

default : false 
useCalendar boolean 

Indicates whether to use the Message Room Calendar feature.

  • If it is set to "false", the feature is disabled. To view the previous data, set this parameter to "true".
  • This parameter is available only if useMessage is "true".

default : false 
useTask boolean 

Indicates whether to use the Message Room Task feature.

  • If it is set to "false", the feature is disabled. To view the previous data, set this parameter to "true".
  • This parameter is available only if useMessage is "true".

default : false 
useFolder boolean 

Indicates whether to use the Message Room Folder feature.

  • If it is set to "false", the feature is disabled. To view the previous data, set this parameter to "true".
  • This parameter is available only if useMessage is "true".

default : false 
useMail boolean 

Indicates whether to use group emails.

  • Available only for the Advanced plan.
  • If this parameter is "true", groupEmail is required.

default : false 
groupEmail string 

Group email address (if useMail is "true").

  • The format is localpart@domain.
  • The localpart must start with a lowercase English letter, a number, an exclamation mark (!), or a number sign (#).
  • The localpart cannot start or end with a dot (.), and cannot contain two or more consecutive dots.
  • The localpart can be between 2 and 64 characters long and can only contain lowercase English letters, numbers, dot (.), hyphen (-), underscore (_), exclamation mark (!), and number sign (#).

minItems : 0
maxLength : 90 
aliasEmails array (string) 

Group email alias (if useMail is "true").

  • Each email address can be up to 90 characters long.
  • The format is localpart@domain.
  • The localpart must start with a lowercase English letter, a number, an exclamation mark (!), or a number sign (#).
  • The localpart cannot start or end with a dot (.), and cannot contain two or more consecutive dots.
  • The localpart can be between 2 and 64 characters long and can only contain lowercase English letters, numbers, dot (.), hyphen (-), underscore (_), exclamation mark (!), and number sign (#).

minItems : 0
maxItems : 20 
canReceiveExternalMail boolean 

Indicates whether to receive external emails (if useMail is "true").


default : false 
toExternalEmails array (string) 

External email addresses to receive group emails.
Email addresses with your company domain are not allowed.


minItems : 0
maxItems : 500 
membersAllowedToUseGroupEmailAsRecipient array (GroupAllowedMember) 

Members who can send an email to the group email address (if useMail is "true").
Only the group emails sent from the specified members are allowed.


minItems : 0 
membersAllowedToUseGroupEmailAsSender array (GroupAllowedMember) 

Members who can use the group email address as their From address (if useMail is "true").
Only the group masters or members are allowed. (Those who are not the members or administrators of the group will be excluded from the list).


minItems : 0 
dynamicMembership object (dynamicMembership) 

Dynamic membership

 

GroupAdministrator

PropertyTypeDescription
userId string 

Member ID
- Email address
- Resource ID
- External key in "externalKey:{externalKey}" format


required 

GroupMember

PropertyTypeDescription
id string 

Member, team, or group ID.
The following types are available for a member ID:
- Email address
- Resource ID
- External key in "externalKey:{externalKey}" format


required 
type string 

required
Allowed values : USER, ORGUNIT, GROUP 

GroupAllowedMember

PropertyTypeDescription
userId string 

Member ID
- Email address
- Resource ID
- External key in "externalKey:{externalKey}" format


required 

dynamicMembership

PropertyTypeDescription
query string 

Membership query.
For how to create a query, see Overview.


maxLength : 10000 
excludeUserIds array (string) 

List of member IDs to exclude from the group. The following types are available:

  • Mail
  • Resource ID
  • External key in "externalKey:{externalKey}" format

minItems : 0 

Request Example

example

1{2  "domainId": 10000001,3  "groupName": "Group1",4  "description": "Domain group",5  "visible": true,6  "useServiceNotification": true,7  "serviceManageable": true,8  "groupExternalKey": "GROUP_EXT_01",9  "administrators": [10    {11      "userId": "userf7da-f82c-4284-13e7-030f3b4c756x"12    }13  ],14  "members": [15    {16      "id": "userf7da-f82c-4284-13e7-030f3b4c756x",17      "type": "USER"18    },19    {20      "id": "orgunitf-f27f-4af8-27e1-03817a911417",21      "type": "ORGUNIT"22    },23    {24      "id": "group769-e656-477d-69c7-04e2f73a4a77",25      "type": "GROUP"26    }27  ],28  "useMessage": true,29  "useNote": true,30  "useCalendar": true,31  "useFolder": true,32  "useTask": true,33  "useMail": true,34  "groupEmail": "email@example.com",35  "aliasEmails": [36    "alias@example.com"37  ],38  "canReceiveExternalMail": true,39  "toExternalEmails": [40    "external@example.com"41  ],42  "membersAllowedToUseGroupEmailAsRecipient": [43    {44      "userId": "userf7da-f82c-4284-13e7-030f3b4c756x"45    }46  ],47  "membersAllowedToUseGroupEmailAsSender": [48    {49      "userId": "userf7da-f82c-4284-13e7-030f3b4c756x"50    }51  ],52  "dynamicMembership": {53    "query": "user.levelId == levelaa7-b824-4937-66af-042f1f43cefa",54    "excludeUserIds": [55      "userf7da-f82c-4284-13e7-030f3b4c756x"56    ]57  }58}

Response

HTTP 200

OK

PropertyTypeDescription
domainId integer 

Domain ID


required
format : int32 
groupId string 

It is automatically assigned.


readOnly : true 
groupName string 

Group name. It must be unique within the domain.


required
maxLength : 100 
description string 

Group description


maxLength : 300
nullable : true 
visible boolean 

Indicates whether to make the group visible. It indicates whether to make the group visible in search results for users who are not managers or members.


default : true 
useServiceNotification boolean 

Indicates whether to send service notifications.


default : false 
serviceManageable boolean 

Indicates whether a group master can change whether to use the service.


default : true 
groupExternalKey string 

Group external key


maxLength : 100
nullable : true 
administrators array (GroupAdministrator) 

List of group masters


required
minItems : 1 
members array (GroupMember) 

List of group members


required 
useMessage boolean 

Indicates whether to use the Message Room features.

  • If it is set to "false", the chat history of all the members is deleted and the Message Room features (Note, Calendar, Folder, and Task) are disabled after 30 days.
  • Set this parameter to "true" again within 30 days to recover the previous data. Setting it to "true" after 30 days cannot recover the previous data; it only creates a new message room.

default : false 
useNote boolean 

Indicates whether to use the Message Room Note feature.

  • If it is set to "false", the feature is disabled. To view the previous data, set this parameter to "true".
  • This parameter is available only if useMessage is "true".

default : false 
useCalendar boolean 

Indicates whether to use the Message Room Calendar feature.

  • If it is set to "false", the feature is disabled. To view the previous data, set this parameter to "true".
  • This parameter is available only if useMessage is "true".

default : false 
useTask boolean 

Indicates whether to use the Message Room Task feature.

  • If it is set to "false", the feature is disabled. To view the previous data, set this parameter to "true".
  • This parameter is available only if useMessage is "true".

default : false 
useFolder boolean 

Indicates whether to use the Message Room Folder feature.

  • If it is set to "false", the feature is disabled. To view the previous data, set this parameter to "true".
  • This parameter is available only if useMessage is "true".

default : false 
useMail boolean 

Indicates whether to use group emails.

  • Available only for the Advanced plan.
  • If this parameter is "true", groupEmail is required.

default : false 
groupEmail string 

Group email address (if useMail is "true").

  • The format is localpart@domain.
  • The localpart must start with a lowercase English letter, a number, an exclamation mark (!), or a number sign (#).
  • The localpart cannot start or end with a dot (.), and cannot contain two or more consecutive dots.
  • The localpart can be between 2 and 64 characters long and can only contain lowercase English letters, numbers, dot (.), hyphen (-), underscore (_), exclamation mark (!), and number sign (#).

minItems : 0
maxLength : 90 
aliasEmails array (string) 

Group email alias (if useMail is "true").

  • Each email address can be up to 90 characters long.
  • The format is localpart@domain.
  • The localpart must start with a lowercase English letter, a number, an exclamation mark (!), or a number sign (#).
  • The localpart cannot start or end with a dot (.), and cannot contain two or more consecutive dots.
  • The localpart can be between 2 and 64 characters long and can only contain lowercase English letters, numbers, dot (.), hyphen (-), underscore (_), exclamation mark (!), and number sign (#).

minItems : 0
maxItems : 20 
canReceiveExternalMail boolean 

Indicates whether to receive external emails (if useMail is "true").


default : false 
toExternalEmails array (string) 

External email addresses to receive group emails.
Email addresses with your company domain are not allowed.


minItems : 0
maxItems : 500 
membersAllowedToUseGroupEmailAsRecipient array (GroupAllowedMember) 

Members who can send an email to the group email address (if useMail is "true").
Only the group emails sent from the specified members are allowed.


minItems : 0 
membersAllowedToUseGroupEmailAsSender array (GroupAllowedMember) 

Members who can use the group email address as their From address (if useMail is "true").
Only the group masters or members are allowed. (Those who are not the members or administrators of the group will be excluded from the list).


minItems : 0 
useDynamicMembership boolean 

Indicates whether to enable dynamic membership.

  • If it is set to "true", group members are automatically added or removed based on query conditions.
  • If dynamic membership is enabled, the specified members field is ignored because group members are automatically added or deleted.

default : false 
dynamicMembership object (dynamicMembership) 

Dynamic membership

 

GroupAdministrator

PropertyTypeDescription
userExternalKey string 

Member external key


readOnly : true 
userId string 

Member ID
- Email address
- Resource ID
- External key in "externalKey:{externalKey}" format


required 

GroupMember

PropertyTypeDescription
externalKey string 

Member external key


readOnly : true 
id string 

Member, team, or group ID.
The following types are available for a member ID:
- Email address
- Resource ID
- External key in "externalKey:{externalKey}" format


required 
type string 

required
Allowed values : USER, ORGUNIT, GROUP 

GroupAllowedMember

PropertyTypeDescription
userExternalKey string 

Member external key


readOnly : true 
userId string 

Member ID
- Email address
- Resource ID
- External key in "externalKey:{externalKey}" format


required 

dynamicMembership

PropertyTypeDescription
query string 

Membership query.
For how to create a query, see Overview.


maxLength : 10000 
excludeUserIds array (string) 

List of member IDs to exclude from the group. The following types are available:

  • Mail
  • Resource ID
  • External key in "externalKey:{externalKey}" format

minItems : 0 

Response Example

example

1{2  "domainId": 10000001,3  "groupId": "group127-8545-4463-603b-04d550d23bf",4  "groupName": "Group1",5  "description": "Domain group",6  "visible": true,7  "useServiceNotification": true,8  "serviceManageable": true,9  "groupExternalKey": "GROUP_EXT_01",10  "administrators": [11    {12      "userExternalKey": "USER_EXT_01",13      "userId": "userf7da-f82c-4284-13e7-030f3b4c756x"14    }15  ],16  "members": [17    {18      "externalKey": "USER_EXT_01",19      "id": "userf7da-f82c-4284-13e7-030f3b4c756x",20      "type": "USER"21    },22    {23      "externalKey": "ORGUNIT_EXT_01",24      "id": "orgunitf-f27f-4af8-27e1-03817a911417",25      "type": "ORGUNIT"26    },27    {28      "externalKey": "GROUP_EXT_01",29      "id": "group769-e656-477d-69c7-04e2f73a4a77",30      "type": "GROUP"31    }32  ],33  "useMessage": true,34  "useNote": true,35  "useCalendar": true,36  "useFolder": true,37  "useTask": true,38  "useMail": true,39  "groupEmail": "email@example.com",40  "aliasEmails": [41    "alias@example.com"42  ],43  "canReceiveExternalMail": true,44  "toExternalEmails": [45    "external@example.com"46  ],47  "membersAllowedToUseGroupEmailAsRecipient": [48    {49      "userExternalKey": "USER_EXT_01",50      "userId": "userf7da-f82c-4284-13e7-030f3b4c756x"51    }52  ],53  "membersAllowedToUseGroupEmailAsSender": [54    {55      "userExternalKey": "USER_EXT_01",56      "userId": "userf7da-f82c-4284-13e7-030f3b4c756x"57    }58  ],59  "useDynamicMembership": true,60  "dynamicMembership": {61    "query": "user.levelId == levelaa7-b824-4937-66af-042f1f43cefa",62    "excludeUserIds": [63      "userf7da-f82c-4284-13e7-030f3b4c756x"64    ]65  }66}

HTTP 400

Bad Request

HTTP 403

Forbidden

HTTP 409

Conflict