Get basic information about department users

Call this API to get basic information about users in a specified department.

API 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://oapi.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://oapi.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'

Java

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

Python

import dingtalk.api

req=dingtalk.api.OapiUserListsimpleRequest("https://oapi.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)

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 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://oapi.dingtalk.io/topapi/user/listsimple");

IDingTalkClient client = new DefaultDingTalkClient("https://oapi.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.

​API call description

​Request

​Query parameter

​Request body

​Request example

​Response

​Response body

​Response body example

​Error codes