Create a department - DingTalk Help Center

Call this API to create a new department.

Request

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

Query parameter

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
name	String	Yes	Development Department	The department name. The length must be 1 to 64 characters. The characters ”-” and ”,” are not allowed.
parent_id	Number	Yes	10	The parent department ID. The root department ID is 1.
hide_dept	Boolean	No	true	Whether to hide this department: - true: Hide the department. After hiding, this department is not displayed in the company contacts. - false (Default): Display the department.
dept_permits	String	No	”123,456”	The list of other departments that are allowed to view this department. The total number cannot exceed 50. This value takes effect when hide_dept is set to true.
user_permits	String	No	”user123,manager222”	The list of userIds of users that are allowed to view this department. The total number cannot exceed 50. This value takes effect when hide_dept is set to true.
outer_dept	Boolean	No	true	Whether to restrict members of this department from viewing the contacts: - true: Enable the restriction. After enabling, members of this department can only see contacts within the specified scope. - false (Default): No restriction.
outer_dept_only_self	Boolean	No	false	Whether members of this department can only view the contacts of their own department and subordinate departments: - true: Can only view the contacts of their own department and subordinate departments. - false: Cannot view any contacts, and can only see themselves in the contacts. This parameter takes effect when outer_dept is set to true.
outer_permit_users	String	No	”manager123,user123”	The list of userIds of contact users that members of this department are allowed to view. The total number cannot exceed 50. This parameter takes effect when outer_dept is set to true.
outer_permit_depts	String	No	”456,123”	The list of contact department IDs that members of this department are allowed to view. The total number cannot exceed 50. This parameter takes effect when outer_dept is set to true.
create_dept_group	Boolean	No	true	Whether to create an enterprise group associated with this department. The default value is false, meaning no group is created.
auto_approve_apply	Boolean	No	false	Whether to accept requests to join this department by default: - true: Requests to join this department are accepted by default. - false: Requests to join this department must be approved by an admin with the required permissions.
order	Number	No	10	The sort value within the parent department. A smaller order value places the department higher in the sort order.
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 an external contact list outside DingTalk.

Request example

curl -X POST "https://oapi.dingtalk.io/topapi/v2/department/create" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=d5ca5xxxxa8' \
-d 'parent_id=10' \
-d 'outer_dept=true' \
-d 'hide_dept=true' \
-d 'create_dept_group=true' \
-d 'order=10' \
-d 'name=HR' \
-d 'source_identifier=HR%20Department' \
-d 'dept_permits=3%2C4%2C5' \
-d 'user_permits=100%2C200' \
-d 'outer_permit_users=500%2C600' \
-d 'outer_permit_depts=6%2C7%2C8' \
-d 'outer_dept_only_self=true'

Java

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/v2/department/create");
OapiV2DepartmentCreateRequest req = new OapiV2DepartmentCreateRequest();
req.setParentId(10L);
req.setOuterDept(true);
req.setHideDept(true);
req.setCreateDeptGroup(true);
req.setOrder(10L);
req.setName("HR");
req.setSourceIdentifier("HR Department");
req.setDeptPermits("3,4,5");
req.setUserPermits("100,200");
req.setOuterPermitUsers("500,600");
req.setOuterPermitDepts("6,7,8");
req.setOuterDeptOnlySelf(true);
OapiV2DepartmentCreateResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());

Python

# -*- coding: utf-8 -*-
import dingtalk.api

req=dingtalk.api.OapiV2DepartmentCreateRequest("https://oapi.dingtalk.io/topapi/v2/department/create")

req.parent_id=10
req.outer_dept=true
req.hide_dept=true
req.create_dept_group=true
req.order=10
req.name="HR"
req.source_identifier="HR Department"
req.dept_permits="3,4,5"
req.user_permits="100,200"
req.outer_permit_users="500,600"
req.outer_permit_depts="6,7,8"
req.outer_dept_only_self=true
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 OapiV2DepartmentCreateRequest;
$req->setName("HR");
$req->setParentId("10");
$req->setHideDept("true");
$req->setDeptPermits("3,4,5");
$req->setUserPermits("100,200");
$req->setOuterPermitUsers("500,600");
$req->setOuterPermitDepts("6,7,8");
$req->setOuterDeptOnlySelf("true");
$req->setOuterDept("true");
$req->setCreateDeptGroup("true");
$req->setOrder("10");
$req->setSourceIdentifier("HR Department");
$resp = $c->execute($req, $access_token, "https://oapi.dingtalk.io/topapi/v2/department/create");

IDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/v2/department/create");
OapiV2DepartmentCreateRequest req = new OapiV2DepartmentCreateRequest();
req.ParentId = 10L;
req.OuterDept = true;
req.HideDept = true;
req.CreateDeptGroup = true;
req.Order = 10L;
req.Name = "HR";
req.SourceIdentifier = "HR Department";
req.DeptPermits = "3,4,5";
req.UserPermits = "100,200";
req.OuterPermitUsers = "500,600";
req.OuterPermitDepts = "6,7,8";
req.OuterDeptOnlySelf = true;
OapiV2DepartmentCreateResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

Response

Response body

Name	Type	Example	Description
request_id	String	6iq4zcul5zjp	The request ID.
errcode	Number	0	The return code.
errmsg	String	ok	The description of the return code.
result	DeptCreateResponse		The call result.
dept_id	Number	100	The department ID.

Response body example

{
  "errcode": 0,
  "errmsg":"ok",
  "result": {
    "dept_id": 41xxxx76
  },
  "request_id": "6iq4zcul5zjp"
}

Error codes

If an error occurs when you call this API, look up the solution in the Global error codes document based on the error message.

Error code (errcode)	Error message (errmsg)	Solution
40035	Invalid parameter	Make sure the parameters are filled in as required by the document above.
43007	Authorization required	Make sure the access_token has the permissions required for this action.
60004	Parent department does not exist	Check whether parent_id is correct.
600109	Invalid visible ID list	Check whether the visible list meets the requirements.
-1	System busy	Try again later.

​Request

​Query parameter

​Request body

​Request example

​Response

​Response body

​Response body example

​Error codes

Request

Query parameter

Request body

Request example

Response

Response body

Response body example

Error codes