Developer GuideRequest
| Basic information | |
|---|---|
| HTTP URL | https://api.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://api.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'
DingTalkClient client = new DefaultDingTalkClient("https://api.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());
# -*- coding: utf-8 -*-
import dingtalk.api
req=dingtalk.api.OapiV2DepartmentCreateRequest("https://api.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)
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://api.dingtalk.io/topapi/v2/department/create");
IDingTalkClient client = new DefaultDingTalkClient("https://api.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. |