Skip to main content
Call this API to get the basic information of the next-tier departments. This API only returns the basic information of the immediate sub-departments of the current department. It does not return all sub-departments across every tier.

​
Request

Basic information
HTTP URLhttps://oapi.dingtalk.io/topapi/v2/department/listsub
HTTP MethodPOST
Supported app typesappType-Internal appappType-Third-party enterprise app
Permissionspermission-qyapi_get_department_list-Read permission for department information in Contacts

​
Query parameters

NameTypeRequiredExampleDescription
access_tokenStringYesbE74xxxxThe app credential used to call this API. - For an internal app, get it by calling the API for getting the access_token of an internal app. - For a third-party enterprise app, get it by calling the API for getting the access_token of a third-party enterprise.

​
Request body

NameTypeRequiredExampleDescription
dept_idNumberNo1The parent department ID. Call the Get the department list API to get the value of the dept_id parameter.
languageStringNozh_CNThe language of Contacts: - zh_CN (default): Chinese - en_US: English

​
Request example

curl -X POST "https://oapi.dingtalk.io/topapi/v2/department/listsub" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=6846xxxx0cc781' \
-d 'dept_id=100' \
-d 'language=zh_CN'
Java 
DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/v2/department/listsub");
OapiV2DepartmentListsubRequest req = new OapiV2DepartmentListsubRequest();
req.setDeptId(1L);
req.setLanguage("zh_CN");
OapiV2DepartmentListsubResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());
Python 
import dingtalk.api

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

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 OapiV2DepartmentListsubRequest;
$req->setDeptId("100");
$req->setLanguage("zh_CN");
$resp = $c->execute($req, $access_token, "https://oapi.dingtalk.io/topapi/v2/department/listsub");
C# 
IDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/v2/department/listsub");
OapiV2DepartmentListsubRequest req = new OapiV2DepartmentListsubRequest();
req.DeptId = 100L;
req.Language = "zh_CN";
OapiV2DepartmentListsubResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

​
Response

​
Response body

NameTypeExampleDescription
request_idString5um7ykyaalsjThe request ID.
errcodeNumber0The return code.
errmsgStringInvalid access_tokenThe error message returned when the call failed.
resultDeptBaseResponse[]The department list.
dept_idNumber100The department ID.
nameStringHRThe department name.
parent_idNumber50The parent department ID.
create_dept_groupBooleantrueWhether to create an organization chat associated with this department at the same time: - true: Create - false: Do not create
auto_add_userBooleanfalseAfter the Department Chat is created, whether new members who join the department are automatically added to the chat: - true: Automatically added - false: Not added

​
Response example

{
  "errcode": 0,
  "errmsg":"ok",
  "result": [
    {
      "auto_add_user": true,
      "create_dept_group": true,
      "dept_id": 37xxxx95,
      "name": "Marketing Department",
      "parent_id": 1
    },
    {
      "auto_add_user": true,
      "create_dept_group": true,
      "dept_id": 399xxxx96,
      "name": "Finance Department",
      "parent_id": 1
    }
  ],
  "request_id": "5um7ykyaalsj"
}

​
Error codes

If the API call returns an error, find the solution in the Global error codes document based on the error message.
Error code (errcode)Error message (errmsg)Solution
60003Department not foundVerify that the dept_id is correct.
400002Invalid parameterVerify that the parameters are entered as required.
-1System busyTry again later.