Update a department

Call this API to update the information of a department.

Request

Basic information
HTTP URL	https://api.dingtalk.io/topapi/v2/department/update
HTTP Method	POST
Supported app type	appType-Internal app
Required permissions	permission-qyapi_manage_addresslist-Contacts data management permission

Query parameters

Name	Type	Required	Example	Description
access_token	String	Yes	bE74xxxx	The app credential used to call this API. Obtain it through the API for getting the access_token of an internal app.

Request body

Name	Type	Required	Example	Description
dept_id	Number	Yes	100	The department ID. You can call the Get department list API to obtain the value of dept_id.
parent_id	Number	No	2	The parent department ID. The root department ID is 1. You can call the Get department list API to obtain the value of parent_id.
hide_dept	Boolean	No	true	Whether to hide this department: - true: hide the department. After being hidden, the department will not appear in the company contacts. - false: show the department. If no value is passed, the current setting remains unchanged.
dept_permits	String	No	123,456	The list of other departments that are allowed to view this department. This value takes effect when hide_dept is set to true. Note The total count of this list plus the user_permits list cannot exceed 50.
user_permits	String	No	user123,manager222	The list of user IDs that are allowed to view this department. This value takes effect when hide_dept is set to true. Note The total count of this list plus the dept_permits list cannot exceed 50.
create_dept_group	Boolean	No	true	Whether to create an organization chat associated with this department. The default value is false, meaning that no chat is created. If no value is passed, the current setting remains unchanged.
order	Number	No	10	The sort value within the parent department. A smaller order value ranks higher.
name	String	No	HR	The department name. The length must be 1 to 64 characters. The characters ’-’, ’，’, and ’,’ are not allowed.
source_identifier	String	No	HR Department	The department identifier field. Developers can use this field to uniquely identify a department and map it to a department in external DingTalk contacts. Note This field is not visible in the department information in the organization management console.
outer_dept	Boolean	No	true	Whether to restrict members of this department from viewing the contacts: - true: enable the restriction. Once enabled, members of this department can only view contacts within the specified scope. - false: no restriction. If no value is passed, the current setting remains unchanged.
outer_permit_users	String	No	user123,manager123	The list of user IDs in the contacts that members of this department are allowed to view. This parameter takes effect when outer_dept is set to true. Note The total count of this list plus the outer_permit_depts list cannot exceed 50.
outer_permit_depts	String	No	123,456	The list of department IDs in the contacts that members of this department are allowed to view. This parameter takes effect when outer_dept is set to true. Note The total count of this list plus the outer_permit_users list cannot exceed 50.
outer_dept_only_self	Boolean	No	true	Whether members of this department can only view the contacts of their own department and sub-departments: - true: can only view the contacts of their own department and sub-departments. - false: cannot view all contacts, and can only see themselves in the contacts. This parameter takes effect when outer_dept is set to true. If no value is passed, the current setting remains unchanged.
language	String	No	zh_CN	The contacts language: - zh_CN: Chinese. - en_US: English.
auto_add_user	Boolean	No	false	After the department chat has been created, whether new members joining the department are automatically added to the chat: - true: automatically join the chat. - false: do not automatically join the chat. If no value is passed, the current setting remains unchanged.
auto_approve_apply	Boolean	No	false	Whether to automatically approve requests to join this department: - true: requests to join this department are approved automatically. - false: requests to join this department must be approved by an admin with the relevant permissions.
dept_manager_userid_list	String	No	manager220	The list of user IDs of the department managers. Separate multiple user IDs with commas. Note Department managers must be members of the current department. Otherwise, the API returns the error userId does not exist.
group_contain_sub_dept	Boolean	No	true	Whether the department chat includes sub-departments: - true: include. - false: do not include. If no value is passed, the current setting remains unchanged.
group_contain_outer_dept	Boolean	No	true	Whether the department chat includes outsourced departments: - true: include. - false: do not include. If no value is passed, the current setting remains unchanged. Note An outsourced department can only see its own department, and cannot see other departments or other people.
group_contain_hidden_dept	Boolean	No	true	Whether the department chat includes hidden departments: - true: include. - false: do not include. If no value is passed, the current setting remains unchanged.
org_dept_owner	String	No	100	The user ID of the organization chat owner. Note The group owner must be a member of the current department.
force_update_fields	String	No	dept_manager_userid_list	The fields to be force-updated. This supports clearing specified fields. Separate multiple fields with commas. The currently supported field is: `dept_manager_userid_list`.
code	String	No	10000	The department code. The maximum length is 30 characters. Note This field can only be set through this API.

Request example

curl -X POST "https://api.dingtalk.io/topapi/v2/department/update" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=c6391xxxxb574' \
-d 'dept_id=100' \
-d 'parent_id=2' \
-d 'hide_dept=true' \
-d 'user_permits=100%2C200'
-d 'dept_permits=3%2C4%2C5' \
-d 'language=zh_CN' \
-d 'code=10000'

Java

DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/v2/department/update");
OapiV2DepartmentUpdateRequest req = new OapiV2DepartmentUpdateRequest();
req.setDeptId(100L);
req.setParentId(2L);
req.setOuterDept(true);
req.setHideDept(true);
req.setCreateDeptGroup(true);
req.setOrder(10L);
req.setName("HR");
req.setSourceIdentifier("HR Department");
req.setDeptPermits("123,456");
req.setUserPermits("user123,manager222");
req.setOuterPermitUsers("user100,user200");
req.setOuterPermitDepts("123,456");
req.setOuterDeptOnlySelf(true);
req.setLanguage("zh_CN");
req.setAutoAddUser(false);
req.setDeptManagerUseridList("manager200");
req.setGroupContainSubDept(true);
req.setGroupContainOuterDept(true);
req.setGroupContainHiddenDept(true);
req.setOrgDeptOwner("100");
OapiV2DepartmentUpdateResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());

Python

import dingtalk.api

req=dingtalk.api.OapiV2DepartmentUpdateRequest("https://api.dingtalk.io/topapi/v2/department/update")

req.dept_id=100
req.parent_id=2
req.hide_dept=true
req.user_permits="100,200"
req.dept_permits="3,4,5"
req.language="zh_CN"
req.code="10000"
try:
  resp= req.getResponse(access_token)
  print(resp)
except Exception,e:
  print(e)

PHP

include "TopSdk.php";
date_default_timezone_set('Asia/Shanghai');

$c = new DingTalkClient(DingTalkConstant::$CALL_TYPE_OAPI, DingTalkConstant::$METHOD_POST , DingTalkConstant::$FORMAT_JSON);
$req = new OapiV2DepartmentUpdateRequest;
$req->setDeptId("100");
$req->setParentId("2");
$req->setHideDept("true");
$req->setDeptPermits("3,4,5");
$req->setUserPermits("100,200");
$req->setLanguage("zh_CN");
$req->setCode("10000");

IDingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/v2/department/update");
OapiV2DepartmentUpdateRequest req = new OapiV2DepartmentUpdateRequest();
req.DeptId = 100L;
req.ParentId = 2L;
req.HideDept = true;
req.DeptPermits = "3,4,5";
req.UserPermits = "100,200";
req.Language = "zh_CN";
req.Code = "10000";
OapiV2DepartmentUpdateResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

Response

Response body

Name	Type	Example	Description
errcode	Number	0	The return code.
errmsg	String	ok	The description of the return code.
request_id	String	6iq4zcul5zjp	The request ID.

Response body example

{
 "errcode":0,
 "errmsg":"ok",
 "request_id": "6iq4zcul5zjp"
}

Error codes

If an error is returned when you call this API, refer to the Global error codes documentation to find a solution based on the error message.

Error code (errcode)	Error message (errmsg)	Solution
43007	Insufficient permissions	Confirm whether the access_token has the required permissions for this operation.
40009	Invalid department ID	Confirm whether the dept_id is correct.
60018	The root department cannot be updated	Use a different dept_id.
60003	The department was not found	Confirm whether the dept_id is correct.
60001	Invalid department name	Confirm whether the department name is correct.
40011	Invalid order	Confirm whether the order value is valid.
60004	The parent department does not exist	Confirm whether the parent_id is correct.
60010	A loop exists in the department IDs	Reset the department ID.
60109	Invalid viewable ID list	Verify whether the viewable list is valid.
40031	Invalid userId list	Confirm whether the userId is correct.
40093	Invalid organization chat owner	Confirm whether the user ID of the organization chat owner is correct.
60510	Failed to set department permissions	Verify whether the parameters are valid.
-1	System busy	Try again later.

API calling guide

Authentication & authorization

Contacts

Calendar

Conferencing

AI Table

Docs & files

IM

Request

Query parameters

Request body

Request example

Response

Response body

Response body example

Error codes

​Request

​Query parameters

​Request body

​Request example

​Response

​Response body

​Response body example

​Error codes

Request

Query parameters

Request body

Request example

Response

Response body

Response body example

Error codes