Skip to main content
Call this API to set the management scope of a role member.

​
Request

Basic information
HTTP URLhttps://oapi.dingtalk.io/topapi/role/scope/update
HTTP MethodPOST
Supported app typeappType-Internal app
Required permissionspermission-qyapi_manage_addresslist-Contacts data management permission

​
Query parameters

NameTypeRequiredExampleDescription
access_tokenStringYesBe3xxxxThe app credential for calling this API. Obtain it through the API for obtaining the access_token of an internal app.

​
Request body

NameTypeRequiredExampleDescription
useridStringYesEMP123The user ID of the employee in the organization.
role_idNumberYes12345The role ID. Call the Obtain a list of organization roles API to obtain the value of the id parameter.
dept_idsStringNo1231The list of department IDs. Separate multiple department IDs with commas. A maximum of 50 department IDs are supported. If left empty, the scope is set to all users.

​
Request example

curl -X POST "https://oapi.dingtalk.io/topapi/role/scope/update" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=3100xxxx2280f5' \
-d 'dept_ids=1231' \
-d 'role_id=12345' \
-d 'userid=EMP123'
Java 
DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/role/scope/update");
OapiRoleScopeUpdateRequest req = new OapiRoleScopeUpdateRequest();
req.setUserid("EMP123");
req.setRoleId(12345L);
req.setDeptIds("1231,2423");
OapiRoleScopeUpdateResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());
Python 
import dingtalk.api

req=dingtalk.api.OapiRoleScopeUpdateRequest("https://oapi.dingtalk.io/topapi/role/scope/update")

req.userid="EMP123"
req.role_id=12345
req.dept_ids="1231"
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 OapiRoleScopeUpdateRequest;
$req->setUserid("EMP123");
$req->setRoleId("12345");
$req->setDeptIds("1231,2423,53536");
$resp = $c->execute($req, $access_token, "https://oapi.dingtalk.io/topapi/role/scope/update");
C# 
IDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/role/scope/update");
OapiRoleScopeUpdateRequest req = new OapiRoleScopeUpdateRequest();
req.Userid = "EMP123";
req.RoleId = 12345L;
req.DeptIds = "1231";
OapiRoleScopeUpdateResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

​
Response

​
Response body

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

​
Response body example

{
  "errcode":"0",
  "errmsg":"ok",
  "request_id":"4pe0h4hlsit9"
}

​
Error codes

If an error is returned when calling this API, find the solution in the Global error codes document based on the error message.
Error code (errcode)Error code description (errmsg)Solution
40003Invalid userIdVerify that the userId is correct.
34018role_id cannot be emptyProvide the roleId.
60301Invalid role_idVerify that the role_id is correct.
60003Department does not existVerify that the dept_ids are correct.
46004Employee is not in the organizationVerify that the parameters are correct.
400002Invalid parameterVerify that the request parameters are correct.
-1System busyTry again later.