钉钉开发文档

用户管理

更新时间: 2019-7-18

创建用户

请求方式: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": "1xxxxxxxxxx",
    "tel" : "xxxx-xxxxxxxx",
    "workPlace" :"",
    "remark" : "",
    "email": "test@xxx.com",
    "orgEmail": "test@xxx.com",
    "jobnumber": "xxx",
    "isHide": false,
    "isSenior": false,
    "extattr": {
                "爱好":"旅游",
                "年龄":"24"
                }
}

参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证
userid String 员工在当前企业内的唯一标识,也称staffId。可由企业在创建时指定,并代表一定含义比如工号,创建后不可修改,企业内必须唯一。
长度为1~64个字符,如果不传,服务器将自动生成一个userid。
name String 成员名称。
长度为1~64个字符
orderInDepts JSONObject 在对应的部门中的排序,
Map结构的json字符串, key是部门的Id, value是人员在这个部门的排序值
department List 数组类型,数组里面值为整型,成员所属部门id列表
position String 职位信息。
长度为0~64个字符
mobile String 手机号码,企业内必须唯一,不可重复。如果是国际号码,请使用+xx-xxxxxx的格式
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管理后台->设置->手机端显示信息设置)
hiredDate Number 入职时间,Unix时间戳

SDK请求示例(JAVA)

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

// 需要用字符串, "[100,200]" 这种格式
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": "ok",
    "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": "1xxxxxxxxxx",
    "tel" : "xxxx-xxxxxxxx",
    "workPlace" :"",
    "remark" : "",
    "email": "test@xxx.com",
    "orgEmail": "test@xxx.com",
    "jobnumber": "xxx",
    "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管理后台->设置->手机端显示信息设置)
hiredDate Number 入职时间,Unix时间戳

SDK请求示例(JAVA)

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

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

返回结果

{
    "errcode": 0,
    "errmsg": "ok"
}
参数 说明
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": "ok"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容

获取用户详情

如果您想调用通讯录接口并同时获取员工手机号,请先参考通讯录权限说明,设置下通讯录接口权限和手机号等敏感字段权限

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

参数 参数类型 必须 说明
access_token String 调用接口凭证
userid String 员工id
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,
    "unionid": "PiiiPyQqBNBii0HnCJ3zljcuAiEiE",
    "remark": "remark",
    "userid": "zhangsan",
    "isLeaderInDepts": "{1:false}",
    "isBoss": false,
    "hiredDate": 1520265600000,
    "isSenior": false,
    "tel": "xxx-xxxxxxxx",
    "department": [1,2],
    "workPlace": "place",
    "email": "test@xxx.com",
    "orderInDepts": "{1:71738366882504}",
    "mobile": "1xxxxxxxxxx",
    "errmsg": "ok",
    "active": false,
    "avatar": "xxx",
    "isAdmin": false,
    "isHide": false,
    "jobnumber": "001",
    "name": "张三",
    "extattr": {},
    "stateCode": "86",
    "position": "manager",
    "roles": [
        {
            "id": 149507744,
            "name": "总监",
            "groupName": "职务"
        }
    ]
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
userid 员工在当前企业内的唯一标识,也称staffId。可由企业在创建时指定,并代表一定含义比如工号,创建后不可修改
unionid 员工在当前开发者企业账号范围内的唯一标识,系统生成,固定值,不会改变
name 员工名字
tel 分机号(仅限企业内部开发调用)
workPlace 办公地点
remark 备注
mobile 手机号码
email 员工的电子邮箱
orgEmail 员工的企业邮箱,如果员工已经开通了企业邮箱,接口会返回,否则不会返回
active 是否已经激活,true表示已激活,false表示未激活
orderInDepts 在对应的部门中的排序,Map结构的json字符串,key是部门的Id,value是人员在这个部门的排序值
isAdmin 是否为企业的管理员,true表示是,false表示不是
isBoss 是否为企业的老板,true表示是,false表示不是
isLeaderInDepts 在对应的部门中是否为主管:Map结构的json字符串,key是部门的Id,value是人员在这个部门中是否为主管,true表示是,false表示不是
isHide 是否号码隐藏,true表示隐藏,false表示不隐藏
department 成员所属部门id列表
position 职位信息
avatar 头像url
hiredDate 入职时间。Unix时间戳 (在OA后台通讯录中的员工基础信息中维护过入职时间才会返回)
jobnumber 员工工号
extattr 扩展属性,可以设置多种属性(但手机上最多只能显示10个扩展属性,具体显示哪些属性,请到OA管理后台->设置->通讯录信息设置和OA管理后台->设置->手机端显示信息设置)
isSenior 是否是高管
stateCode 国家地区码
roles 用户所在角色列表
└ id 角色id
└ name 角色名称
└ groupName 角色组名称

获取部门用户userid列表

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

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

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

SDK请求示例(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 long 支持分页查询,与offset参数同时设置时才生效,此参数代表分页大小,最大100
order String 支持分页查询,部门成员的排序规则,默认不传是按自定义排序;
entry_asc:代表按照进入部门的时间升序,
entry_desc:代表按照进入部门的时间降序,
modify_asc:代表按照部门信息修改时间升序,
modify_desc:代表按照部门信息修改时间降序,
custom:代表用户定义(未定义时按照拼音)排序

SDK请求示例(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参数同时设置时才生效,此参数代表偏移量,偏移量从0开始
size long 支持分页查询,与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",
            "mobile": "1xxxxxxxxxx",
            "tel" : "xxxx-xxxxxxxx",
            "workPlace" :"",
            "remark" : "",
            "order" : 1,
            "isAdmin": true,
            "isBoss": false,
            "isHide": true,
            "isLeader": true,
            "name": "张三",
            "active": true,
            "department": [1, 2],
            "position": "工程师",
            "email": "test@xxx.com",
            "avatar":  "xxx",
            "jobnumber": "xxx",
            "extattr": {
                "爱好":"旅游",
                "年龄":"24"
                }
        }
    ]
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
hasMore 在分页查询时返回,代表是否还有下一页更多数据
userlist 成员列表
userid 员工在当前企业内的唯一标识,也称staffId。可由企业在创建时指定,并代表一定含义比如工号,创建后不可修改
unionid 员工在当前开发者企业账号范围内的唯一标识,系统生成,固定值,不会改变
order 表示人员在此部门中的排序,列表是按order的倒序排列输出的,即从大到小排列输出的
钉钉管理后台里面调整了顺序的话order才有值
mobile 手机号
tel 分机号
workPlace 办公地点
remark 备注
isAdmin 是否是企业的管理员,true表示是,false表示不是
isBoss 是否为企业的老板,true表示是,false表示不是
isHide 是否隐藏号码,true表示是,false表示不是
isLeader 是否是部门的主管,true表示是,false表示不是
name 成员名称
active 表示该用户是否激活了钉钉
department 成员所属部门id列表
position 职位信息
email 员工的邮箱
orgEmail 员工的企业邮箱,如果员工的企业邮箱没有开通,返回信息中不包含
avatar 头像url
jobnumber 员工工号
hiredDate 入职时间
extattr 扩展属性,可以设置多种属性(但手机上最多只能显示10个扩展属性,具体显示哪些属性,请到OA管理后台->设置->通讯录信息设置和OA管理后台->设置->手机端显示信息设置)
stateCode 国家地区码

获取管理员列表

请求方式: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":"userid2"},
        {"sys_level":1,"userid":"userid1"}
    ]
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
sys_level 管理员角色,1:主管理员,2:子管理员
userid 员工id

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

请求方式: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("userid1");
OapiUserGetAdminScopeResponse rsp = client.execute(req, accessToken);

返回结果

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

根据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": "userid1"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
contactType 联系类型,0表示企业内部员工,1表示企业外部联系人
userid 员工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 企业员工数量
以上内容是否对您有帮助:
在文档使用中是否遇到以下问题(多选):
  • 内容错误
  • 更新不及时
  • 链接错误
  • 缺少代码/图片示例
  • 太简单/步骤待完善
手机号
更多建议
提交成功,感谢您的反馈!