钉钉开发文档

用户管理

更新时间: 2018-12-24

获取用户详情

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

参数 参数类型 必须 说明
access_token String 调用接口凭证
userid String 企业内的userid,企业用来唯一标识一个用户
lang String 通讯录语言(默认zh_CN,未来会支持en_US)

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/get");
OapiUserGetRequest request = new OapiUserGetRequest();
request.setUserid("zhangsan");
request.setHttpMethod("GET");
OapiUserGetResponse response = client.execute(request, accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok",
    "name": "test1",
    "unionid": "PiiiPyQqBNBii0HnCJ3zljcuAiEiE",
    "userid": "zhangsan",
    "isLeaderInDepts": "{1:false}",
    "isBoss": false,
    "hiredDate": 1520265600000,
    "isSenior": false,
    "department": [1,2],
    "orderInDepts": "{1:71738366882504}",
    "active": false,
    "avatar": "dingtalk.com/abc.jpg",
    "isAdmin": false,
    "isHide": false,
    "jobnumber": "001",
    "position": "manager"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
userid 员工唯一标识ID(不可修改
name 员工名字
active 是否已经激活,true表示已激活,false表示未激活
orderInDepts 在对应的部门中的排序,Map结构的json字符串,key是部门的Id,value是人员在这个部门的排序值
isAdmin 是否为企业的管理员,true表示是,false表示不是
isBoss 是否为企业的老板,true表示是,false表示不是
unionid 在当前isv全局范围内唯一标识一个用户的身份,用户无法修改
isLeaderInDepts 在对应的部门中是否为主管:Map结构的json字符串,key是部门的Id,value是人员在这个部门中是否为主管,true表示是,false表示不是
isHide 是否号码隐藏,true表示隐藏,false表示不隐藏
department 成员所属部门id列表
position 职位信息
avatar 头像url
hiredDate 入职时间。Unix时间戳 (在OA后台通讯录中的员工基础信息中维护过入职时间才会返回)
jobnumber 员工工号
isSenior 是否是高管
roles 角色信息(ISV不可见),json数组格式
roles.id 角色id(ISV不可见
roles.name 角色名称(ISV不可见
roles.groupName 角色分组名称(ISV不可见

获取部门用户userid列表

【推荐使用】通过该接口,可以获取当前部门下的userid列表

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

参数 参数类型 必须 说明
access_token String 调用接口凭证
deptId String 部门id

S​DK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/getDeptMember");
OapiUserGetDeptMemberRequest req = new OapiUserGetDeptMemberRequest();
req.setDeptId("a");
req.setHttpMethod("GET");
OapiUserGetDeptMemberResponse rsp = client.execute(req, accessToken);
System.out.println(rsp.getBody());

返回结果

{
    "errcode": 0,
    "errmsg": "ok",
    "userIds": ["1","2"]
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
userIds userid列表

获取部门用户

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

参数
参数类型
必须
说明
access_token
String
调用接口凭证
lang
String
通讯录语言(默认zh_CN另外支持en_US)
department_id
long
获取的部门id
offset
long
支持分页查询,与size参数同时设置时才生效,此参数代表偏移量
size
int
支持分页查询,与offset参数同时设置时才生效,此参数代表分页大小,最大100
order
String
支持分页查询,部门成员的排序规则,默认不传是按自定义排序;
entry_asc:代表按照进入部门的时间升序,
entry_desc:代表按照进入部门的时间降序,
modify_asc:代表按照部门信息修改时间升序,
modify_desc:代表按照部门信息修改时间降序,
custom:代表用户定义(未定义时按照拼音)排序

S​DK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/simplelist");
OapiUserSimplelistRequest request = new OapiUserSimplelistRequest();
request.setDepartmentId(100L);
request.setOffset(0L);
request.setSize(10L);
request.setHttpMethod("GET");

OapiUserSimplelistResponse response = client.execute(request, accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok",
    "hasMore": false,
    "userlist": [
        {
            "userid": "zhangsan",
            "name": "张三"
        }
    ]
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
hasMore 在分页查询时返回,代表是否还有下一页更多数据
userlist 成员列表
userid 员工唯一标识ID(不可修改
name 成员名称

获取部门用户详情

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

参数
参数类型
必须
说明
access_token
String
调用接口凭证
lang
String
通讯录语言(默认zh_CN另外支持en_US)
department_id
long
获取的部门id,1表示根部门
offset
long
支持分页查询,与size参数同时设置时才生效,此参数代表偏移量
size
int
支持分页查询,与offset参数同时设置时才生效,此参数代表分页大小,最大100
order
String
支持分页查询,部门成员的排序规则,默认 是按自定义排序;
entry_asc:代表按照进入部门的时间升序,
entry_desc:代表按照进入部门的时间降序,
modify_asc:代表按照部门信息修改时间升序,
modify_desc:代表按照部门信息修改时间降序,
custom:代表用户定义(未定义时按照拼音)排序

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/listbypage");
OapiUserListbypageRequest request = new OapiUserListbypageRequest();
request.setDepartmentId(1L);
request.setOffset(0L);
request.setSize(10L);
request.setOrder("entry_desc");
request.setHttpMethod("GET");
OapiUserListbypageResponse execute = client.execute(request,accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok",
    "hasMore": false,
    "userlist":[
        {
            "userid": "zhangsan",
            "unionid": "PiiiPyQqBNBii0HnCJ3zljcuAiEiE",
            "order" : 1,
            "isAdmin": true,
            "isBoss": false,
            "isHide": true,
            "isLeader": true,
            "name": "张三",
            "active": true,
            "department": [1, 2],
            "position": "工程师",
            "avatar":  "./dingtalk/abc.jpg",
            "jobnumber": "111111"
        }
    ]
}
参数
说明
errcode
返回码
errmsg
对返回码的文本描述内容
hasMore
在分页查询时返回,代表是否还有下一页更多数据
userlist
成员列表
userid
员工唯一标识ID(不可修改
order
表示人员在此部门中的排序,列表是按order的倒序排列输出的,即从大到小排列输出的
钉钉管理后台里面调整了顺序的话order才有值
unionid
在当前isv全局范围内唯一标识一个用户的身份,用户无法修改
isAdmin
是否是企业的管理员,true表示是,false表示不是
isBoss
是否为企业的老板,true表示是,false表示不是
isHide
是否隐藏号码,true表示是,false表示不是
isLeader
是否是部门的主管,true表示是,false表示不是
name
成员名称
active
表示该用户是否激活了钉钉
department
成员所属部门id列表
position
职位信息
avatar
头像url
jobnumber
员工工号
hiredDate
入职时间

获取管理员列表

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

参数 参数类型 必须 说明
access_token String 调用接口凭证

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/get_admin");
OapiUserGetAdminRequest request = new OapiUserGetAdminRequest();
request.setHttpMethod("GET");

OapiUserGetAdminResponse response = client.execute(request, accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok",
    "admin_list":[
        {"sys_level":2,"userid":"123abc"}
        {"sys_level":1,"userid":"456efg"}
    ]
}
参数
说明
errcode
返回码
errmsg
对返回码的文本描述内容
sys_level
管理员角色
1:主管理员
2:子管理员

获取管理员通讯录权限范围

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

参数 参数类型 必须 说明
access_token String 调用接口凭证
userid String 员工唯一标识ID

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/user/get_admin_scope");
OapiUserGetAdminScopeRequest req = new OapiUserGetAdminScopeRequest();
req.setUserid("manager7078");
OapiUserGetAdminScopeResponse rsp = client.execute(req, accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok",
    "dept_ids"":[1,2]
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
dept_ids 可管理的部门id列表

查询管理员是否具备管理某个应用的权限

ISV专用接口,应用必须是ISV所开发,且管理员所在组织必须开通了此应用。


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

参数 参数类型 必须 说明
access_token String 调用接口凭证
appId String 微应用id
userId String 员工唯一标识ID

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/can_access_microapp");
OapiUserCanAccessMicroappRequest request = new OapiUserCanAccessMicroappRequest();
request.setUserId("zhangsan");
request.setAppId(158L);
request.setHttpMethod("GET");

OapiUserCanAccessMicroappResponse response = client.execute(request, accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok",
    "canAccess":true
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
canAccess 表示是否能管理该微应用

根据unionid获取userid

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

参数 参数类型 必须 说明
access_token String 调用接口凭证
unionid String 用户在当前钉钉开放平台账号范围内的唯一标识,同一个钉钉开放平台账号可以包含多个开放应用,同时也包含第三方企业应用及企业自建应用

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/getUseridByUnionid");
OapiUserGetUseridByUnionidRequest request = new OapiUserGetUseridByUnionidRequest();
request.setUnionid("M9Ar4MVQA4vk4iPRwIJdTXAiEiE");
request.setHttpMethod("GET");

OapiUserGetUseridByUnionidResponse response = client.execute(request, accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok",
    "contactType": 0,
    "userid": "16475530071232190"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
contactType 联系类型
userid 员工唯一标识ID

创建用户

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

{
    "userid": "zhangsan",
    "name": "张三",
    "orderInDepts" : "{1:10, 2:20}",
    "department": [1, 2],
    "position": "产品经理",
    "mobile": "15913215421",
    "tel" : "010-123333",
    "workPlace" :"",
    "remark" : "",
    "email": "zhangsan@gzdev.com",
    "orgEmail": "qiye@gzdev.com",
    "jobnumber": "111111",
    "isHide": false,
    "isSenior": false,
    "extattr": {
                "爱好":"旅游",
                "年龄":"24"
                }
}

参数说明

参数
参数类型
必须
说明
access_token
String
调用接口凭证
userid
String
员工唯一标识ID(不可修改),企业内必须唯一。
长度为1~64个字符,如果不传,服务器将自动生成一个userid
name
String
成员名称。
长度为1~64个字符
orderInDepts
JSONObject
在对应的部门中的排序,
Map结构的json字符串, key是部门的Id, value是人员在这个部门的排序值
department
List
数组类型,数组里面值为整型,成员所属部门id列表
position
String
职位信息。
长度为0~64个字符
mobile
String
手机号码,企业内必须唯一,不可重复
tel
String
分机号,长度为0~50个字符,企业内必须唯一,不可重复
workPlace
String
办公地点,长度为0~50个字符
remark
String
备注,长度为0~1000个字符
email
String
邮箱。长度为0~64个字符。企业内必须唯一,不可重复
orgEmail
String
员工的企业邮箱,员工的企业邮箱已开通,才能增加此字段, 否则会报错
jobnumber
String
员工工号。对应显示到OA后台和客户端个人资料的工号栏目。
长度为0~64个字符
isHide
Boolean
是否号码隐藏,
true表示隐藏,
false表示不隐藏
隐藏手机号后,手机号在个人资料页隐藏,但仍可对其发DING、发起钉钉免费商务电话。
isSenior
Boolean
是否高管模式,
true表示是,
false表示不是。
开启后,手机号码对所有员工隐藏。普通员工无法对其发DING、发起钉钉免费商务电话。高管之间不受影响。
extattr
JSONObject
扩展属性,可以设置多种属性
(但手机上最多只能显示10个扩展属性
具体显示哪些属性,请到OA管理后台->设置->通讯录信息设置和OA管理后台->设置->手机端显示信息设置)

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/create");
OapiUserCreateRequest request = new OapiUserCreateRequest();
request.setUserid("zhangsan");
request.setMobile("17700000010");
request.setName("name_test");

// 需要用字符串, "[59869009,60345027]" 这种格式
List<Long> departments = new ArrayList<Long>();
departments.add(100L);
departments.add(200L);
request.setDepartment(JSON.toJSONString(departments));

OapiUserCreateResponse response = client.execute(request, accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "created",
    "userid": "zhangsan"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
userid 员工唯一标识

更新用户

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

{
    "userid": "zhangsan",
    "name": "张三",
    "department": [1, 2],
    "orderInDepts": "{1:10}",
    "position": "产品经理",
    "mobile": "15913215421",
    "tel" : "010-123333",
    "workPlace" :"",
    "remark" : "",
    "email": "zhangsan@gzdev.com",
    "orgEmail": "qiye@gzdev.com",
    "jobnumber": "111111",
    "isHide": false,
    "isSenior": false,
    "extattr": {
                "爱好":"旅游",
                "年龄":"24"
                }
}

参数说明(如果非必须的字段未指定,则钉钉后台不改变该字段之前设置好的值)

参数
参数类型
必须
说明
access_token
String
调用接口凭证
lang
String
通讯录语言
(默认zh_CN另外支持en_US)
userid
String
员工唯一标识ID(不可修改),企业内必须唯一,长度为1~64个字符
name
String
成员名称,长度为1~64个字符
department
List
成员所属部门id列表
orderInDepts
JSONObject
实际是Map的序列化字符串,
Map的Key是deptId,表示部门id,
Map的Value是order,表示排序的值,
列表是按order的倒序排列输出的,即从大到小排列输出的
position
String
职位信息。长度为0~64个字符
mobile
String
手机号码。只有当用户未激活时,才可以更新该字段
tel
String
分机号,长度为0~50个字符
workPlace
String
办公地点,长度为0~50个字符
remark
String
备注,长度为0~1000个字符
email
String
邮箱,长度为0~64个字符,企业内必须唯一
orgEmail
String
员工的企业邮箱,需要确认员工已经开通企业邮箱,否则会报错
jobnumber
String
员工工号,对应显示到OA后台和客户端个人资料的工号栏目,长度为0~64个字符
isHide
Boolean
是否号码隐藏,
true表示隐藏,
false表示不隐藏。
隐藏手机号后,手机号在个人资料页隐藏,但仍可对其发DING、发起钉钉免费商务电话
isSenior
Boolean
是否高管模式,
true表示是,
false表示不是。
开启后,手机号码对所有员工隐藏。普通员工无法对其发DING、发起钉钉免费商务电话。高管之间不受影响
extattr
JSONObject
扩展属性,可以设置多种属性
(但手机上最多只能显示10个扩展属性
具体显示哪些属性,请到OA管理后台->设置->通讯录信息设置和OA管理后台->设置->手机端显示信息设置)

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/update");
OapiUserUpdateRequest request = new OapiUserUpdateRequest();
request.setUserid("zhangsan");
request.setName("name_test");

OapiUserUpdateResponse response = client.execute(request, accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "updated"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容

删除用户

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

参数 参数类型 必须 说明
access_token String 调用接口凭证
userid String 员工唯一标识ID(不可修改)

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/delete");
OapiUserDeleteRequest request = new OapiUserDeleteRequest();
request.setUserid("zhangsan");
request.setHttpMethod("GET");

OapiUserDeleteResponse response = client.execute(request, accessToken);

返回结果

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