Skip to main content
Call this API to create a new role.

​
Request

Basic information
HTTP URLhttps://oapi.dingtalk.io/role/add_role
HTTP MethodPOST
Supported app typesappType-Internal app
Required permissionspermission-qyapi_manage_addresslist-Contacts data management permission

​
Query parameters

NameTypeRequiredExampleDescription
access_tokenStringYes6d1bxxxxThe app credential used to call this API. Obtain it by calling the API for getting the access_token of an internal app.

​
Request body

NameTypeRequiredExampleDescription
roleNameStringYesServiceThe name of the role.
groupIdNumberYes1507113595The ID of the role group. - If the target role group already exists, call the Get the list of roles API to obtain it. - If the role group has not been created, first call the Create a role group API to create one and obtain its ID.

​
Request example

curl -X POST "https://oapi.dingtalk.io/role/add_role" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=2e3f55xxxx6e34' \
-d 'groupId=11' \
-d 'roleName=test'
Java 
DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/role/add_role");
OapiRoleAddRoleRequest req = new OapiRoleAddRoleRequest();
req.setRoleName("Test1");
req.setGroupId(1507113595L);
OapiRoleAddRoleResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());
Python 
import dingtalk.api

req=dingtalk.api.OapiRoleAddRoleRequest("https://oapi.dingtalk.io/role/add_role")

req.roleName="test"
req.groupId=11
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 OapiRoleAddRoleRequest;
$req->setRoleName("test");
$req->setGroupId("11");
$resp = $c->execute($req, $access_token, "https://oapi.dingtalk.io/role/add_role");
C# 
IDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/role/add_role");
OapiRoleAddRoleRequest req = new OapiRoleAddRoleRequest();
req.RoleName = "test";
req.GroupId = 11L;
OapiRoleAddRoleResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

​
Response

​
Response body

NameTypeExampleDescription
roleIdNumber1688611118The ID of the role.
errcodeNumber0The return code.
errmsgStringokThe description of the return code.

​
Response body example

{
  "errcode":0,
  "roleId":1688611118,
  "errmsg":"ok"
}

​
Error codes

If an error is returned 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
34018The role cannot be emptyProvide both roleName and groupId.
34020Invalid groupIdCheck whether groupId is correct.
34021The role name already existsCheck whether roleName is correct.
-1System busyTry again later.