> ## Documentation Index
> Fetch the complete documentation index at: https://help.dingtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get the user ID by unionId

> Call this API to get the userId of an employee by unionId, which is the system-generated unique identifier of the employee within the developer enterprise account scope.

# 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 URL              | [https://api.dingtalk.io/topapi/user/getbyunionid](https://api.dingtalk.io/topapi/user/getbyunionid) |
| 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 parameter

| Name          | Type   | Required | Example  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------- | ------ | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| access\_token | String | Yes      | be3Fxxxx | The 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](/open/development/obtain-orgapp-token). - 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

| Name    | Type   | Required | Example            | Description                                                                                                                                                                                                                                                                                                                 |
| ------- | ------ | -------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| unionid | String | Yes      | z21HjQliSzpw0Yxxxx | The 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](/open/development/obtain-the-userid-of-a-user-by-using-the-log-free). |

### Request example

```curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api.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

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
DingTalkClient client = new DefaultDingTalkClient("https://api.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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import dingtalk.api

req=dingtalk.api.OapiUserGetbyunionidRequest("https://api.dingtalk.io/topapi/user/getbyunionid")
req.unionid="z21HjQliSzpw0YWCNxmii6u2Os62cZ62iSZ"
try:
  resp= req.getResponse(access_token)
  print(resp)
except Exception,e:
  print(e)
```

PHP

```php theme={"theme":{"light":"github-light","dark":"github-dark"}}
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://api.dingtalk.io/topapi/user/getbyunionid");
```

C#

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
IDingTalkClient client = new DefaultDingTalkClient("https://api.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

| Name          | Type                     | Example      | Description                                                              |
| ------------- | ------------------------ | ------------ | ------------------------------------------------------------------------ |
| request\_id   | String                   | zcqi5450rpit | The request ID.                                                          |
| errcode       | Number                   | 0            | The return code.                                                         |
| errmsg        | String                   | ok           | The description of the return code.                                      |
| result        | UserGetByUnionIdResponse |              | The returned result.                                                     |
| contact\_type | Number                   | 0            | The contact type:   - **0**: Internal employee - **1**: External contact |
| userid        | String                   | zhangsan     | The user ID of the user.                                                 |

### Response body example

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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](/open/development/server-api-error-codes-1) document.

| Error code (errcode) | Error message (errmsg)                   | Solution                              |
| -------------------- | ---------------------------------------- | ------------------------------------- |
| 60121                | The corresponding employee is not found. | Check whether the unionId is correct. |
| 400002               | Invalid parameter.                       | Check whether the unionId is correct. |
| -1                   | The system is busy.                      | Try again later.                      |