文档中心 > 通讯录管理

ISV(应用服务商)默认没有其他企业的管理通讯录的权限,企业开发者默认拥有所在企业的所有通讯录权限。

调用通讯录管理权限的准备工作

如果你是企业内部开发者(企业应用开发),准备工作如下:

1)在开发者后台获取CorpSecret信息。

2)通过企业的CorpId 和 CorpSecret信息换取access_token信息。

3)查询CorpSecret的按部门授权范围

如果你是ISV(应用服务商)开发者,准备工作如下:

1.登录钉钉开发者平台,点击顶部“入驻|登录”,若还未注册企业团队(且完成认证)的钉钉号,请点击入驻。若已完成认证,请点击“登录”(钉钉扫码)进入开发者后台。在左侧「成为服务商」,选择「应用服务商」,填写申请信息。钉钉小二会在5个工作日内审核,审核结果会通过钉钉小秘书发送给申请人。

2.通过审批后,会将申请人加入服务商沟通组织,在该组织的审批应用中发起“通讯录权限申请”。

3.将自己公司开发的微应用部署到钉钉云上,具体的上云步骤可查看钉钉云相关文档,按步骤完成。点击查看

4.钉钉的安全审核人员会审核微应用在钉钉云上的部署状态,审核通过后2个工作日之内,工作人员会开通该微应用的通讯录接口权限。

注意:ISV(应用服务商)所获取到的通讯录权限仅包括数据获取权限,不包括数据提交权限。 钉钉审核通过后,之前已经开通套件应用的企业,需要先解除该企业的授权,再重新授权,之后再次获取的corptoken才具备访问通讯录的能力。

获取成员详情

通过CorpId+userId,可以在一个企业内唯一标记一个用户,通过免登授权接口可以获取到当前用户的UserId信息。

请求说明

Https请求方式: GET

https://oapi.dingtalk.com/user/get?access_token=ACCESS_TOKEN&userid=zhangsan

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

返回结果

{
	"errcode": 0,
	"unionid": "PiiiPyQqBNBii0HnCJ3zljcuAiEiE",
	"openId": "PiiiPyQqBNBii0HnCJ3zljcuAiEiE",
	"roles": [{
		"id": 23003585,
		"name": "财务",
		"groupName": "职务"
	}],
	"remark": "备注",
	"userid": "04232334556237185",
	"isLeaderInDepts": "{1:false}",
	"isBoss": false,
	"hiredDate": 1520265600000,
	"isSenior": false,
	"tel": "010-88996533",
	"department": [1,2],
	"workPlace": "北京市朝阳区",
	"email": "ceshi@aliyun.com",
	"orderInDepts": "{1:71738366882504}",
	"mobile": "15901516821",
	"errmsg": "ok",
	"active": false,
	"avatar": "dingtalk.com/abc.jpg",
	"isAdmin": false,
	"isHide": false,
	"jobnumber": "001",
	"name": "测试名字",
	"extattr": {},
	"stateCode": "86",
	"position": "总监"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
userid 员工唯一标识ID(不可修改)
openId 在本 服务窗运营服务商 范围内,唯一标识关注者身份的id(不可修改)
name 成员名称
tel 分机号(仅限企业内部开发调用)
workPlace 办公地点(ISV不可见)
remark 备注(ISV不可见)
mobile 手机号码(ISV不可见)
email 员工的电子邮箱(ISV不可见)
orgEmail 员工的企业邮箱,如果员工已经开通了企业邮箱,接口会返回,否则不会返回(ISV不可见)
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 入职时间
jobnumber 员工工号
extattr 扩展属性,可以设置多种属性(但手机上最多只能显示10个扩展属性,具体显示哪些属性,请到OA管理后台->设置->通讯录信息设置和OA管理后台->设置->手机端显示信息设置)
roles 角色信息(ISV不可见),json数组格式
roles.id 角色id(ISV不可见)
stateCode 手机号码区号
isSenior 是否是高管
roles.name 角色名称(ISV不可见)
roles.groupName 角色分组名称(ISV不可见)

创建成员

请求说明 【ISV默认无调用权限

如果你是ISV(应用服务商,将开发的应用上架到钉钉应用市场,提供给钉钉其他企业用户使用),则默认无调用权限
如果你是企业内部开发者(将自己公司的HR、OA、客户管理、业务管理等系统接入钉钉),则有权限调用
本接口属高权限接口,调用会被严格限制。请管理员在调用前完成个人实名认证,或者提交企业认证,人数上限将自动扩充。

请求说明

Https请求方式: POST

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管理后台->设置->手机端显示信息设置)

返回结果

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

更新成员

请求说明 【ISV默认无调用权限

如果你是ISV(应用服务商,将开发的应用上架到钉钉应用市场,提供给钉钉其他企业用户使用),则默认无调用权限
如果你是企业内部开发者(将自己公司的HR、OA、客户管理、业务管理等系统接入钉钉),则有权限调用
Https请求方式: POST

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管理后台->设置->手机端显示信息设置)

返回结果

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

删除成员

请求说明 【ISV默认无调用权限

如果你是ISV(应用服务商,将开发的应用上架到钉钉应用市场,提供给钉钉其他企业用户使用),则默认无调用权限
如果你是企业内部开发者(将自己公司的HR、OA、客户管理、业务管理等系统接入钉钉),则有权限调用
Https请求方式: GET

https://oapi.dingtalk.com/user/delete?access_token=ACCESS_TOKEN&userid=ID

参数说明

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

返回结果

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

批量删除成员

请求说明 【ISV默认无调用权限

如果你是ISV(应用服务商,将开发的应用上架到钉钉应用市场,提供给钉钉其他企业用户使用),则默认无调用权限
如果你是企业内部开发者(将自己公司的HR、OA、客户管理、业务管理等系统接入钉钉),有权限调用
Https请求方式: POST

https://oapi.dingtalk.com/user/batchdelete?access_token=ACCESS_TOKEN

请求包结构

{
   "useridlist":["zhangsan","lisi"]
}

参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证
useridlist List 员工UserID列表。列表长度在1到20之间

返回结果

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

获取部门成员

请求说明 【ISV默认无调用权限

如果你是ISV(应用服务商,将开发的应用上架到钉钉应用市场,提供给钉钉其他企业用户使用),则默认无调用权限
如果你是企业内部开发者(将自己公司的HR、OA、客户管理、业务管理等系统接入钉钉),则有权限调用
Https请求方式: GET

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代表用户定义(未定义时按照拼音)排序

返回结果

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

获取部门成员(详情)

请求说明 【ISV默认无调用权限

如果你是ISV(应用服务商,将开发的应用上架到钉钉应用市场,提供给钉钉其他企业用户使用),则默认无调用权限
如果你是企业内部开发者(将自己公司的HR、OA、客户管理、业务管理等系统接入钉钉),则有权限调用
Https请求方式: GET

https://oapi.dingtalk.com/user/list?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代表用户定义(未定义时按照拼音)排序

返回结果

{
    "errcode": 0,
    "errmsg": "ok",
    "hasMore": false,
    "userlist":[
        {
            "userid": "zhangsan",
	    "unionid": "PiiiPyQqBNBii0HnCJ3zljcuAiEiE",
            "mobile": "13122222222",
            "tel" : "010-123333",
            "workPlace" :"",
            "remark" : "",
            "order" : 1,
            "isAdmin": true,
            "isBoss": false,
            "isHide": true,
            "isLeader": true,
            "name": "张三",
            "active": true,
            "department": [1, 2],
            "position": "工程师",
            "email": "zhangsan@alibaba-inc.com",
            "avatar":  "./dingtalk/abc.jpg",
            "jobnumber": "111111",
            "extattr": {
                "爱好":"旅游",
                "年龄":"24"
                }
        }
    ]
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
hasMore 在分页查询时返回,代表是否还有下一页更多数据
userlist 成员列表
userid 员工唯一标识ID(不可修改)
order 表示人员在此部门中的排序,列表是按order的倒序排列输出的,即从大到小排列输出的(OA后台里面调整了顺序的话order才有值)
unionid 在当前isv全局范围内唯一标识一个用户的身份,用户无法修改
mobile 手机号(ISV不可见)
tel 分机号(ISV不可见)
workPlace 办公地点(ISV不可见)
remark 备注(ISV不可见)
isAdmin 是否是企业的管理员, true表示是, false表示不是
isBoss 是否为企业的老板, true表示是, false表示不是 (不能通过接口设置,可以通过OA后台设置
isHide 是否隐藏号码, true表示是, false表示不是
isLeader 是否是部门的主管, true表示是, false表示不是
name 成员名称
active 表示该用户是否激活了钉钉
department 成员所属部门id列表
position 职位信息
email 员工的邮箱
orgEmail 员工的企业邮箱,如果员工的企业邮箱没有开通,返回信息中不包含
avatar 头像url
jobnumber 员工工号
hiredDate 入职时间
extattr 扩展属性,可以设置多种属性(但手机上最多只能显示10个扩展属性,具体显示哪些属性,请到OA管理后台->设置->通讯录信息设置和OA管理后台->设置->手机端显示信息设置)

获取管理员列表

Https请求方式: GET

https://oapi.dingtalk.com/user/get_admin?access_token=ACCESS_TOKEN

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

返回结果

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

获取管理员的微应用管理权限

如果你是ISV(应用服务商,将开发的应用上架到钉钉应用市场,提供给其他企业用户使用),则只能查询自身的微应用的权限

Https请求方式: GET

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

返回结果

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

根据unionid获取成员的userid

请求说明

Https请求方式: GET

https://oapi.dingtalk.com/user/getUseridByUnionid?access_token=ACCESS_TOKEN&unionid=xxxxxx

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

返回结果

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

FAQ

关于此文档暂时还没有FAQ
返回
顶部