开发者注册
目前钉钉开发者平台,仅支持有企业资质开发者注册
注册成为钉钉企业开发者
已有钉钉企业管理员账号, 立即登录
文档中心 > 通讯录管理

ISV(应用服务商)默认无管理通讯录的权限,企业应用默认有所有通讯录权限。

ISV通讯录权限获取流程:

isv_flow

ISV开发微应用的时候如果必须要使用到企业通讯录,请按照如上流程进行申请:
1.发送邮件到open-dingtalk@list.alibaba-inc.com 提交申请,申请之后3个工作日之内会有我们的商务联系你们进行对接。发送邮件的时候请写明:appId、所属公司、应用的使用场景(详细)、应用的功能模块描述(详细)、联系人手机号等信息。
2.将自己公司开发的微应用部署到聚石塔上,具体的上塔步骤请参考:https://open-doc.dingtalk.com/docs/doc.htm?docType=1&articleId=106046。
3.将聚石塔上塔的淘宝账号、公司、appId、联系人手机号等信息发送邮件到open-dingtalk@list.alibaba-inc.com 提交聚石塔资源审核。
4.审核完成后2个工作日之内,工作人员会开通该微应用的通讯录接口权限。

注意:ISV所获取到的通讯录权限仅包括数据拉取权限,不包括数据提交权限。

获取成员详情

请求说明

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,
    "errmsg": "ok",
    "userid": "zhangsan",
    "name": "张三",
    "tel" : "010-123333",
    "workPlace" :"",
    "remark" : "",
    "mobile" : "13800000000",
    "email" : "dingding@aliyun.com",
    "active" : true,
    "orderInDepts" : "{1:10, 2:20}",
    "isAdmin" : false,
    "isBoss" : false,
    "dingId" : "WsUDaq7DCVIHc6z1GAsYDSA",
    "unionid" : "cdInjDaq78sHYHc6z1gsz",
    "isLeaderInDepts" : "{1:true, 2:false}",
    "isHide" : false,
    "department": [1, 2],
    "position": "工程师",
    "avatar": "dingtalk.com/abc.jpg",
    "jobnumber": "111111",
    "extattr": {
                "爱好":"旅游",
                "年龄":"24"
                },
    "roles":[
        {
             "id":123,
             "name":"总监",
             "groupName":"职务"
        }
    ]
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
userid 员工唯一标识ID(不可修改)
name 成员名称
tel 分机号(ISV不可见)
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表示不是(不能通过接口设置,可以通过OA后台设置
dingId 钉钉Id,在钉钉全局范围内标识用户的身份,但用户可以自行修改一次
unionid 在当前isv全局范围内唯一标识一个用户的身份,用户无法修改
isLeaderInDepts 在对应的部门中是否为主管, Map结构的json字符串, key是部门的Id, value是人员在这个部门中是否为主管, true表示是, false表示不是
isHide 是否号码隐藏, true表示隐藏, false表示不隐藏
department 成员所属部门id列表
position 职位信息
avatar 头像url
jobnumber 员工工号
extattr 扩展属性,可以设置多种属性(但手机上最多只能显示10个扩展属性,具体显示哪些属性,请到OA管理后台->设置->通讯录信息设置和OA管理后台->设置->手机端显示信息设置)
roles 角色信息(ISV不可见),json数组格式
roles.id 角色id(ISV不可见)
roles.name 角色名称(ISV不可见)
roles.groupName 角色分组名称(ISV不可见)

创建成员

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

本接口属高权限接口,调用会被严格限制。请管理员在调用前完成个人实名认证,或者提交企业认证,人数上限将自动扩充。

请求说明

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",
    "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个字符。企业内必须唯一
jobnumber String 员工工号。对应显示到OA后台和客户端个人资料的工号栏目。长度为0~64个字符
isHide Boolean 是否号码隐藏, true表示隐藏, false表示不隐藏。隐藏手机号后,手机号在个人资料页隐藏,但仍可对其发DING、发起钉钉免费商务电话。
isSenior Boolean 是否高管模式,true表示是,false表示不是。开启后,手机号码对所有员工隐藏。普通员工无法对其发DING、发起钉钉免费商务电话。高管之间不受影响。
extattr JSONObject 扩展属性,可以设置多种属性(但手机上最多只能显示10个扩展属性,具体显示哪些属性,请到OA管理后台->设置->通讯录信息设置和OA管理后台->设置->手机端显示信息设置)

返回结果

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

更新成员

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

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",
    "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个字符。企业内必须唯一
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默认无调用权限

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默认无调用权限

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默认无调用权限

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默认无调用权限

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",
            "dingId": "dwdded",
            "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的倒序排列输出的,即从大到小排列输出的
dingId 钉钉ID
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 员工工号
extattr 扩展属性,可以设置多种属性(但手机上最多只能显示10个扩展属性,具体显示哪些属性,请到OA管理后台->设置->通讯录信息设置和OA管理后台->设置->手机端显示信息设置)

获取管理员列表

Https请求方式: GET

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

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

返回结果

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

根据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",
    "userid": "zhangsan"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
userid 员工唯一标识ID(不可修改)

FAQ

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