Get department details - DingTalk Help Center

Call this API to get the details of a specified department by its department ID.

Request

Basic information
HTTP URL	https://oapi.dingtalk.io/topapi/v2/department/get
HTTP Method	POST
Supported app types	appType-Internal app, appType-Third-party enterprise app
Permission required	permission-qyapi_get_department_list-Read permission for Contacts department information

Query parameters

Name	Type	Required	Example	Description
access_token	String	Yes	bE74xxxx	The app credential used to call this API. - For an internal app, obtain it by calling the API to get the access_token of an internal app. - For a third-party enterprise app, obtain it by calling the API to get the access_token of a third-party enterprise.

Request body

Name	Type	Required	Example	Description
dept_id	Number	Yes	100	The department ID. The root department ID is 1. Call the Get department list API to obtain the value of dept_id.
language	String	No	zh_CN	The Contacts language: - zh_CN (default): Chinese - en_US: English

Request example

curl -X POST "https://oapi.dingtalk.io/topapi/v2/department/get" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=d3daxxxx51990' \
-d 'dept_id=100' \
-d 'language=zh_CN'

Java

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/v2/department/get");
OapiV2DepartmentGetRequest req = new OapiV2DepartmentGetRequest();
req.setDeptId(100L);
req.setLanguage("zh_CN");
OapiV2DepartmentGetResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());

Python

import dingtalk.api

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

req.dept_id=100
req.language="zh_CN"
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 OapiV2DepartmentGetRequest;
$req->setDeptId("100");
$req->setLanguage("zh_CN");
$resp = $c->execute($req, $access_token, "https://oapi.dingtalk.io/topapi/v2/department/get");

IDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/v2/department/get");
OapiV2DepartmentGetRequest req = new OapiV2DepartmentGetRequest();
req.DeptId = 100L;
req.Language = "zh_CN";
OapiV2DepartmentGetResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

Response

Response body

Name	Type	Example	Description
request_id	String	4e7ljtq91rgo	The request ID.
errcode	Number	0	The return code.
errmsg	String	ok	The error message.
result	DeptGetResponse		The department details.
dept_id	Number	100	The department ID.
name	String	HR	The department name.
parent_id	Number	50	The parent department ID. The root department ID is 1.
source_identifier	String	HR	The department identifier field. Note This parameter is not returned for third-party enterprise apps.
create_dept_group	Boolean	true	Whether to synchronously create an enterprise chat associated with this department: - true: Create - false: Do not create
auto_add_user	Boolean	false	Whether new users joining the department are automatically added to the department chat after the chat is created: - true: Automatically join the chat - false: Do not automatically join the chat
tags	String	campus	The education department tag: - campus: Campus - period: Period - grade: Grade - class: Class Note This parameter is not returned for third-party enterprise apps.
from_union_org	Boolean	false	Whether the department comes from an associated organization: - true: Yes - false: No Note This parameter is not returned for third-party enterprise apps.
order	Number	10	The order value within the parent department.
dept_group_chat_id	String	123	The department chat ID.
group_contain_sub_dept	Boolean	true	Whether the department chat includes sub-departments: - true: Included - false: Not included
org_dept_owner	String	80	The user ID of the enterprise chat group owner.
dept_manager_userid_list	String[]	[“5”,“6”,“7”,“8”]	The list of department manager user IDs.
outer_dept	Boolean	true	Whether to restrict members of this department from viewing the Contacts: - true: Restriction enabled. After enabling, members of this department can only see the Contacts of specified departments/users. - false: No restriction
outer_permit_depts	Number[]	[500,600]	The list of department IDs visible to department employees. Note When the organization restricts members of this department from viewing the Contacts, the outer_dept value is returned. - Restriction enabled on members of this department viewing the Contacts (that is, outer_dept is true): outer_permit_depts indicates the list of department IDs of the specified departments/users that members can see. Note For example, the organization restricts members of this department from viewing the Contacts, and members of this department are set to only see the Contacts of 2 specified departments and 2 specified employees. The department ID of Test Department 1 is 1 and the department ID of Test Department 2 is 2. When calling this API, the obtained value of outer_permit_depts is [1,2]. The employee list is not returned, that is, the information of Employee Xiaoding 1 and Employee Xiaoding 2 is not returned. - Restriction not enabled on members of this department viewing the Contacts (that is, outer_dept is false): The outer_permit_depts field is not returned.
outer_permit_users	String[]	[“78”,“79”]	The list of employee user IDs visible to department employees. Note When the organization restricts members of this department from viewing the Contacts, the outer_dept value is returned. - Restriction enabled on members of this department viewing the Contacts (that is, outer_dept is true): outer_permit_users indicates the list of employee user IDs of the specified departments/users that members can see. Note For example, the organization restricts members of this department from viewing the Contacts, and members of this department are set to only see the Contacts of 2 specified departments and 2 specified employees. The user ID of Employee Xiaoding 1 is 001 and the user ID of Employee Xiaoding 2 is 002. When calling this API, the obtained value of outer_permit_users is [“001”,“002”]. The department list is not returned, that is, the information of Test Department 1 and Test Department 2 is not returned. - Restriction not enabled on members of this department viewing the Contacts (that is, outer_dept is false): The outer_permit_users field is not returned.
user_permits	String[]	[“5”,“9”]	The list of employee user IDs for the hidden department. Note When the organization enables hiding this department, the hide_dept value is returned. - Hide this department enabled (that is, hide_dept is true): user_permits indicates the list of employee user IDs that are allowed to be visible to specified departments/users. Note For example, the organization enables hiding this department and sets 2 departments and 2 employees to be visible to specified departments/users. The user ID of Employee Xiaoding 1 is 001 and the user ID of Employee Xiaoding 2 is 002. When calling this API, the obtained value of user_permits is [“001”,“002”]. The department list is not returned, that is, the information of Test Department 1 and Test Department 2 is not returned. - Hide this department not enabled (that is, hide_dept is false): The user_permits field is not returned.
hide_dept	Boolean	false	Whether to enable hiding this department: - true: Hide this department enabled. You can set the hiding scope, such as hiding from all users and departments, or allowing visibility to specified departments/users. - false: Hide this department disabled. That is, the department is displayed in the company Contacts.
dept_permits	Number[]	[3,4,5]	The list of department IDs for the hidden department. Note When the organization enables hiding this department, the hide_dept value is returned. - Hide this department enabled (that is, hide_dept is true): dept_permits indicates the list of department IDs that are allowed to be visible to specified departments/users. Note For example, the organization enables hiding this department and sets 2 departments and 2 employees to be visible to specified departments/users. The department ID of Test Department 1 is 1 and the department ID of Test Department 2 is 2. When calling this API, the obtained value of dept_permits is [1,2]. The employee list is not returned, that is, the information of Employee Xiaoding 1 and Employee Xiaoding 2 is not returned. - Hide this department not enabled (that is, hide_dept is false): The dept_permits field is not returned.
auto_approve_apply	Boolean	true	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 require approval from an admin with permission.
code	String	10000	The department code. Note This field is returned only after the department code is set via the Update department API.
member_count	Number	10	The number of employees in the department (including sub-departments).
owning_member_count	Number	8	The number of employees directly belonging to the department (excluding sub-departments).
union_dept_ext	Object		The associated department information.
deptId	Number	1234567	The associated department ID.
corpId	String	test	The organization ID of the associated department.

Response body example

{
  "errcode": 0,
  "errmsg": "ok",
  "result": {
    "dept_permits": [
      3,
      4,
      5
    ],
    "outer_permit_users": [
      "user123",
      "1234"
    ],
    "dept_manager_userid_list": [
      "1020302901-431772414"
    ],
    "org_dept_owner": "manager9153",
    "outer_dept": false,
    "dept_group_chat_id": "chat1fccdb4b921f2bde18c26xxxx",
    "group_contain_sub_dept": true,
    "auto_add_user": true,
    "hide_dept": false,
    "name": "Test",
    "outer_permit_depts": [
      500,
      600
    ],
    "user_permits": [],
    "dept_id": 1,
    "create_dept_group": true,
    "order": 0,
    "code":"100",
    "union_dept_ext":{
      "corp_id": "test",
      "dept_id": 1234567
    }
  },
  "request_id": "4e7ljtq91rgo"
}

Error codes

If an error occurs when calling this API, find the solution by the error message in the Global error codes document.

Error code (errcode)	Error message (errmsg)	Solution
43007	Authorization required	Confirm that the access_token has the operation permission.
60003	Corresponding department not found	Confirm that the dept_id is correct.
400002	Invalid parameter	Confirm that the parameter is entered as required.
-1	System busy	Try again later.

​Request

​Query parameters

​Request body

​Request example

​Response

​Response body

​Response body example

​Error codes