Get details of an Enterprise Account user

Call this API to get the detailed information of a specified Enterprise Account user. This API is only available to organizations that have purchased and enabled Enterprise Account.

API call description

The way to obtain permissions such as mobile number and email differs by app type.

Internal app To obtain a user’s mobile number and email information, an internal app must add the permission to access mobile numbers and emails in Contacts. To add the permission: Sign in to DingTalk Developer Platform > Internal development > find the app that needs the permission > Manage permissions > Contacts management, select Mobile number information of employees and Email and other profile information, then click Request permission.
Third-party enterprise app

Request

Basic information
HTTP URL	https://api.dingtalk.io/topapi/v2/user/get
HTTP Method	POST
Supported app types	appType-Internal app, appType-Third-party enterprise app
Required permissions	permission-qyapi_get_member-Read permission for user information

Query parameters

Name	Type	Required	Example	Description
access_token	String	Yes	be3Fxxxx	The app credential for calling this API. - For an internal app, obtain it through the API for getting the access_token of an internal app. - For a third-party enterprise app, obtain it through the API for getting the access_token of a third-party enterprise.

Request body

Name	Type	Required	Example	Description
userid	String	Yes	manager4220	The user ID of the user.
language	String	No	zh_CN	The language for Contacts. - zh_CN: Chinese (default) - en_US: English
login_id	String	No	test	The sign-in name. When this field is not empty, userid is ignored. Note Querying by sign-in name is only supported for DingTalk-built Enterprise Accounts belonging to your organization.

Request example

curl -X POST "https://api.dingtalk.io/topapi/v2/user/get" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=a894388c-a1b9-4ab4-8623-99cd0502019f' \
-d 'language=zh_CN' \
-d 'login_id=zhangsan' \
-d 'userid=zhangsan'

Java

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

Python

import dingtalk.api

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

req.userid="zhangsan"
req.language="zh_CN"
req.login_id="zhangsan"
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");
$req->setLoginId("zhangsan");
$resp = $c->execute($req, $access_token, "https://api.dingtalk.io/topapi/v2/user/get");

IDingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/v2/user/get");
OapiV2UserGetRequest req = new OapiV2UserGetRequest();
req.Userid = "zhangsan";
req.Language = "zh_CN";
req.LoginId = "zhangsan";
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 user ID of the employee.
unionid	String	z21HjQliSzpw0YWCNxmii6u2Os62cZ62iSZ	The unique identifier of the employee within the current developer’s Enterprise Account scope.
name	String	John	The employee name.
avatar	String	xxx	The profile photo. Note - This field is not returned if the employee uses the default profile photo. - This field is returned if the employee has manually set a profile photo.
state_code	String	86	The international dialing code. Note This field is not returned for third-party enterprise apps. To obtain state_code, use the DingTalk unified authorization suite.
mobile	String	13800138000	The mobile number. Note - If an internal app does not receive this field, check whether the Mobile number information of employees permission is enabled in the Contacts permissions of the current app. - This field is not returned for third-party enterprise apps. To obtain mobile, use the DingTalk unified authorization suite.
hide_mobile	Boolean	false	Whether the mobile number is hidden: - true: hidden - false: not hidden Note After the mobile number is hidden, it is hidden on the Profile page, but you can still send DING messages and initiate DingTalk business calls to the user.
telephone	String	010-86123456-2345	The extension number. Note This field is not returned for third-party enterprise apps.
job_number	String	4	The employee ID.
title	String	Technical Director	The job title.
email	String	test@xxx.com	The employee mail. Note - If an internal app does not receive this field, check whether the Email and other profile information permission is enabled in the Contacts permissions of the current app. - This field is not returned for third-party enterprise apps. To obtain email, use the DingTalk unified authorization suite.
org_email	String	test@xxx.com	The Enterprise Mail of the employee. This data is not included in the response if the employee’s Enterprise Mail is not activated. Note This field is not returned for third-party enterprise apps.
work_place	String	Future Park	The work location. Note - If an internal app does not receive this field, check whether the Email and other profile information permission is enabled in the Contacts permissions of the current app. - This field is returned only when there is a value in this field on the employee information panel. - This field is not returned for third-party enterprise apps.
remark	String	Remark	The alias. Note - If an internal app does not receive this field, check whether the Email and other profile information permission is enabled in the Contacts permissions of the current app. - This field is returned only when there is a value in this field on the employee information panel. - This field is not returned for third-party enterprise apps.
dept_id_list	Number[]	[2,3,4]	The list of department IDs the employee belongs to.
dept_order_list	Object[]		The sort order of the employee in each department.
dept_id	Number	2	The department ID.
order	Number	1	The sort order of the employee in the department.
extension	String	`{"Hobby":"Travel","Age":"24"}`	The extended attributes. The maximum length is 2,000 characters. Note - If an internal app does not receive this field, check whether the Email and other profile information permission is enabled in the Contacts permissions of the current app. - This field is returned only when the extended fields added on the employee information panel contain values. - This field is not returned for third-party enterprise apps.
hired_date	Number	1597573616828	The hire date, as a Unix timestamp in milliseconds. Note - This field is not returned for third-party enterprise apps. - This field is returned only when the Hire date field on the information panel has a value.
active	Boolean	true	Whether DingTalk has been activated: - true: activated - false: not activated
real_authed	Boolean	true	Whether real-name authentication has been completed: - true: authenticated - false: not authenticated
senior	Boolean	true	Whether the user is a senior executive of the organization: - true: yes - false: no
admin	Boolean	true	Whether the user is an admin of the organization: - true: yes - false: no
boss	Boolean	true	Whether the user is the boss of the organization: - true: yes - false: no
leader_in_dept	Object[]		The information about the departments the employee belongs to and whether the employee is a leader in each: - 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 user 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.
exclusive_account	Boolean	true	Whether the user is an Enterprise Account: - true: yes - false: no
union_emp_ext	Object		The association information when the user is from an associated organization. Note This field is returned when the user’s organization has associated organizations.
userid	String	500	The user ID of the employee.
union_emp_map_list	Object[]		The association mapping.
userid	String	5000	The user ID of the employee in the associated branch organization.
corp_id	String	dingxxx	The corp ID of the associated branch organization.
corp_id	String	dingxxx	The corp ID of the organization the current user belongs to.
exclusive_account_type	String	dingtalk	The Enterprise Account type: - sso: self-built Enterprise Account of the organization - dingtalk: DingTalk-built Enterprise Account Note This field is returned only for Enterprise Accounts.
login_id	String	login_id3	The sign-in name of the DingTalk-built Enterprise Account. Note This field is returned only for DingTalk Enterprise Accounts belonging to your organization.
manager_userid	String	manager240	The employee’s direct manager. Note This field is returned only when the Direct manager field on the employee profile panel in the organization’s admin console has a value.
org_email_type	String	profession	The Enterprise Mail type of the employee: - profession: Standard - base: Basic
nickname	String	Name	The employee name. Note This field is returned only for DingTalk Enterprise Accounts belonging to your organization.
exclusive_account_corp_name	String	Organization name	The name of the organization to which the Enterprise Account belongs. Note This applies only to Enterprise Accounts and returns the organization that created the Enterprise Account.
exclusive_account_corp_id	String	dingxxx	The corp ID of the organization to which the Enterprise Account belongs. Note This applies only to Enterprise Accounts and returns the organization that created the Enterprise Account.
disable_status	Boolean	false	The disabled status of the Enterprise Account in your organization: - true: disabled - false: enabled Note This field is returned only for DingTalk Enterprise Accounts belonging to your organization.

Response body example

{
  "errcode":"0",
  "result":{
    "exclusive_account_type":"dingtalk",
    "extension":"{\"Hobby\":\"Travel\",\"Age\":\"24\"}",
    "unionid":"z21HjQliSzpw0YWCNxmii6u2Os62cZ62iSZ",
    "boss":"true",
    "role_list":{
      "group_name":"Position",
      "name":"Director",
      "id":"100"
    },
    "exclusive_account":"true",
    "manager_userid":"manager240",
    "admin":"true",
    "remark":"Remark",
    "title":"Technical Director",
    "hired_date":"1597573616828",
    "userid":"zhangsan",
    "org_email_type":"profession",
    "work_place":"Future Park",
    "dept_order_list":{
      "dept_id":"2",
      "order":"1"
    },
    "real_authed":"true",
    "nickname":"Name",
    "dept_id_list":"[2,3,4]",
    "job_number":"4",
    "email":"test@xxx.com",
    "leader_in_dept":{
      "leader":"true",
      "dept_id":"2"
    },
    "login_id":"login_id3",
    "exclusive_account_corp_name":"Organization name",
    "mobile":"13800138000",
    "active":"true",
    "telephone":"010-86123456-2345",
    "avatar":"xxx",
    "hide_mobile":"false",
    "exclusive_account_corp_id":"dingxxx",
    "senior":"true",
    "org_email":"test@xxx.com",
    "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 an error occurs when calling this API, look up the solution in the Global error codes document based on the error message.

Error code (errcode)	Error message (errmsg)	Solution
33012	Invalid userId	Check whether the userId is correct.
400002	Invalid parameter	Verify that the parameter is entered as required.
-1	The system is busy	Try again later.

API calling guide

Authentication & authorization

Contacts

Calendar

Conferencing

AI Table

Docs & files

IM

Get details of an Enterprise Account user

API call description

Request

Query parameters

Request body

Request example

Response

Response body

Response body example

Error codes

​API call description

​Request

​Query parameters

​Request body

​Request example

​Response

​Response body

​Response body example

​Error codes

API call description

Request

Query parameters

Request body

Request example

Response

Response body

Response body example

Error codes