Skip to main content
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 URLhttps://oapi.dingtalk.io/topapi/v2/user/get
HTTP MethodPOST
Supported app typesappType-Internal app, appType-Third-party enterprise app
Required permissionspermission-qyapi_get_member-Read permission for user information

​
Query parameters

NameTypeRequiredExampleDescription
access_tokenStringYesbe3FxxxxThe 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

NameTypeRequiredExampleDescription
useridStringYesmanager4220The user ID of the user.
languageStringNozh_CNThe language for Contacts. - zh_CN: Chinese (default) - en_US: English
login_idStringNotestThe 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://oapi.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://oapi.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://oapi.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://oapi.dingtalk.io/topapi/v2/user/get");
C# 
IDingTalkClient client = new DefaultDingTalkClient("https://oapi.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

NameTypeExampleDescription
request_idString4e7exhl6pm0tThe request ID.
errcodeNumber0The return code.
errmsgStringokThe description of the return code.
resultObjectThe returned result.
useridStringzhangsanThe user ID of the employee.
unionidStringz21HjQliSzpw0YWCNxmii6u2Os62cZ62iSZThe unique identifier of the employee within the current developer’s Enterprise Account scope.
nameStringJohnThe employee name.
avatarStringxxxThe 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_codeString86The international dialing code. Note This field is not returned for third-party enterprise apps. To obtain state_code, use the DingTalk unified authorization suite.
mobileString13800138000The 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_mobileBooleanfalseWhether 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.
telephoneString010-86123456-2345The extension number. Note This field is not returned for third-party enterprise apps.
job_numberString4The employee ID.
titleStringTechnical DirectorThe job title.
emailStringtest@xxx.comThe 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_emailStringtest@xxx.comThe 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_placeStringFuture ParkThe 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.
remarkStringRemarkThe 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_listNumber[][2,3,4]The list of department IDs the employee belongs to.
dept_order_listObject[]The sort order of the employee in each department.
dept_idNumber2The department ID.
orderNumber1The sort order of the employee in the department.
extensionString{"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_dateNumber1597573616828The 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.
activeBooleantrueWhether DingTalk has been activated: - true: activated - false: not activated
real_authedBooleantrueWhether real-name authentication has been completed: - true: authenticated - false: not authenticated
seniorBooleantrueWhether the user is a senior executive of the organization: - true: yes - false: no
adminBooleantrueWhether the user is an admin of the organization: - true: yes - false: no
bossBooleantrueWhether the user is the boss of the organization: - true: yes - false: no
leader_in_deptObject[]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_idNumber2The department ID.
leaderBooleantrueWhether the user is a leader: - true: yes - false: no
role_listObject[]The role list.
idNumber100The role ID.
nameStringDirectorThe role name.
group_nameStringPositionThe role group name.
exclusive_accountBooleantrueWhether the user is an Enterprise Account: - true: yes - false: no
union_emp_extObjectThe association information when the user is from an associated organization. Note This field is returned when the user’s organization has associated organizations.
useridString500The user ID of the employee.
union_emp_map_listObject[]The association mapping.
useridString5000The user ID of the employee in the associated branch organization.
corp_idStringdingxxxThe corp ID of the associated branch organization.
corp_idStringdingxxxThe corp ID of the organization the current user belongs to.
exclusive_account_typeStringdingtalkThe 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_idStringlogin_id3The sign-in name of the DingTalk-built Enterprise Account. Note This field is returned only for DingTalk Enterprise Accounts belonging to your organization.
manager_useridStringmanager240The 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_typeStringprofessionThe Enterprise Mail type of the employee: - profession: Standard - base: Basic
nicknameStringNameThe employee name. Note This field is returned only for DingTalk Enterprise Accounts belonging to your organization.
exclusive_account_corp_nameStringOrganization nameThe 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_idStringdingxxxThe 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_statusBooleanfalseThe 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
33012Invalid userIdCheck whether the userId is correct.
400002Invalid parameterVerify that the parameter is entered as required.
-1The system is busyTry again later.