POST/orgunits

Adds a team.

Caution

  • The following API operations must be called once per second in a single thread, in the order they are listed, for each domain: Add a team, Update a team, Update part of a team, and Move a team.

Authorization

oauth2

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

Scope

directory
orgunit

HTTP Request

POSThttps://www.worksapis.com/v1.0/orgunits

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 
orgUnitExternalKey string 

Customer's external key

Some special characters, %, \, #, /, ? are not allowed.


maxLength : 100
nullable : true 
orgUnitName string 

Team name. The allowed special characters are ! @ & ( ) - _ + [ ] { } , . /.


required
maxLength : 100 
i18nNames array (OrgUniti18nName) 

List of multilingual names

 
email string 

Team email address (localpart@domain or localpart@group). It is required to update a team.

  • The entire email address can be up to 90 characters long.
  • 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 (#).

maxLength : 90 
description string 

Team description


maxLength : 160
nullable : true 
visible boolean 

Indicates whether to make the team visible.
Only "false" is allowed if the parent team is private.


default : true 
parentOrgUnitId string 

Parent team ID

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

nullable : true 
displayOrder integer 

Ordering between the teams that share the same parent team.


required
minimum : 1
format : int32 
aliasEmails array (string) 

List of email aliases

  • Available only for the Advanced plan.

minItems : 0
maxItems : 20 
canReceiveExternalMail boolean 

Indicates whether to receive external emails.


default : false 
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 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 when 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 when 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 when 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 when useMessage is "true".

default : false 
useServiceNotification boolean 

Indicates whether to use service notifications.


default : false 
membersAllowedToUseOrgUnitEmailAsRecipient array (OrgUnitAllowedMember) 

List of members who can send an email to the team email address.


minItems : 0 

OrgUniti18nName

PropertyTypeDescription
language string 

Language


required
Allowed values : ko_KR, ja_JP, en_US, zh_CN, zh_TW 
name string 

Multilingual name The allowed special characters are ! @ & ( ) - _ + [ ] { } , . /.


required
maxLength : 100 

OrgUnitAllowedMember

PropertyTypeDescription
userId string 

Member ID


required 

Request Example

example

1{2  "domainId": 10000001,3  "orgUnitExternalKey": "externalKeyValue",4  "orgUnitName": "name01",5  "i18nNames": [6    {7      "language": "en_US",8      "name": "Team01"9    }10  ],11  "email": "team01@example.com",12  "description": "desc",13  "visible": true,14  "parentOrgUnitId": "parernt9-ffda-4395-24a8-03fb9e22e051",15  "displayOrder": 1,16  "aliasEmails": [17    "alias@example.com"18  ],19  "canReceiveExternalMail": true,20  "useMessage": true,21  "useNote": true,22  "useCalendar": true,23  "useTask": true,24  "useFolder": true,25  "useServiceNotification": true,26  "membersAllowedToUseOrgUnitEmailAsRecipient": [27    {28      "userId": "e7b4f7da-f82c-4284-13e7-030f3b4c7569"29    }30  ],31  "displayLevel": 132}

Response

HTTP 201

OK

PropertyTypeDescription
domainId integer 

Domain ID


required
format : int32 
orgUnitId string 

Resource ID


readOnly : true 
orgUnitExternalKey string 

Customer's external key

Some special characters, %, \, #, /, ? are not allowed.


maxLength : 100
nullable : true 
orgUnitName string 

Team name. The allowed special characters are ! @ & ( ) - _ + [ ] { } , . /.


required
maxLength : 100 
i18nNames array (OrgUniti18nName) 

List of multilingual names

 
email string 

Team email address (localpart@domain or localpart@group). It is required to update a team.

  • The entire email address can be up to 90 characters long.
  • 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 (#).

maxLength : 90 
description string 

Team description


maxLength : 160
nullable : true 
visible boolean 

Indicates whether to make the team visible.


default : true 
parentOrgUnitId string 

Parent team ID

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

nullable : true 
parentExternalKey string 

Parent team external key


readOnly : true
nullable : true 
displayOrder integer 

Ordering between the teams that share the same parent team. It is required only when a team is added. It is ignored when a team is updated.


minimum : 1
format : int32 
displayLevel integer 

Team depth (starting from 1)


minimum : 1
format : int32
readOnly : true 
aliasEmails array (string) 

List of email aliases.

  • Available only for the Advanced plan.

minItems : 0
maxItems : 20 
canReceiveExternalMail boolean 

Indicates whether to receive external emails.


default : false 
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 when 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 when 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 when 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 when useMessage is "true".

default : false 
useServiceNotification boolean 

Indicates whether to use service notifications.


default : false 
membersAllowedToUseOrgUnitEmailAsRecipient array (OrgUnitAllowedMember) 

List of members who can send an email to the team email address.


minItems : 0 
membersAllowedToUseOrgUnitEmailAsSender array (OrgUnitAllowedMember) 

List of members who can use the team email address as their From address. Only team members are allowed.


minItems : 0 

OrgUniti18nName

PropertyTypeDescription
language string 

Language


required
Allowed values : ko_KR, ja_JP, en_US, zh_CN, zh_TW 
name string 

Multilingual name The allowed special characters are ! @ & ( ) - _ + [ ] { } , . /.


required
maxLength : 100 

OrgUnitAllowedMember

PropertyTypeDescription
userId string 

Member ID


required 
userExternalKey string 

Customer's external key


readOnly : true
nullable : true 

Response Example

example

1{2  "domainId": 10000001,3  "orgUnitId": "orgunitf-f27f-4af8-27e1-03817a911417",4  "orgUnitExternalKey": "externalKeyValue",5  "orgUnitName": "name01",6  "i18nNames": [7    {8      "language": "en_US",9      "name": "Team01"10    }11  ],12  "email": "team01@example.com",13  "description": "desc",14  "visible": true,15  "parentOrgUnitId": "parernt9-ffda-4395-24a8-03fb9e22e051",16  "parentExternalKey": "parentExtKeyValue",17  "displayOrder": 1,18  "displayLevel": 1,19  "aliasEmails": [20    "alias@example.com"21  ],22  "canReceiveExternalMail": true,23  "useMessage": true,24  "useNote": true,25  "useCalendar": true,26  "useTask": true,27  "useFolder": true,28  "useServiceNotification": true,29  "membersAllowedToUseOrgUnitEmailAsRecipient": [30    {31      "userId": "e7b4f7da-f82c-4284-13e7-030f3b4c7569",32      "userExternalKey": null33    }34  ],35  "membersAllowedToUseOrgUnitEmailAsSender": [36    {37      "userId": "e7b4f7da-f82c-4284-13e7-030f3b4c7569",38      "userExternalKey": null39    }40  ]41}

HTTP 400

Bad Request