Get details of users in a department

Call this API to get the details of users in a specified department.

API call description

This API only returns the details of users in the specified department. Users in sub-departments are not returned.
This API can return the details of either regular-account users or Enterprise Account users in a department. Because the parameter usage differs significantly between the two scenarios, the documentation is split by account type for clarity:
- To get details of regular-account users in a department, refer to this document.
- To get details of Enterprise Account users in a department (typically Enterprise DingTalk users), see Get details of Enterprise Account users in a department.

Request

Basic information
HTTP URL	https://oapi.dingtalk.io/topapi/v2/user/list
HTTP Method	POST
Supported app types	appType-Internal app, appType-Third-party enterprise app
Required permissions	permission-qyapi_get_department_member-Read permission for department members in Contacts

Query parameter

Name	Type	Required	Example	Description
access_token	String	Yes	bE74xxxx	The app credential used to call this API. - For an internal app, get it through the API for getting the access_token of an internal app. - For a third-party enterprise app, get 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 Get the department list to get it. For the root department, set this parameter to 1. Note Only users in the current department are returned. Users in sub-departments are not included.
cursor	Number	Yes	0	The cursor for paginated queries. Set it to 0 for the first call, and then use the `next_cursor` value returned by the previous call.
size	Number	Yes	10	The page size.
order_field	String	No	modify_desc	The sorting rule for department members. If not specified, the default is custom sorting (`custom`): - entry_asc: sort by the time of joining the department in ascending order. - entry_desc: sort by the time of joining the department in descending order. - modify_asc: sort by department information modified time in ascending order. - modify_desc: sort by department information modified time in descending order. - custom: sort by user-defined order (or by pinyin if not defined).
contain_access_limit	Boolean	No	false	Whether to return users with restricted access: - 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://oapi.dingtalk.io/topapi/v2/user/list" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=834f6b00-25b8-4484-a89d-595d1f7fa0a7' \
-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://oapi.dingtalk.io/topapi/v2/user/list");
OapiV2UserListRequest req = new OapiV2UserListRequest();
req.setDeptId(1L);
req.setCursor(0L);
req.setSize(10L);
req.setOrderField("modify_desc");
req.setContainAccessLimit(false);
req.setLanguage("zh_CN");
OapiV2UserListResponse rsp = client.execute(req, "");
System.out.println(rsp.getBody());

Python

import dingtalk.api

req=dingtalk.api.OapiV2UserListRequest("https://oapi.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://oapi.dingtalk.io/topapi/v2/user/list");

IDingTalkClient client = new DefaultDingTalkClient("https://oapi.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 result returned.
has_more	Boolean	true	Whether there is more data: - true: yes. - false: no.
next_cursor	Number	10	The cursor for the next page. Note If has_more is false, there is no more paginated data.
list	Object[]		The list of user information.
userid	String	zhangsan	The user ID.
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 - If this field is not returned for an internal app, 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 get `state_code`, use the DingTalk unified authorization suite.
mobile	String	13800138000	The mobile number. Note - If this field is not returned for an internal app, 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 get `mobile`, use the DingTalk unified authorization suite.
hide_mobile	Boolean	false	Whether the mobile number is hidden: - true: hidden. When hidden, the mobile number is hidden on the Profile page, but other users can still send DINGs or initiate DingTalk free business calls to this 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 - If this field is not returned for an internal app, check whether the Mail and other personal information permission is enabled in the current app’s Contacts permissions. - The field is returned only when it has a value on the user information panel. - This parameter is not returned for third-party enterprise apps.
org_email	String	test@xxx.com	The employee’s Enterprise Mail. Note - If this field is not returned for an internal app, check whether the Mail and other personal information permission is enabled in the current app’s Contacts permissions. - The field is returned only when it has a value on the user information panel. - This parameter is not returned for third-party enterprise apps.
work_place	String	Future Park	The work location. Note - If this field is not returned for an internal app, check whether the Mail and other personal information permission is enabled in the current app’s Contacts permissions. - The field is returned only when it has a value on the user information panel. - This parameter is not returned for third-party enterprise apps.
remark	String	Remark	The alias. Note - If this field is not returned for an internal app, check whether the Mail and other personal information permission is enabled in the current app’s Contacts permissions. - The field is returned only when it has a value on the user information panel. - This parameter is not returned for third-party enterprise apps.
dept_id_list	Number[]	[2,3,4]	The list of department IDs the user belongs to.
dept_order	Number	1	The user’s sort order within the department.
extension	String	`{"Hobby":"Travel","Age":"24"}`	The extended attributes. Note - If this field is not returned for an internal app, check whether the Mail and other personal information permission is enabled in the current app’s Contacts permissions. - The field is returned only when it has a value on the user 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 the user has activated DingTalk: - 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	false	Whether the user is an Enterprise Account: - true: yes. - false: no. Note - For an introduction to Enterprise Accounts, see Enterprise Account overview. - This parameter is not returned for third-party enterprise apps.

Response body example

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

Error codes

If an error is returned when you call this API, find the solution in Global error codes based on the error message.

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

​API call description

​Request

​Query parameter

​Request body

​Request example

​Response

​Response body

​Response body example

​Error codes

API call description

Request

Query parameter

Request body

Request example

Response

Response body

Response body example

Error codes