Developer GuideAPI call description
- This API only returns the userId and name fields of users. To get detailed user information, see Get the complete information of a department user.
- This API only returns basic information about users in the current department. Information about users in sub-departments is not returned.
Request
| Basic information | |
|---|---|
| HTTP URL | https://api.dingtalk.io/topapi/user/listsimple |
| HTTP Method | POST |
| Supported app types | appType-Internal app appType-Third-party enterprise app |
| Permissions | permission-qyapi_get_department_member-Read permission for Contacts department users |
Query parameter
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| access_token | String | Yes | bE74xxxx | The app credential used to call this API. - For an internal app, obtain it through the API that gets the access_token of an internal app. - For a third-party enterprise app, obtain it through the API that gets the access_token of a third-party enterprise. |
Request body
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| dept_id | Number | Yes | 10 | The department ID. For the root department, pass 1. Call Get the department list to get the value of dept_id. |
| cursor | Number | Yes | 0 | The cursor for pagination. Pass 0 for the first request, and pass the next_cursor value from the response in subsequent requests. |
| size | Number | Yes | 10 | The page size. The maximum value is 100. |
| order_field | String | No | modify_desc | The sorting rules for department users. The default value is 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 the modified time of department information in ascending order. - modify_desc: sort by the modified time of department information in descending order. - custom: user-defined sorting (sorted by pinyin when not defined). |
| contain_access_limit | Boolean | No | false | Whether to return users with restricted access. - true: Yes - false: No |
| language | String | No | zh_CN | The language of Contacts. - zh_CN: Chinese (default). - en_US: English. |
Request example
curl -X POST "https://api.dingtalk.io/topapi/user/listsimple" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=c1f2d110-4e7c-4536-a340-06652613e0c1' \
-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/user/listsimple");
OapiUserListsimpleRequest req = new OapiUserListsimpleRequest();
req.setDeptId(10L);
req.setCursor(0L);
req.setSize(10L);
req.setOrderField("modify_desc");
req.setContainAccessLimit(false);
req.setLanguage("zh_CN");
OapiUserListsimpleResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());
import dingtalk.api
req=dingtalk.api.OapiUserListsimpleRequest("https://api.dingtalk.io/topapi/user/listsimple")
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 OapiUserListsimpleRequest;
$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/user/listsimple");
IDingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/user/listsimple");
OapiUserListsimpleRequest req = new OapiUserListsimpleRequest();
req.DeptId = 10L;
req.Cursor = 0L;
req.Size = 10L;
req.OrderField = "modify_desc";
req.Language = "zh_CN";
req.ContainAccessLimit = false;
req.Language = "zh_CN";
OapiUserListsimpleResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);
Response
Response body
| Name | Type | Example | Description |
|---|---|---|---|
| request_id | String | 4f9md9obopn2 | The request ID. |
| errcode | Number | 0 | The return code. 0 indicates success. |
| errmsg | String | ok | The description of the return code. |
| result | PageResult | 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 page. If has_more is false, no more paginated data is available. |
| list | ListUserSimpleResponse[] | The user information list. | |
| userid | String | zxxxxx | The userid of the user. |
| name | String | Zhang San | The user name. |
Response body example
{
"errcode": 0,
"errmsg": "ok",
"result": {
"has_more": false,
"list": [
{
"name": "Test User 2",
"userid": "user100"
},
{
"name": "Li Si",
"userid": "user1"
}
]
},
"request_id": "x4p6arvi0fzj"
}
Error codes
If an error occurs when you call this API, find the solution in the Global error codes document based on the error message.| Error code (errcode) | Error message (errmsg) | Solution |
|---|---|---|
| 400002 | Invalid parameter | Make sure the parameters are filled in as required above. |
| 60003 | The department is not found | Make sure the department ID is correct. |
| 40069 | Invalid size | Adjust the page size. |
| 40068 | Invalid offset | Adjust the offset. |
| -1 | System busy | Try again later. |