Skip to main content
Call this API to add roles to multiple employees in bulk. Roles in the “Default” group, including Owner, Supervisor, Super Admin, and Sub Admin, cannot be added.

​
Request

Basic information
HTTP URLhttps://oapi.dingtalk.io/topapi/role/addrolesforemps
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 through the API for getting the access_token of an internal app.

​
Request body

NameTypeRequiredExampleDescription
roleIdsStringYes1507113584The list of role IDs (roleId). Call the Get the list of roles API to obtain them. Separate multiple roleId values with commas (,). Up to 20 values are allowed.
userIdsStringYesuser1The userId of an employee. Call Query users by phone number to obtain it. Separate multiple userId values with commas (,). Up to 20 values are allowed.

​
Request example

curl -X POST "https://oapi.dingtalk.io/topapi/role/addrolesforemps" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=8f577dxxxx76f2a3a2' \
-d 'roleIds=1507113584' \
-d 'userIds=user1'
Java 
DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/role/addrolesforemps");
OapiRoleAddrolesforempsRequest req = new OapiRoleAddrolesforempsRequest();
req.setRoleIds("1507113584,1507113589");
req.setUserIds("user1,user2");
OapiRoleAddrolesforempsResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());
Python 
import dingtalk.api

req=dingtalk.api.OapiRoleAddrolesforempsRequest("https://oapi.dingtalk.io/topapi/role/addrolesforemps")

req.roleIds="1507113584"
req.userIds="user1"
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 OapiRoleAddrolesforempsRequest;
$req->setRoleIds("1507113584");
$req->setUserIds("user1");
$resp = $c->execute($req, $access_token, "https://oapi.dingtalk.io/topapi/role/addrolesforemps");
C# 
IDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/role/addrolesforemps");
OapiRoleAddrolesforempsRequest req = new OapiRoleAddrolesforempsRequest();
req.RoleIds = "1507113584";
req.UserIds = "user1";
OapiRoleAddrolesforempsResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

​
Response

​
Response body

NameTypeExampleDescription
errcodeNumber0The return code.
errmsgStringokThe description of the return code.
request_idStringemhw6ma4xmegThe request ID.

​
Response body example

{
  "errcode": 0,
  "request_id": "emhw6ma4xmeg"
}

​
Error codes

If an error occurs when you call this API, refer to the Global error codes document to find a solution based on the error message.
Error code (errcode)Error message (errmsg)Solution
33011Invalid roleIdsCheck whether the roleIds are correct.
33012Invalid userIdsCheck whether the userId values are correct.
12012The organization does not existCheck whether the access_token is correct.
1002System busyTry again later.