钉钉开发文档

部门管理

更新时间: 2018-12-25

获取子部门ID列表

【注意】该接口能获取到企业部门下的所有直属子部门列表,不受授权范围限制,ISV可以根据该接口完成企业部门的遍历。

请求方式:GET(HTTPS)
请求地址https://oapi.dingtalk.com/department/list_ids?access_token=ACCESS_TOKEN
参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证
id String 父部门id。根部门的话传1

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/department/list_ids");
OapiDepartmentListIdsRequest request = new OapiDepartmentListIdsRequest();
request.setId("123");
request.setHttpMethod("GET");
OapiDepartmentListIdsResponse response = client.execute(request, accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok",
    "sub_dept_id_list": [ 2,3,4,5 ]
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
sub_dept_id_list 子部门ID列表数据

获取部门列表

【注意】企业开发者所使用的CorpSecret都是按照部门进行设置的,企业开发者需要先查询自己的CorpSecret对应的授权部门。

请求方式:GET(HTTPS)
请求地址https://oapi.dingtalk.com/department/list?access_token=ACCESS_TOKEN
参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证
lang String 通讯录语言(默认zh_CN,未来会支持en_US)
fetch_child Boolean 是否递归部门的全部子部门,ISV微应用固定传递false
id String 父部门id(如果不传,默认部门为根部门,根部门ID为1)

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/department/list");
OapiDepartmentListRequest request = new OapiDepartmentListRequest();
request.setId("123");
request.setHttpMethod("GET");
OapiDepartmentListResponse response = client.execute(request, accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok",
    "department": [
        {
           "id": 2,
            "name": "钉钉事业部",
            "parentid": 1,
            "createDeptGroup": true,
            "autoAddUser": true
        },
        {
            "id": 3,
            "name": "服务端开发组",
            "parentid": 2,
            "createDeptGroup": false,
            "autoAddUser": false
        }
    ]
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
department 部门列表数据,以部门的order字段从小到大排列
id 部门id
name 部门名称
parentid 父部门id,根部门为1
createDeptGroup 是否同步创建一个关联此部门的企业群,true表示是,false表示不是
autoAddUser 当群已经创建后,是否有新人加入部门会自动加入该群, true表示是,false表示不是

获取部门详情



请求方式:GET(HTTPS)
请求地址https://oapi.dingtalk.com/department/get?access_token=ACCESS_TOKEN&id=123
参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证
id String 部门id
lang String 通讯录语言(默认zh_CN,未来会支持en_US)

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/department/get");
OapiDepartmentGetRequest request = new OapiDepartmentGetRequest();
request.setId("2");
request.setHttpMethod("GET");
OapiDepartmentGetResponse response = client.execute(request, accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok",
    "id": 2,
    "name": "钉钉事业部",
    "order" : 10,
    "parentid": 1,
    "createDeptGroup": true,
    "autoAddUser": true,
    "deptHiding" : true,
    "deptPermits" : "3|4",
    "userPermits" : "userid1|userid2",
    "outerDept" : true,
    "outerPermitDepts" : "1|2",
    "outerPermitUsers" : "userid3|userid4",
    "orgDeptOwner" : "manager1122",
    "deptManagerUseridList" : "manager1122|manager3211",
    "sourceIdentifier" : "source"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
id 部门id
name 部门名称
parentid 父部门id,根部门为1
order 当前部门在父部门下的所有子部门中的排序值
createDeptGroup 是否同步创建一个关联此部门的企业群,true表示是,false表示不是
autoAddUser 当部门群已经创建后,是否有新人加入部门会自动加入该群,true表示是,false表示不是
deptHiding 是否隐藏部门,true表示隐藏,false表示显示
deptPermits 可以查看指定隐藏部门的其他部门列表,如果部门隐藏,则此值生效,取值为其他的部门id组成的的字符串,使用“|”符号进行分割
userPermits 可以查看指定隐藏部门的其他人员列表,如果部门隐藏,则此值生效,取值为其他的人员userid组成的的字符串,使用“|”符号进行分割
outerDept 是否本部门的员工仅可见员工自己,为true时,本部门员工默认只能看到员工自己
outerPermitDepts 本部门的员工仅可见员工自己为true时,可以配置额外可见部门,值为部门id组成的的字符串,使用“|”符号进行分割
outerPermitUsers 本部门的员工仅可见员工自己为true时,可以配置额外可见人员,值为userid组成的的字符串,使用“|”符号进行分割
orgDeptOwner 企业群群主
deptManagerUseridList 部门的主管列表,取值为由主管的userid组成的字符串,不同的userid使用“|”符号进行分割
sourceIdentifier 部门标识字段,开发者可用该字段来唯一标识一个部门,并与钉钉外部通讯录里的部门做映射
groupContainSubDept 部门群是否包含子部门

查询部门的所有上级父部门路径

【注意】此接口不受授权范围的限制

假设部门的组织结构如下:
1
  |->123
    |->456
      |->789
当传入部门id为789时,返回的结果按顺序依次为当前部门id及其所有父部门的ID,直到根部门,如[789,456,123,1]。

请求方式:GET(HTTPS)
请求地址https://oapi.dingtalk.com/department/list_parent_depts_by_dept?access_token=ACCESS_TOKEN&id=ID
参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证
id String 希望查询的部门的id,包含查询的部门本身

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/department/list_parent_depts_by_dept");
OapiDepartmentListParentDeptsByDeptRequest request = new OapiDepartmentListParentDeptsByDeptRequest();
request.setId("789");
request.setHttpMethod("GET");
OapiDepartmentListParentDeptsByDeptResponse response = client.execute(request, accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok""parentIds":[789,456,123,1]
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
parentIds 该部门的所有父部门id列表

查询指定用户的所有上级父部门路径

【注意】此接口不受授权范围的限制

假设用户所属部门的组织结构如下
1
  |->123
    |->456  ->员工A
  |->789  ->员工A
当传入员工A的userId时,返回的结果按顺序依次为其所有父部门的ID,直到根部门,如[[456,123,1],[789,1]]。

请求方式:GET(HTTPS)
请求地址https://oapi.dingtalk.com/department/list_parent_depts?access_token=ACCESS_TOKEN&userId=USERID
参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证
userId String 希望查询的用户的id

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/department/list_parent_depts");
OapiDepartmentListParentDeptsRequest request = new OapiDepartmentListParentDeptsRequest();
request.setUserId("userId");
request.setHttpMethod("GET");
OapiDepartmentListParentDeptsResponse response = client.execute(request, accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok""department":[[456,123,1],[789,1]]
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
parentIds 该部门的所有父部门id列表

获取企业员工人数

请求方式:GET(HTTPS)
请求地址https://oapi.dingtalk.com/user/get_org_user_count?access_token=ACCESS_TOKEN&onlyActive=0
参数说明

参数
参数类型
必须
说明
access_token
String
调用接口凭证
onlyActive
Number
0:包含未激活钉钉的人员数量
1:不包含未激活钉钉的人员数量

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/get_org_user_count");
OapiUserGetOrgUserCountRequest request = new OapiUserGetOrgUserCountRequest();
request.setOnlyActive(1L);
request.setHttpMethod("GET");
OapiUserGetOrgUserCountResponse response = client.execute(request, accessToken);

返回结果

{ 
  "count":6,
  "errcode":0,
  "errmsg":"ok"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
count 企业员工数量

创建部门

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/department/create?access_token=ACCESS_TOKEN
请求包结构体

{
    "name": "钉钉事业部",
    "parentid": "1",
    "order": "1",
    "createDeptGroup": true,
    "deptHiding" : true,
    "deptPermits" : "3|4",
    "userPermits" : "userid1|userid2",
    "outerDept" : true,
    "outerPermitDepts" : "1|2",
    "outerPermitUsers" : "userid3|userid4",
    "sourceIdentifier" : "source"
}

参数说明

参数
参数类型
必须
说明
access_token
String
调用接口凭证
name
String
部门名称,长度限制为1~64个字符,不允许包含字符‘-’‘,’以及‘,’
parentid
String
父部门id,根部门id为1
order
String
在父部门中的排序值,order值小的排序靠前
createDeptGroup
Boolean
是否创建一个关联此部门的企业群,默认为false
deptHiding
Boolean
是否隐藏部门,
true表示隐藏
false表示显示
deptPermits
String
可以查看指定隐藏部门的其他部门列表,如果部门隐藏,则此值生效,取值为其他的部门id组成的字符串,使用“\|”符号进行分割。总数不能超过200
userPermits
String
可以查看指定隐藏部门的其他人员列表,如果部门隐藏,则此值生效,取值为其他的人员userid组成的的字符串,使用“\|”符号进行分割。总数不能超过200
outerDept
Boolean
限制本部门成员查看通讯录,限制开启后,本部门成员只能看到限定范围内的通讯录。true表示限制开启
outerPermitDepts
String
outerDept为true时,可以配置额外可见部门,值为部门id组成的的字符串,使用“\|”符号进行分割。总数不能超过200
outerPermitUsers
String
outerDept为true时,可以配置额外可见人员,值为userid组成的的字符串,使用“\|”符号进行分割。总数不能超过200
outerDeptOnlySelf
Boolean
outerDept为true时,可以配置该字段,为true时,表示只能看到所在部门及下级部门通讯录
sourceIdentifier
String
部门标识字段,开发者可用该字段来唯一标识一个部门,并与钉钉外部通讯录里的部门做映射

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/department/create");
OapiDepartmentCreateRequest request = new OapiDepartmentCreateRequest();
request.setParentid("1");
request.setCreateDeptGroup(true);
request.setOrder("100");
request.setName("部门");
OapiDepartmentCreateResponse response = client.execute(request, accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "created",
    "id": 2
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
id 创建的部门id

更新部门

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/department/update?access_token=ACCESS_TOKEN
请求包结构体

{
    "name": "钉钉事业部",
    "parentid": "1",
    "order": "1",
    "id": 1,
    "createDeptGroup": true,
    "autoAddUser": true,
    "deptManagerUseridList": "manager1111|2222",
    "deptHiding" : true,
    "deptPermits" : "3|4",
    "userPermits" : "userid1|userid2",
    "outerDept" : true,
    "outerPermitDepts" : "1|2",
    "outerPermitUsers" : "userid3|userid4",
    "orgDeptOwner": "manager1111",
    "sourceIdentifier" : "source"
}

参数说明

参数
参数类型
必须
说明
access_token
string
调用接口凭证
lang
String
通讯录语言(默认zh_CN另外支持en_US)
name
String
部门名称,长度限制为1~64个字符,不允许包含字符‘-’‘,’以及‘,’
parentid
String
父部门id,根部门id为1
order
String
在父部门中的排序值,order值小的排序靠前
id
String
部门id
createDeptGroup
Boolean
是否创建一个关联此部门的企业群
autoAddUser
Boolean
如果有新人加入部门是否会自动加入部门群
deptManagerUseridList
String
部门的主管列表,取值为由主管的userid组成的字符串,不同的userid使用“\|”符号进行分割
deptHiding
Boolean
是否隐藏部门,
true表示隐藏
false表示显示
deptPermits
String
可以查看指定隐藏部门的其他部门列表,如果部门隐藏,则此值生效,取值为其他的部门id组成的的字符串,使用“\|”符号进行分割。总数不能超过200
userPermits
String
可以查看指定隐藏部门的其他人员列表,如果部门隐藏,则此值生效,取值为其他的人员userid组成的字符串,使用“\|”符号进行分割。总数不能超过200
outerDept
Boolean
是否本部门的员工仅可见员工自己, 为true时,本部门员工默认只能看到员工自己
outerPermitDepts
String
本部门的员工仅可见员工自己为true时,可以配置额外可见部门,值为部门id组成的的字符串,使用\|符号进行分割。总数不能超过200
outerPermitUsers
String
本部门的员工仅可见员工自己为true时,可以配置额外可见人员,值为userid组成的的字符串,使用\|符号进行分割。总数不能超过200
outerDeptOnlySelf
Boolean
outerDept为true时,可以配置该字段,为true时,表示只能看到所在部门及下级部门通讯录
orgDeptOwner
String
企业群群主
sourceIdentifier
String
部门标识字段,开发者可用该字段来唯一标识一个部门,并与钉钉外部通讯录里的部门做映射

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/department/update");
OapiDepartmentUpdateRequest request = new OapiDepartmentUpdateRequest();
request.setId(Long.valueOf("123"));
request.setParentid("1");
request.setOrder("200");
request.setName("部门2");
OapiDepartmentUpdateResponse response = client.execute(request, accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok",
    "id": 61602002
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
id 已经更新的部门id

删除部门

请求方式:GET(HTTPS)
请求地址https://oapi.dingtalk.com/department/delete?access_token=ACCESS_TOKEN&id=ID
参数说明

参数
参数类型
必须
说明
access_token
String
调用接口凭证
id
String
部门id
(注:不能删除根部门;不能删除含有子部门、成员的部门)

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/department/delete");
OapiDepartmentDeleteRequest request = new OapiDepartmentDeleteRequest();
request.setId("123");
request.setHttpMethod("GET");
OapiDepartmentDeleteResponse response = client.execute(request, accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
以上内容是否对您有帮助:
在文档使用中是否遇到以下问题(多选):
  • 内容错误
  • 更新不及时
  • 链接错误
  • 缺少代码/图片示例
  • 太简单/步骤待完善
手机号
更多建议
提交成功,感谢您的反馈!