Get user details - DingTalk Help Center

Call this API to get the details of a specified user.

API call description

This API lets you query the details of a regular account user or an Enterprise Account user. Because parameter usage differs significantly between the two scenarios, the documentation is split by account type for easier reference:

To query the details of a regular account user, refer to this article.
To query the details of an Enterprise Account user, see Get the details of an Enterprise Account user.

If you need to obtain permissions for fields such as phone number and mail, the method varies by App type.

For an Internal app to obtain a user’s phone number and mail, add the permission to access phone numbers and mail in Contacts. To add the permission: Sign in to the DingTalk Developer Console > Internal Development > find the app to which you want to add the permission > Manage permissions > Contacts Management. Select Employee phone number and Mail and other Profile information, and click Request permission.
For a Third-party enterprise app to obtain a user’s phone number and mail, use the DingTalk unified authorization suite.

Request

Basic information
HTTP URL	https://oapi.dingtalk.io/topapi/v2/user/get
HTTP Method	POST
Supported app types	appType-Internal app, appType-Third-party enterprise app
Permission requirements	permission-qyapi_get_member-User information read permission

Query parameters

Name	Type	Required	Example	Description
access_token	String	Yes	bE74xxxx	App credential used to call this API. - For an Internal app, get it through the API for obtaining the access_token of an Internal app. - For a Third-party enterprise app, get it through the API for obtaining the access_token of a third-party enterprise.

Request body

Name	Type	Required	Example	Description
userid	String	Yes	manager4220	The userid of the user.
language	String	No	zh_CN	The Contacts language. - zh_CN: Chinese (Default) - en_US: English

Request example

curl -X POST "https://oapi.dingtalk.io/topapi/v2/user/get" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=b97a231d-7dd8-4243-ac4e-6b75b2a1e28a' \
-d 'language=zh_CN' \
-d 'userid=zhangsan'

Java

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/v2/user/get");
OapiV2UserGetRequest req = new OapiV2UserGetRequest();
req.setUserid("001");
req.setLanguage("zh_CN");
OapiV2UserGetResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());

Python

import dingtalk.api

req=dingtalk.api.OapiV2UserGetRequest("https://oapi.dingtalk.io/topapi/v2/user/get")

req.userid="zhangsan"
req.language="zh_CN"
try:
	resp= req.getResponse(access_token)
	print(resp)
except Exception,e:
	print(e)

PHP

include "TopSdk.php";
date_default_timezone_set('Asia/Shanghai');

$c = new DingTalkClient(DingTalkConstant::$CALL_TYPE_OAPI, DingTalkConstant::$METHOD_POST , DingTalkConstant::$FORMAT_JSON);
$req = new OapiV2UserGetRequest;
$req->setUserid("zhangsan");
$req->setLanguage("zh_CN");
$resp = $c->execute($req, $access_token, "https://oapi.dingtalk.io/topapi/v2/user/get");

IDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/v2/user/get");
OapiV2UserGetRequest req = new OapiV2UserGetRequest();
req.Userid = "zhangsan";
req.Language = "zh_CN";
OapiV2UserGetResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

Response

Response body

Name	Type	Example	Description
request_id	String	4e7exhl6pm0t	The request ID.
errcode	Number	0	The return code.
errmsg	String	ok	The description of the return code.
result	Object		The returned result.
userid	String	zhangsan	The userid of the Employee.
unionid	String	z21HjQliSzpw0YWCNxmii6u2Os62cZ62iSZ	The unique identifier of the Employee within the current developer enterprise account scope.
name	String	John	The Employee’s Name.
avatar	String	xxx	Profile Photo. Note If the Employee uses the default Profile Photo, this field is not returned. It is returned only when the Profile Photo is set manually.
state_code	String	86	The international country calling code. Note This field is not returned for a Third-party enterprise app. To obtain state_code, use the DingTalk unified authorization suite.
manager_userid	String	user01	The Employee’s direct manager. Note This field is returned only when the Direct Manager field on the Employee’s Profile panel in the enterprise admin console has a value.
mobile	String	13800138000	The phone number. Note - For an Internal app, this field is returned only when the App has been granted the Employee phone number permission in Contacts. - This field is not returned for a Third-party enterprise app. To obtain mobile, use the DingTalk unified authorization suite.
hide_mobile	Boolean	false	Whether the phone number is hidden: - true: hidden - false: not hidden Note When the phone number is hidden, it is hidden on the Profile page, but you can still send DING messages and initiate Free DingTalk business calls to it.
telephone	String	010-86123456-2345	The extension number. Note This parameter is not returned for a Third-party enterprise app.
job_number	String	4	The Employee ID.
title	String	Technical Director	The Job Title.
email	String	test@xxx.com	The Employee’s Mail. Note - For an Internal app, this field is returned only when the App has been granted the Mail and other Profile information permission in Contacts. - This parameter is not returned for a Third-party enterprise app. To obtain email, use the DingTalk unified authorization suite.
work_place	String	Future Park	The Work Location. Note - This field is returned only when it has a value on the Employee Profile panel. If empty, the field is not returned. - For an Internal app, this field is returned only when the App has been granted the Mail and other Profile information permission in Contacts. - This parameter is not returned for a Third-party enterprise app.
remark	String	Remark	The Alias. Note - This field is returned only when it has a value on the Employee Profile panel. If empty, the field is not returned. - For an Internal app, this field is returned only when the App has been granted the Mail and other Profile information permission in Contacts. - This parameter is not returned for a Third-party enterprise app.
exclusive_account	Boolean	false	Whether the user is an Enterprise Account: - true: yes - false: no
org_email	String	test@xxx.com	The Employee’s Enterprise Mail. If the Employee’s Enterprise Mail is not enabled, this data is not included in the response. Note This parameter is not returned for a Third-party enterprise app.
dept_id_list	Number[]	[2,3,4]	The list of department IDs the Employee belongs to.
dept_order_list	Object[]		The Employee’s Sort order within each Department.
dept_id	Number	2	The department ID.
order	Number	1	The Employee’s Sort order within the Department.
extension	String	`{"Hobby":"Travel","Age":"24"}`	Extended Attributes, up to 2000 characters in length. Note - Returned only when an extended Field added on the Employee Profile panel has a value. - For an Internal app, this field is returned only when the App has been granted the Mail and other Profile information permission in Contacts. - This field is not returned for a Third-party enterprise app. - Important: Adding a new Attribute directly overwrites existing Attribute values. First fetch the existing Attributes, append the new Attribute, and then perform a full Update.
hired_date	Number	1597573616828	The hire date. A Unix timestamp in milliseconds. Note - Returned only when the Hire Date field on the Profile panel has a value. - This parameter is not returned for a Third-party enterprise app.
active	Boolean	true	Whether DingTalk has been activated: - true: activated - false: not activated
real_authed	Boolean	true	Whether real-name Authentication is completed: - true: verified - false: not verified
senior	Boolean	true	Whether the Employee is an Organization executive: - true: yes - false: no
admin	Boolean	true	Whether the Employee is an Organization Admin: - true: yes - false: no
boss	Boolean	true	Whether the Employee is the Organization boss: - true: yes - false: no
leader_in_dept	Object[]		The Employee’s Department information and whether the Employee is a leader: - The Department ID of the Department the Employee belongs to. - Whether the Employee is a leader in the corresponding Department: - true: yes - false: no
dept_id	Number	2	The Department ID.
leader	Boolean	true	Whether the Employee is a leader: - true: yes - false: no
role_list	Object[]		The Role List.
id	Number	100	The Role ID.
name	String	Director	The Role Name.
group_name	String	Position	The role group Name.
union_emp_ext	Object		Association information when the user comes from an associated Organization. Note This field is returned when the Organization the user belongs to has an Association relationship with another Organization.
userid	String	500	The Employee’s userid.
union_emp_map_list	Object[]		The Association mapping.
userid	String	5000	The userid of the Employee in the associated branch Organization.
corp_id	String	dingxxx	The corpId of the associated branch Organization.
corp_id	String	dingxxx	The corpId of the Organization the current user belongs to.
dept_position_list	DeptPosition[]		Position information within the Department.
extension_i18n	Json	`{"Hobby": {"zh_CN": "旅游", "en_US": "travel", "aJP": "旅行"}}`	Internationalized values of the extended Attributes.

Response body example

{
  "errcode":"0",
  "result":{
    "extension":"{\"Hobby\":\"Travel\",\"Age\":\"24\"}",
    "unionid":"z21HjQliSzpw0YWxxxxx",
    "boss":"true",
    "role_list":{
      "group_name":"Position",
      "name":"Director",
      "id":"100"
    },
    "exclusive_account":false,
    "manager_userid":"manager240",
    "admin":"true",
    "remark":"Remark",
    "title":"Technical Director",
    "hired_date":"1597573616828",
    "userid":"zhangsan",
    "work_place":"Future Park",
    "dept_order_list":{
      "dept_id":"2",
      "order":"1"
    },
    "real_authed":"true",
    "dept_id_list":"[2,3,4]",
    "job_number":"4",
    "email":"test@xxx.com",
    "leader_in_dept":{
      "leader":"true",
      "dept_id":"2"
    },
    "mobile":"13800138000",
    "active":"true",
    "org_email":"test@xxx.com",
    "telephone":"010-86123456-2345",
    "avatar":"xxx",
    "hide_mobile":"false",
    "senior":"true",
    "name":"John",
    "union_emp_ext":{
      "union_emp_map_list":{
        "userid":"5000",
        "corp_id":"dingxxx"
      },
      "userid":"500",
      "corp_id":"dingxxx"
    },
    "state_code":"86"
  },
  "errmsg":"ok"
}

Error codes

If the API call returns an Error, look up the solution by error message in the Global error codes documentation.

Error code (errcode)	Error code description (errmsg)	Solution
33012	Invalid userid	Check whether the userid is correct.
400002	Invalid parameter	Check whether the parameter is entered as required.
-1	System busy	Try again Later.

​API call description

​Request

​Query parameters

​Request body

​Request example

​Response

​Response body

​Response body example

​Error codes