Skip to main content
Call this API to get the list of users for a specified role.

​
Request

Basic information
HTTP URLhttps://oapi.dingtalk.io/topapi/role/simplelist
HTTP MethodPOST
Supported app typesappType-Internal appappType-Third-party enterprise app
Required permissionspermission-qyapi_get_department_member-Read permission for department users in Contacts

​
Query parameter

NameTypeRequiredExampleDescription
access_tokenStringYesbE74xxxxThe app credential used to call this API. - For an internal app, obtain it through the API for obtaining the access_token of an internal app. - For a third-party enterprise app, obtain it through the API for obtaining the access_token of a third-party enterprise.

​
Request body

NameTypeRequiredExampleDescription
role_idNumberYes1203141The role ID. To get this value, call the Get the role list API and use the value of the id parameter.
sizeNumberNo20The page size. Note This parameter takes effect only when set together with the offset parameter. The default value is 20 and the maximum value is 100.
offsetNumberNo0The pagination offset. Note This parameter takes effect only when set together with the size parameter. The offset starts from 0.

​
Request example

curl -X POST "https://oapi.dingtalk.io/topapi/role/simplelist" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=d1812xxxxc53245' \
-d 'offset=0' \
-d 'role_id=1203141' \
-d 'size=20'
Java 
DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/role/simplelist");
OapiRoleSimplelistRequest req = new OapiRoleSimplelistRequest();
req.setRoleId(1203141L);
req.setSize(20L);
req.setOffset(0L);
OapiRoleSimplelistResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());
Python 
import dingtalk.api

req=dingtalk.api.OapiRoleSimplelistRequest("https://oapi.dingtalk.io/topapi/role/simplelist")

req.role_id=1203141
req.offset=0
req.size=20
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 OapiRoleSimplelistRequest;
$req->setRoleId("1203141");
$req->setOffset("0");
$req->setSize("20");
$resp = $c->execute($req, $access_token, "https://oapi.dingtalk.io/topapi/role/simplelist");
C# 
IDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/role/simplelist");
OapiRoleSimplelistRequest req = new OapiRoleSimplelistRequest();
req.RoleId = 1203141L;
req.Offset = 0L;
req.Size = 20L;
OapiRoleSimplelistResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

​
Response

​
Response body

NameTypeExampleDescription
request_idStringf6249uw1kuusThe request ID.
errcodeNumber0The return code.
errmsgStringokThe description of the return code.
resultPageVoThe query result.
hasMoreBooleantrueIndicates whether more data is available.
listOpenEmpSimple[]The list of users assigned to the role.
useridStringmanager4220The user ID of the user.
nameStringJohnThe name of the user.
manageScopesOrgDeptVo[]The management scope.
dept_idNumber11The department ID.
nameStringDiscipline Inspection DepartmentThe department name.

​
Response body example

{
  "errcode": 0,
  "result": {
    "hasMore": false,
    "list": [
      {
        "name": "John",
        "userid": "manager4220",
        "manageScopes":[
          {
            "dept_id":11,
            "name":"Discipline Inspection Department"
          }
        ]
      }
    ]
  },
  "request_id": "f6249uw1kuus"
}

​
Error codes

If an error occurs when you call this API, look up the solution in the Global error codes document based on the error message.
Error code (errorcode)Error message (errmsg)Solution
33011Invalid roleIdCheck whether the roleId is correct.
40069Invalid sizeAdjust the page size.
40068Invalid offsetAdjust the offset.
400001System errorTry again later.