Skip to main content
Call this API to get the role list.

​
Request

Basic information
HTTP URLhttps://oapi.dingtalk.io/topapi/role/list
HTTP MethodPOST
Supported app typesappType-Internal app, appType-Third-party enterprise app
Permissionspermission-qyapi_get_department_list-Read permission for Contacts department information

​
Query parameters

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

​
Request body

NameTypeRequiredExampleDescription
sizeNumberNo20Supports paginated queries. Takes effect only when set together with the offset parameter. This parameter represents the page size. Default is 20. Maximum is 200.
offsetNumberNo0Supports paginated queries. Takes effect only when set together with the size parameter. This parameter represents the offset, which starts from 0.

​
Request example

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

req=dingtalk.api.OapiRoleListRequest("https://oapi.dingtalk.io/topapi/role/list")

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

​
Response

​
Response body

NameTypeExampleDescription
request_idStringii8a42qgzu7eThe request ID.
errcodeNumber0The return code.
errmsgStringokThe description of the return code.
resultPageVoThe result list.
hasMoreBooleanfalseWhether more data is available.
listOpenRoleGroup[]The role group list.
nameStringDefaultThe role group name.
groupIdNumber1507113577The role group ID.
rolesOpenRole[]The role list.
nameStringAdminThe role name.
idNumber1507113578The role ID.

​
Response body example

{
  "errcode": 0,
  "result": {
    "hasMore": true,
    "list": [
      {
        "groupId": 1507113577,
        "name": "Default",
        "roles": [
          {
            "id": 1507113580,
            "name": "Owner"
          },
          {
            "id": 1507113581,
            "name": "Manager"
          },
          {
            "id": 1507113578,
            "name": "Super Admin"
          },
          {
            "id": 1507113579,
            "name": "Sub Admin"
          }
        ]
      }
    ]
  },
  "request_id": "ii8a42qgzu7e"
}

​
Error codes

If an error is returned when you call this API, find a solution in the Global error codes document based on the error message.
Error code (errcode)Error message (errmsg)Solution
400043Invalid orgIdCheck whether the access_token is correct.
40069Invalid sizeAdjust the page size.
40068Invalid offsetAdjust the offset.
400001System errorTry again later.