Skip to main content
Call this API to get the details of a specified role by role ID.

​
Request

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

​
Query parameters

NameTypeRequiredExampleDescription
access_tokenStringYesbE74xxxxThe 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
roleIdNumberYes1581321999The role ID. To get the value of the id parameter, call the Get role list API.

​
Request example

curl -X POST "https://oapi.dingtalk.io/topapi/role/getrole" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=2c9ecxxxx4210' \
-d 'roleId=1001'
Java 
DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/role/getrole");
OapiRoleGetroleRequest req = new OapiRoleGetroleRequest();
req.setRoleId(1507113578L);
OapiRoleGetroleResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());
Python 
import dingtalk.api

req=dingtalk.api.OapiRoleGetroleRequest("https://oapi.dingtalk.io/topapi/role/getrole")

req.roleId=1001
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 OapiRoleGetroleRequest;
$req->setRoleId("1001");
$resp = $c->execute($req, $access_token, "https://oapi.dingtalk.io/topapi/role/getrole");
C# 
IDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/role/getrole");
OapiRoleGetroleRequest req = new OapiRoleGetroleRequest();
req.RoleId = 1001L;
OapiRoleGetroleResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

​
Response

​
Response body

NameTypeExampleDescription
roleOpenRoleThe role information.
nameStringOwnerThe role name.
groupIdNumber1507113577The ID of the role group that the role belongs to.
errcodeNumber0The return code.
errmsgStringokThe description of the return code.
request_idString4cmr6app8ujfThe request ID.

​
Response example

{
  "errcode":0,
  "role":{
    "groupId":1507113577,
    "name":"Owner"
  },
  "request_id":"4cmr6app8ujf"
}

​
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
33011Invalid roleIdVerify that the roleId is correct.
43007Operation permission requiredVerify that the access_token has the required permissions.
400001System errorTry again later.