Get the details of Enterprise Account users in a department

Call this API to get the details of employees in a specified department. Employees in sub-departments cannot be retrieved. This API is currently only available to organizations that have purchased and enabled Enterprise Account.

Request

Basic information
HTTP URL	https://api.dingtalk.io/topapi/v2/user/list
HTTP Method	POST
Supported app types	appType-Internal app, appType-Third-party enterprise app
Permissions required	permission-qyapi_get_department_member-Contacts department member read permission

Query parameters

Name	Type	Required	Example	Description
access_token	String	Yes	be3Fxxxx	The app credential used to call this API. - For an internal app, obtain it through the API for getting the access_token of an internal app. - For a third-party enterprise app, obtain it through the API for getting the access_token of a third-party enterprise.

Request body

Name	Type	Required	Example	Description
dept_id	Number	Yes	10	The department ID. Call the Get the department list API to obtain the value of dept_id. Note - Only employees in the current department are returned. Employees in sub-departments are not included. - For the root department, pass 1.
cursor	Number	Yes	0	The cursor for pagination. Pass 0 for the first call, then pass the value of next_cursor returned in subsequent calls.
size	Number	Yes	10	The page size.
order_field	String	No	modify_desc	The sorting rules for department members. If this parameter is not passed, results are sorted by custom order (custom) by default. - entry_asc: Sort by ascending order of the time joining the department. - entry_desc: Sort by descending order of the time joining the department. - modify_asc: Sort by ascending order of department information modification time. - modify_desc: Sort by descending order of department information modification time. - custom: Sort by user-defined order (by pinyin when undefined).
contain_access_limit	Boolean	No	false	Whether to return employees with access restrictions: - true: Return them. - false: Do not return them.
language	String	No	zh_CN	The language for Contacts. - zh_CN: Chinese (default). - en_US: English.

Request example

curl -X POST "https://api.dingtalk.io/topapi/v2/user/list" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=8d4de2xxxx49c' \
-d 'contain_access_limit=false' \
-d 'cursor=0' \
-d 'dept_id=10' \
-d 'language=zh_CN' \
-d 'order_field=modify_desc' \
-d 'size=10'

Java

DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/v2/user/list");
OapiV2UserListRequest req = new OapiV2UserListRequest();
req.setDeptId(10L);
req.setCursor(0L);
req.setSize(10L);
req.setOrderField("modify_desc");
req.setContainAccessLimit(false);
req.setLanguage("zh_CN");
OapiV2UserListResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());

Python

import dingtalk.api

req=dingtalk.api.OapiV2UserListRequest("https://api.dingtalk.io/topapi/v2/user/list")

req.dept_id=10
req.cursor=0
req.size=10
req.order_field="modify_desc"
req.contain_access_limit=false
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 OapiV2UserListRequest;
$req->setDeptId("10");
$req->setCursor("0");
$req->setSize("10");
$req->setOrderField("modify_desc");
$req->setContainAccessLimit("false");
$req->setLanguage("zh_CN");
$resp = $c->execute($req, $access_token, "https://api.dingtalk.io/topapi/v2/user/list");

IDingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/v2/user/list");
OapiV2UserListRequest req = new OapiV2UserListRequest();
req.DeptId = 10L;
req.Cursor = 0L;
req.Size = 10L;
req.OrderField = "modify_desc";
req.ContainAccessLimit = false;
req.Language = "zh_CN";
OapiV2UserListResponse 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.
result	Object		The returned result.
has_more	Boolean	true	Whether more data is available: - true: Yes. - false: No.
next_cursor	Number	10	The cursor for the next pagination. Note If has_more is false, there is no more paginated data.
list	Object[]		The user information list.
userid	String	zhangsan	The userId of the user.
unionid	String	z21HjQliSzpw0YWCNxmii6u2Os62cZ62iSZ	The unique identifier of the user within the current developer’s enterprise account scope.
name	String	John	The user name.
avatar	String	xxx	The profile photo URL.
state_code	String	86	The international dialing code. Note - For an internal app, if this field is not returned, check whether the Permission to access employee mobile numbers is enabled in the current app’s Contacts permissions. - This parameter is not returned for third-party enterprise apps. To obtain state_code, use the DingTalk unified authorization suite.
mobile	String	13800138000	The mobile number. Note - For an internal app, if this field is not returned, check whether the Permission to access employee mobile numbers is enabled in the current app’s Contacts permissions. - This parameter is not returned for third-party enterprise apps. To obtain mobile, use the DingTalk unified authorization suite.
hide_mobile	Boolean	false	Whether the mobile number is hidden: - true: Hidden. After the mobile number is hidden, it is hidden on the Profile page, but DING messages and DingTalk business calls can still be sent to the number. - false: Not hidden.
telephone	String	010-86123456-2345	The extension number. Note This parameter is not returned for third-party enterprise apps.
job_number	String	4	The employee ID.
title	String	Technical Director	The job title.
email	String	test@xxx.com	The employee mail. Note - For an internal app, if this field is not returned, check whether the Mail and other profile permission is enabled in the current app’s Contacts permissions. - This field is returned only when the mail field has a value in the employee information panel. - This parameter is not returned for third-party enterprise apps.
org_email	String	test@xxx.com	The Enterprise Mail of the employee. Note - For an internal app, if this field is not returned, check whether the Mail and other profile permission is enabled in the current app’s Contacts permissions. - This field is returned only when it has a value in the employee information panel. - This parameter is not returned for third-party enterprise apps.
work_place	String	Future Park	The Work Location. Note - For an internal app, if this field is not returned, check whether the Mail and other profile permission is enabled in the current app’s Contacts permissions. - This field is returned only when it has a value in the employee information panel. - This parameter is not returned for third-party enterprise apps.
remark	String	Remarks	The alias. Note - For an internal app, if this field is not returned, check whether the Mail and other profile permission is enabled in the current app’s Contacts permissions. - This field is returned only when it has a value in the employee information panel. - This parameter is not returned for third-party enterprise apps.
dept_id_list	Number[]	[2,3,4]	The list of department IDs to which the employee belongs.
dept_order	Number	1	The sort order of the employee within the department.
extension	String	`{"Hobby":"Travel","Age":"24"}`	The extended attributes. Note - For an internal app, if this field is not returned, check whether the Mail and other profile permission is enabled in the current app’s Contacts permissions. - This field is returned only when it has a value in the employee information panel. - This parameter is not returned for third-party enterprise apps.
hired_date	Number	1597573616828	The hire date, as a Unix timestamp in milliseconds. Note This parameter is not returned for third-party enterprise apps.
active	Boolean	true	Whether DingTalk has been activated: - true: Activated. - false: Not activated.
admin	Boolean	true	Whether the user is an admin of the organization: - true: Yes. - false: No.
boss	Boolean	true	Whether the user is the boss of the organization: - true: Yes. - false: No.
leader	Boolean	true	Whether the user is the leader of the department: - true: Yes. - false: No.
exclusive_account	Boolean	true	Whether the user is an Enterprise Account: - true: Yes. - false: No. Note This parameter is not returned for third-party enterprise apps.
login_id	String	login_id3	The sign-in name of the Enterprise Account in your organization. Note This field is returned only for DingTalk Enterprise Accounts that belong to your organization.
exclusive_account_type	String	dingtalk	sso	The Enterprise Account type. - sso: Enterprise Account created by the organization. - dingtalk: Enterprise Account created by DingTalk. Note This field is returned only for Enterprise Accounts.
nickname	String	Name	The name of the Enterprise Account. Note This field is returned only for Enterprise Accounts created by your organization.
exclusive_account_corp_name	String	Organization Name	The name of the organization to which the Enterprise Account belongs. Note Only applicable to Enterprise Accounts. Returns the name of the organization that created the Enterprise Account.
exclusive_account_corp_id	String	corpxxx	The organization ID of the organization to which the Enterprise Account belongs. Note Only applicable to Enterprise Accounts. Returns the organization ID of the organization that created the Enterprise Account.
disable_status	Boolean	true	The disabled status of the Enterprise Account in your organization: - true: Disabled. - false: Enabled. Note This field is returned only for DingTalk Enterprise Accounts that belong to your organization.

Response example

{
  "errcode":"0",
  "result":{
    "next_cursor":"10",
    "has_more":"true",
    "list":{
      "leader":"true",
      "exclusive_account_type":"dingtalk|sso",
      "extension":"{\"Hobby\":\"Travel\",\"Age\":\"24\"}",
      "unionid":"z21HjQliSzpw0YWCNxmii6u2Os62cZ62iSZ",
      "boss":"true",
      "exclusive_account":"true",
      "admin":"true",
      "remark":"Remarks",
      "title":"Technical Director",
      "hired_date":"1597573616828",
      "userid":"zhangsan",
      "work_place":"Future Park",
      "nickname":"Name",
      "dept_id_list":"[2,3,4]",
      "job_number":"4",
      "email":"test@xxx.com",
      "dept_order":"1",
      "login_id":"login_id3",
      "exclusive_account_corp_name":"Organization Name",
      "mobile":"13800138000",
      "active":"true",
      "telephone":"010-86123456-2345",
      "avatar":"xxx",
      "hide_mobile":"false",
      "exclusive_account_corp_id":"corpxxx",
      "org_email":"test@xxx.com",
      "name":"John",
      "state_code":"86"
    }
  },
  "errmsg":"ok"
}

Error codes

If an error is returned when calling this API, find a solution in the Global error codes document based on the error message.

Error code (errcode)	Error message (errmsg)	Solution
400002	Invalid parameter	Check whether the parameter is filled in as required.
50004	The department is not within the permission scope	Make sure the access_token has operation permissions.
40035	Invalid parameter	dept_id, cursor, size, or order_field is filled in incorrectly.
60019	Failed to get users from the department	Make sure the relevant parameters are filled in correctly.
-1	System busy	Try again later.

API calling guide

Authentication & authorization

Contacts

Calendar

Conferencing

AI Table

Docs & files

IM

Get the details of Enterprise Account users in a department

Request

Query parameters

Request body

Request example

Response

Response body

Response example

Error codes

​Request

​Query parameters

​Request body

​Request example

​Response

​Response body

​Response example

​Error codes

Request

Query parameters

Request body

Request example

Response

Response body

Response example

Error codes