查询用户详情

POST

https://oapi.dingtalk.com/topapi/v2/user/get

调用本接口获取指定用户的详细信息。

说明

调用本接口可以实现查询普通账号用户详情或查询企业账号用户详情。由于在调用时参数使用有较多区别，为便于开发者查看，按照新用户的账号类型进行拆分优化：

查询普通账号用户详情，接口说明文档请查看本文介绍。

查询企业账号用户详情，接口说明文档请参见查询企业账号用户详情。

权限

添加接口权限

服务端API是以应用维度授权的，在调用接口前，确保已经为应用添加了接口权限。

应用类型	是否支持调用	权限申请方式	API Explorer调试
企业内部应用	是	成员信息读权限	调试
第三方企业应用	是	成员信息读权限	调试
第三方个人应用	否	—	—

添加获取手机号和邮箱权限

如果需要获取手机号和邮箱等权限，不同的应用类型获取方式不同。

企业内部应用

企业内部应用如需获取用户的手机号、邮箱信息，需要添加获取通讯录中手机号和邮箱的权限。添加方法如下：

登录钉钉开发者后台 > 企业内部开发 > 找到需添加权限的应用 > 权限管理 > 通讯录管理页面，勾选企业员工手机号信息和邮箱等个人信息，单击申请权限。

第三方企业应用

第三方企业应用如需获取用户手机号、邮箱信息，可以使用钉钉统一授权套件方式获取。

错误码

错误码（errcode）	错误码描述（errmsg）	解决方案
33012	无效的userId	请检查userId是否正确
400002	无效的参数	请确认参数是否按要求输入
-1	系统繁忙	请稍后再试

请求示例

Shell

JavaScript

Java

Swift

curl --location --request POST 'https://oapi.dingtalk.com/topapi/v2/user/get?access_token' \
--header 'Content-Type: application/json' \
--data-raw '{
        "language":"zh_CN",
        "userid":"zhangsan"
}'

响应示例

{
    "errcode": "string",
    "result": {
        "extension": "string",
        "unionid": "string",
        "boss": "string",
        "role_list": {
            "group_name": "string",
            "name": "string",
            "id": "string"
        },
        "exclusive_account": true,
        "manager_userid": "string",
        "admin": "string",
        "remark": "string",
        "title": "string",
        "hired_date": "string",
        "userid": "string",
        "work_place": "string",
        "dept_order_list": {
            "dept_id": "string",
            "order": "string"
        },
        "real_authed": "string",
        "dept_id_list": "string",
        "job_number": "string",
        "email": "string",
        "leader_in_dept": {
            "leader": "string",
            "dept_id": "string"
        },
        "mobile": "string",
        "active": "string",
        "org_email": "string",
        "telephone": "string",
        "avatar": "string",
        "hide_mobile": "string",
        "senior": "string",
        "name": "string",
        "union_emp_ext": {
            "union_emp_map_list": {
                "userid": "string",
                "corp_id": "string"
            },
            "userid": "string",
            "corp_id": "string"
        },
        "state_code": "string"
    },
    "errmsg": "string"
}

请求参数

Query 参数

access_token

string

必需

调用该接口的应用凭证。

企业内部应用，通过获取企业内部应用的access_token接口获取。

第三方企业应用，通过获取第三方企业应用的access_token接口获取。

Body 参数application/json

language

string

可选

通讯录语言。 zh_CN：中文（默认值） en_US：英文

userid

string

必需

用户的userId。

示例

返回响应

🟢200成功

application/json

Body

errcode

string

返回码。

必需

result

object

返回结果。

必需

extension

string

必需

扩展属性，最大长度2000个字符。说明员工信息面板中添加的拓展字段内有值才返回。企业内部应用，只有应用开通通讯录邮箱等个人信息权限，才会返回该字段。第三方企业应用，不返回该字段。

unionid

string

必需

员工在当前开发者企业账号范围内的唯一标识。

boss

string

必需

是否为企业的老板： true：是 false：不是

role_list

object

角色列表。

必需

exclusive_account

boolean

必需

是否为企业账号： true：是 false：不是

manager_userid

string

必需

员工的直属主管。说明员工在企业管理后台个人信息面板中，直属主管内有值，才会返回该字段。

admin

string

必需

是否为企业的管理员： true：是 false：不是

remark

string

必需

备注。说明员工信息面板中该字段必须有值，才正常返回。如果无值，则不返回该字段。企业内部应用，只有应用开通通讯录邮箱等个人信息权限，才会返回该字段。第三方企业应用，不返回该参数。

title

string

职位。

必需

hired_date

string

必需

入职时间，Unix时间戳，单位毫秒。说明信息面板中入职时间字段内有值才返回。第三方企业应用，不返回该参数。

userid

string

必需

员工的userId。

work_place

string

必需

办公地点。说明员工信息面板中该字段必须有值，才正常返回。如果无值，则不返回该字段。企业内部应用，只有应用开通通讯录邮箱等个人信息权限，才会返回该字段。第三方企业应用，不返回该参数。

dept_order_list

object

必需

员工在对应的部门中的排序。

real_authed

string

必需

是否完成了实名认证： true：已认证 false：未认证

dept_id_list

string

所属部门id列表。

必需

job_number

string

员工工号。

必需

string

必需

员工邮箱。说明企业内部应用，只有应用开通通讯录邮箱等个人信息权限，才会返回该字段。第三方企业应用，不返回该参数；如需获取email，可以使用钉钉统一授权套件方式获取。

leader_in_dept

object

必需

员工所在部门信息及是否是领导：员工所在部门的部门ID。员工在对应的部门中是否是领导： true：是 false：不是

mobile

string

必需

手机号码。说明企业内部应用，只有应用开通通讯录邮箱等个人信息权限，才会返回该字段。第三方企业应用不返回该字段，如需获取mobile，可以使用钉钉统一授权套件方式获取。

active

string

必需

头像。说明员工使用默认头像，不返回该字段，手动设置头像会返回。

org_email

string

必需

员工的企业邮箱。如果员工的企业邮箱没有开通，返回信息中不包含该数据。说明第三方企业应用不返回该参数。

telephone

string

必需

分机号。说明第三方企业应用不返回该参数。

avatar

string

必需

头像。说明员工使用默认头像，不返回该字段，手动设置头像会返回。

hide_mobile

string

必需

是否号码隐藏： true：隐藏 false：不隐藏说明隐藏手机号后，手机号在个人资料页隐藏，但仍可对其发DING、发起钉钉免费商务电话。

senior

string

必需

是否为企业的高管： true：是 false：不是

name

string

员工姓名。

必需

union_emp_ext

object

必需

当用户来自于关联组织时的关联信息。说明用户所在企业存在关联关系的企业，返回该字段。

state_code

string

必需

国际电话区号。说明第三方企业应用不返回该字段；如需获取state_code，可以使用钉钉统一授权套件方式获取。

errmsg

string

返回码描述。

必需

删除用户

获取部门用户基础信息

查询用户详情

权限#

添加接口权限#

添加获取手机号和邮箱权限#

错误码#

请求参数

返回响应

权限

添加接口权限

添加获取手机号和邮箱权限

错误码