> ## 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 details of users in a department > Call this API to get detailed information of users in a specified department, including full profile fields. Call this API to get the details of users in a specified department. ## API call description * This API only returns the details of users in the specified department. Users in sub-departments are not returned. * This API can return the details of either regular-account users or Enterprise Account users in a department. Because the parameter usage differs significantly between the two scenarios, the documentation is split by account type for clarity: * To get details of regular-account users in a department, refer to this document. * To get details of Enterprise Account users in a department (typically Enterprise DingTalk users), see [Get details of Enterprise Account users in a department](/open/development/queries-account-details). ## Request | **Basic information** | | | --------------------- | -------------------------------------------------------------------------------------------- | | HTTP URL | [https://api.dingtalk.io/topapi/v2/user/list](https://api.dingtalk.io/topapi/v2/user/list) | | HTTP Method | POST | | Supported app types | appType-Internal app, appType-Third-party enterprise app | | Required permissions | permission-qyapi\_get\_department\_member-Read permission for department members in Contacts | ### Query parameter | Name | Type | Required | Example | Description | | ------------- | ------ | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | access\_token | String | Yes | bE74xxxx | The app credential used to call this API. - For an internal app, get it through the API for getting the [access\_token of an internal app](/open/development/obtain-orgapp-token). - For a third-party enterprise app, get it through the API for getting the access\_token of a third-party enterprise. | ### Request body | Name | Type | Required | Example | Description | | ---------------------- | ------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | dept\_id | Number | Yes | 10 | The department ID. Call [Get the department list](/open/development/user-management-acquires-the-list-departments) to get it. For the root department, set this parameter to 1. **Note** Only users in the current department are returned. Users in sub-departments are not included. | | cursor | Number | Yes | 0 | The cursor for paginated queries. Set it to 0 for the first call, and then use the `next_cursor` value returned by the previous call. | | size | Number | Yes | 10 | The page size. | | order\_field | String | No | modify\_desc | The sorting rule for department members. If not specified, the default is custom sorting (`custom`): - **entry\_asc**: sort by the time of joining the department in ascending order. - **entry\_desc**: sort by the time of joining the department in descending order. - **modify\_asc**: sort by department information modified time in ascending order. - **modify\_desc**: sort by department information modified time in descending order. - **custom**: sort by user-defined order (or by pinyin if not defined). | | contain\_access\_limit | Boolean | No | false | Whether to return users with restricted access: - true: return them. - false: do not return them. | | language | String | No | zh\_CN | The language for Contacts: - **zh\_CN**: Chinese (default). - **en\_US**: English. | ### Request example ```curl theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X POST "https://api.dingtalk.io/topapi/v2/user/list" \ -H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \ -d 'access_token=834f6b00-25b8-4484-a89d-595d1f7fa0a7' \ -d 'contain_access_limit=false' \ -d 'cursor=0' \ -d 'dept_id=10' \ -d 'language=zh_CN' \ -d 'order_field=modify_desc' \ -d 'size=10' ``` Java ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/v2/user/list"); OapiV2UserListRequest req = new OapiV2UserListRequest(); req.setDeptId(1L); req.setCursor(0L); req.setSize(10L); req.setOrderField("modify_desc"); req.setContainAccessLimit(false); req.setLanguage("zh_CN"); OapiV2UserListResponse rsp = client.execute(req, ""); System.out.println(rsp.getBody()); ``` Python ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} import dingtalk.api req=dingtalk.api.OapiV2UserListRequest("https://api.dingtalk.io/topapi/v2/user/list") req.dept_id=10 req.cursor=0 req.size=10 req.order_field="modify_desc" req.contain_access_limit=false req.language="zh_CN" 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 OapiV2UserListRequest; $req->setDeptId("10"); $req->setCursor("0"); $req->setSize("10"); $req->setOrderField("modify_desc"); $req->setContainAccessLimit("false"); $req->setLanguage("zh_CN"); $resp = $c->execute($req, $access_token, "https://api.dingtalk.io/topapi/v2/user/list"); ``` C# ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} IDingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/v2/user/list"); OapiV2UserListRequest req = new OapiV2UserListRequest(); req.DeptId = 10L; req.Cursor = 0L; req.Size = 10L; req.OrderField = "modify_desc"; req.ContainAccessLimit = false; req.Language = "zh_CN"; OapiV2UserListResponse rsp = client.Execute(req, access_token); Console.WriteLine(rsp.Body); ``` ## Response ### Response body | Name | Type | Example | Description | | ------------------ | --------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | errcode | Number | 0 | The return code. | | errmsg | String | ok | The description of the return code. | | result | Object | | The result returned. | | has\_more | Boolean | true | Whether there is more data: - true: yes. - false: no. | | next\_cursor | Number | 10 | The cursor for the next page. **Note** If **has\_more** is **false**, there is no more paginated data. | | list | Object\[] | | The list of user information. | | userid | String | zhangsan | The user ID. | | unionid | String | z21HjQliSzpw0YWCNxmii6u2Os62cZ62iSZ | The unique identifier of the user within the current developer's enterprise account scope. | | name | String | John | The user name. | | avatar | String | xxx | The profile photo URL. | | state\_code | String | 86 | The international dialing code. **Note** - If this field is not returned for an internal app, check whether the **Permission to access employee mobile numbers** is enabled in the current app's Contacts permissions. - This parameter is not returned for third-party enterprise apps. To get `state_code`, use the DingTalk unified authorization suite. | | mobile | String | 13800138000 | The mobile number. **Note** - If this field is not returned for an internal app, check whether the **Permission to access employee mobile numbers** is enabled in the current app's Contacts permissions. - This parameter is not returned for third-party enterprise apps. To get `mobile`, use the DingTalk unified authorization suite. | | hide\_mobile | Boolean | false | Whether the mobile number is hidden: - **true**: hidden. When hidden, the mobile number is hidden on the Profile page, but other users can still send DINGs or initiate DingTalk free business calls to this number. - **false**: not hidden. | | telephone | String | 010-86123456-2345 | The extension number. **Note** This parameter 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](mailto:test@xxx.com) | The employee mail. **Note** - If this field is not returned for an internal app, check whether the **Mail and other personal information** permission is enabled in the current app's Contacts permissions. - The field is returned only when it has a value on the user information panel. - This parameter is not returned for third-party enterprise apps. | | org\_email | String | [test@xxx.com](mailto:test@xxx.com) | The employee's Enterprise Mail. **Note** - If this field is not returned for an internal app, check whether the **Mail and other personal information** permission is enabled in the current app's Contacts permissions. - The field is returned only when it has a value on the user information panel. - This parameter is not returned for third-party enterprise apps. | | work\_place | String | Future Park | The work location. **Note** - If this field is not returned for an internal app, check whether the **Mail and other personal information** permission is enabled in the current app's Contacts permissions. - The field is returned only when it has a value on the user information panel. - This parameter is not returned for third-party enterprise apps. | | remark | String | Remark | The alias. **Note** - If this field is not returned for an internal app, check whether the **Mail and other personal information** permission is enabled in the current app's Contacts permissions. - The field is returned only when it has a value on the user information panel. - This parameter is not returned for third-party enterprise apps. | | dept\_id\_list | Number\[] | \[2,3,4] | The list of department IDs the user belongs to. | | dept\_order | Number | 1 | The user's sort order within the department. | | extension | String | `{"Hobby":"Travel","Age":"24"}` | The extended attributes. **Note** - If this field is not returned for an internal app, check whether the **Mail and other personal information** permission is enabled in the current app's Contacts permissions. - The field is returned only when it has a value on the user information panel. - This parameter is not returned for third-party enterprise apps. | | hired\_date | Number | 1597573616828 | The hire date, as a Unix timestamp in milliseconds. **Note** This parameter is not returned for third-party enterprise apps. | | active | Boolean | true | Whether the user has activated DingTalk: - **true**: activated. - **false**: not activated. | | 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 | Boolean | true | Whether the user is the leader of the department: - **true**: yes. - **false**: no. | | exclusive\_account | Boolean | false | Whether the user is an Enterprise Account: - **true**: yes. - **false**: no. **Note** - For an introduction to Enterprise Accounts, see [Enterprise Account overview](/open/development/dedicated-account-overview). - This parameter is not returned for third-party enterprise apps. | ### Response body example ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "errcode":"0", "result":{ "next_cursor":"10", "has_more":"true", "list":{ "leader":"true", "extension":"{\"Hobby\":\"Travel\",\"Age\":\"24\"}", "unionid":"z21HjQliSzpw0YWCNxmii6u2Os62cZ62iSZ", "boss":"true", "exclusive_account":"false", "admin":"true", "remark":"Remark", "title":"Technical Director", "hired_date":"1597573616828", "userid":"zhangsan", "work_place":"Future Park", "dept_id_list":"[2,3,4]", "job_number":"4", "email":"test@xxx.com", "dept_order":"1", "mobile":"13800138000", "active":"true", "telephone":"010-86123456-2345", "avatar":"xxx", "hide_mobile":"false", "org_email":"test@xxx.com", "name":"John", "state_code":"86" } }, "errmsg":"ok" } ``` ### Error codes If an error is returned when you call this API, find the solution in [Global error codes](/open/development/server-api-error-codes-1) based on the error message. | Error code (errcode) | Error message (errmsg) | Solution | | -------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------ | | 400002 | Invalid parameter | Check whether the parameters are filled in as required. | | 50004 | The department is out of the permission scope | Check whether the access\_token has the operation permission. | | 40035 | Invalid parameter | The value of dept\_id, cursor, size, or order\_field does not meet the requirements. | | 60019 | Failed to get users from the department | Check whether the related parameters are filled in correctly. | | -1 | System busy | Try again later. |