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://api.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://api.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'
DingTalkClient client = new DefaultDingTalkClient("https://api.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());
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)
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 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. |
| 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. |