Skip to main content

​
Get the user ID by unionId

​
API call description

A unionId is a unique identifier assigned to an employee within the scope of the current developer Enterprise Account, generated by the system:
  • The unionId of the same employee differs across different developer Enterprise Accounts.
  • Within the same developer Enterprise Account, the unionId is unique and immutable. For example, multiple apps developed by the same service provider, or multiple app accounts in scenarios such as Scan QR Code sign-in, all share the same unionId.

​
Request

Basic information
HTTP URLhttps://oapi.dingtalk.io/topapi/user/getbyunionid
HTTP MethodPOST
Supported app typesappType-Internal app, appType-Third-party enterprise app
Required permissionspermission-qyapi_get_member-Read permission for user information

​
Query parameter

NameTypeRequiredExampleDescription
access_tokenStringYesbe3FxxxxThe app credential used to call this API. Note If the unionId was obtained through silent login, you cannot use the token obtained from silent login to call this API. You must obtain a new token using the APIs below. - For an internal app, obtain the access_token through the API for getting the access_token of an internal app. - For a third-party enterprise app, obtain the access_token through the API for getting the access_token of a third-party enterprise.

​
Request body

NameTypeRequiredExampleDescription
unionidStringYesz21HjQliSzpw0YxxxxThe unique identifier of an employee within the scope of the current developer Enterprise Account. It is generated by the system and remains unchanged. You can get the unionId by calling Get the user ID of a user by using the silent login code.

​
Request example

curl -X POST "https://oapi.dingtalk.io/topapi/user/getbyunionid" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=6348d21e-fb41-4745-a214-95bcf8c118f0' \
-d 'unionid=z21HjQliSzpw0YWCNxmii6u2Os62cZ62iSZ'
Java 
DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/user/getbyunionid");
OapiUserGetbyunionidRequest req = new OapiUserGetbyunionidRequest();
req.setUnionid("z21HjQliSzpw0Yxxxxxx");
OapiUserGetbyunionidResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());
Python 
import dingtalk.api

req=dingtalk.api.OapiUserGetbyunionidRequest("https://oapi.dingtalk.io/topapi/user/getbyunionid")
req.unionid="z21HjQliSzpw0YWCNxmii6u2Os62cZ62iSZ"
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 OapiUserGetbyunionidRequest;
$req->setUnionid("z21HjQliSzpw0YWCNxmii6u2Os62cZ62iSZ");
$resp = $c->execute($req, $access_token, "https://oapi.dingtalk.io/topapi/user/getbyunionid");
C# 
IDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/user/getbyunionid");
OapiUserGetbyunionidRequest req = new OapiUserGetbyunionidRequest();
req.Unionid = "z21HjQliSzpw0YWCNxmii6u2Os62cZ62iSZ";
OapiUserGetbyunionidResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

​
Response

​
Response body

NameTypeExampleDescription
request_idStringzcqi5450rpitThe request ID.
errcodeNumber0The return code.
errmsgStringokThe description of the return code.
resultUserGetByUnionIdResponseThe returned result.
contact_typeNumber0The contact type: - 0: Internal employee - 1: External contact
useridStringzhangsanThe user ID of the user.

​
Response body example

{
  "errcode":"0",
  "errmsg":"ok",
  "result":{
   "contact_type":"0",
   "userid":"zhangsan"
  },
  "request_id": "zcqi5450rpit"
}

​
Error codes

If an error occurs when calling this API, look up the solution by error message in the Global error codes document.
Error code (errcode)Error message (errmsg)Solution
60121The corresponding employee is not found.Check whether the unionId is correct.
400002Invalid parameter.Check whether the unionId is correct.
-1The system is busy.Try again later.