# Search for departments

Call this interface to query the visible department information through the department name keyword as a user, including the department's ID, parent department, person in charge, and status, etc.

## Precautions

This interface can only be called with the user identity (user_access_token), and the search results are affected by the visibility range of the user identity's organizational structure. If a department is not visible to the current user, it cannot be searched. The visible range of the user's organizational structure needs to be set by the enterprise administrator in [Admin](https://feishu.cn/admin/index) > **Security** > **Member Permissions** > **Visibility scope of organization** within, make adjustments.

## Request

Facts | &nbsp;
---|---
HTTP URL | https://open.feishu.cn/open-apis/contact/v3/departments/search
HTTP Method | POST
Rate Limit | [Special Rate Limit](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
Supported app types | Custom App、Store App
Required scopes<br>**To use this API, you must have at least 1 of the listed scopes.**<br>Enable any scope from the list | Get basic information in contacts(contact:contact.base:readonly)<br>Search department(search:department:read)<br>Access Contacts as an app(contact:contact:access_as_app)<br>Read Contacts as an app(contact:contact:readonly_as_app)
Required field scopes | **Notice**：The response body of the API contains the following sensitive fields, and they will be returned only after corresponding scopes are added. If you do not need the fields, it is not recommended that you request the scopes.<br>Obtain department's organizational structure in contacts(contact:department.organize:readonly)<br>Obtain department's basic information(contact:department.base:readonly)<br>Obtain user ID(contact:user.employee_id:readonly)<br>View department HRBP info(contact:department.hrbp:readonly)<br>Access Contacts as an app(contact:contact:access_as_app)<br>Read contacts(contact:contact:readonly)<br>Read Contacts as an app(contact:contact:readonly_as_app)

### Request header

Parameter | Type | Required | Description
---|---|---|---
Authorization | string | Yes | `user_access_token`<br>**Value format**: "Bearer `access_token`"<br>**Example value**: "Bearer u-7f1bcd13fc57d46bac21793a18e560"<br>[How to choose and get access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
Content-Type | string | Yes | **Fixed value**: "application/json; charset=utf-8"

### Query parameters

Parameter | Type | Required | Description
---|---|---|---
user_id_type | string | No | User ID categories<br>**Example value**: open_id<br>**Optional values are**:<br>- open_id：Identifies a user to an app. The same user has different Open IDs in different apps. [How to get Open ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)<br>- union_id：Identifies a user to a tenant that acts as a developer. A user has the same Union ID in apps developed by the same developer, and has different Union IDs in apps developed by different developers. A developer can use Union ID to link the same user's identities in multiple apps.[How to get Union ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-union-id)<br>- user_id：Identifies a user to a tenant. The same user has different User IDs in different tenants. In one single tenant, a user has the same User ID in all apps （including store apps）. User ID is usually used to communicate user data between different apps. [How to get User ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-user-id)<br>**Default value**: `open_id`<br>**When the value is `user_id`, the following field scopes are required**:<br>Obtain user ID(contact:user.employee_id:readonly)
department_id_type | string | No | The type of department ID in this call. For a detailed introduction to department ID, please refer to [Department ID Description](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview#23857fe0).<br>**Default**: open_department_id<br>**Example value**: open_department_id<br>**Optional values are**:<br>- department_id：Supports user-defined configured department IDs. The deleted department_id can be reused when customizing the configuration, so department_id is unique within the scope of the department that has not been deleted.<br>- open_department_id：Department ID automatically generated by the system. The ID prefix is fixed to `od-` and is globally unique within the tenant.
page_token | string | No | Page identifier. It is not filled in the first request, indicating traversal from the beginning; when there will be more groups, the new page_token will be returned at the same time, and the next traversal can use the page_token to get more groups<br>**Example value**: AQD9/Rn9eij9Pm39ED40/RD/cIFmu77WxpxPB/2oHfQLZ+G8JG6tK7+ZnHiT7COhD2hMSICh/eBl7cpzU6JEC3J7COKNe4jrQ8ExwBCR
page_size | int | No | Paging size, used to limit the number of data entries returned in one request.<br>**Example value**: 10<br>**Default value**: `20`<br>**Data validation rules**:<br>- Maximum value: `50`

### Request body

Parameter | Type | Required | Description
---|---|---|---
query | string | Yes | Search keywords, the matching field is the department name (matching department internationalized names is not supported).<br>**Example value**: "DemoName"

### Request body example
```json
{
    "query": "DemoName"
}
```

**Go Request Example**
```go
import (
	"context"

"github.com/larksuite/oapi-sdk-go/v3"
	"github.com/larksuite/oapi-sdk-go/v3/service/contact/v3"
)

func main() {
	client := lark.NewClient("appID", "appSecret")

req := larkcontact.NewSearchDepartmentReqBuilder().
		PageSize(20).
		Body(larkcontact.NewSearchDepartmentReqBodyBuilder().
			Query(`DemoName`).
			Build()).
		Build()

resp, err := client.Contact.Department.Search(context.Background(), req)
}
```

**Java Request Example**
```java
import com.lark.oapi.Client;
import com.lark.oapi.core.request.RequestOptions;
import com.lark.oapi.service.contact.v3.model.SearchDepartmentReq;
import com.lark.oapi.service.contact.v3.model.SearchDepartmentReqBody;
import com.lark.oapi.service.contact.v3.model.SearchDepartmentResp;

public class Main {

public static void main(String arg[]) throws Exception {
        Client client = Client.newBuilder("appId", "appSecret").build();

SearchDepartmentReq req = SearchDepartmentReq.newBuilder()
                .pageSize(20)
                .searchDepartmentReqBody(SearchDepartmentReqBody.newBuilder()
                        .query("DemoName")
                        .build())
                .build();

SearchDepartmentResp resp = client.contact().department().search(req, RequestOptions.newBuilder().build());
    }
}
```

## Response

### Response body

Parameter | Type | Description
---|---|---
code | int | Error codes, fail if not zero
msg | string | Error descriptions
data | \- | \-
items | department\[\] | Department information.
name | string | Department name.<br>**Required field scopes (Satisfy any)**:<br>Obtain department's basic information(contact:department.base:readonly)<br>Access Contacts as an app(contact:contact:access_as_app)<br>Read contacts(contact:contact:readonly)<br>Read Contacts as an app(contact:contact:readonly_as_app)
i18n_name | department_i18n_name | Internationalized department name.<br>**Required field scopes (Satisfy any)**:<br>Obtain department's basic information(contact:department.base:readonly)<br>Access Contacts as an app(contact:contact:access_as_app)<br>Read contacts(contact:contact:readonly)<br>Read Contacts as an app(contact:contact:readonly_as_app)
zh_cn | string | Department's Chinese name.
ja_jp | string | Department's Japanese name.
en_us | string | Department's English name.
parent_department_id | string | The department ID of the parent department.<br>- The ID type is consistent with the department_id_type value of the query parameter.<br>- When the parent department is the root department, the parameter value is `0`.<br>**Required field scopes (Satisfy any)**:<br>Obtain department's organizational structure in contacts(contact:department.organize:readonly)<br>Access Contacts as an app(contact:contact:access_as_app)<br>Read contacts(contact:contact:readonly)<br>Read Contacts as an app(contact:contact:readonly_as_app)
department_id | string | Custom department ID. This ID can be used later to delete, modify, and query department information.<br>**Required field scopes (Satisfy any)**:<br>Obtain department's basic information(contact:department.base:readonly)<br>Access Contacts as an app(contact:contact:access_as_app)<br>Read contacts(contact:contact:readonly)<br>Read Contacts as an app(contact:contact:readonly_as_app)
open_department_id | string | The open_department_id of the department is automatically generated by the system. This ID can be used later to delete, modify, and query department information.
leader_user_id | string | The user ID and ID type of the department head are consistent with the user_id_type value of the query parameter.<br>**Required field scopes (Satisfy any)**:<br>Obtain department's organizational structure in contacts(contact:department.organize:readonly)<br>Access Contacts as an app(contact:contact:access_as_app)<br>Read contacts(contact:contact:readonly)<br>Read Contacts as an app(contact:contact:readonly_as_app)
chat_id | string | The group ID of the department group. You can later use [Get Group Information](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat/get) to obtain the detailed information of the group.<br>**Required field scopes (Satisfy any)**:<br>Obtain department's basic information(contact:department.base:readonly)<br>Access Contacts as an app(contact:contact:access_as_app)<br>Read contacts(contact:contact:readonly)<br>Read Contacts as an app(contact:contact:readonly_as_app)
order | string | The sorting of departments is the order in which departments are displayed among departments at the same level. The smaller the value, the higher the sorting is.<br>**Required field scopes (Satisfy any)**:<br>Obtain department's organizational structure in contacts(contact:department.organize:readonly)<br>Access Contacts as an app(contact:contact:access_as_app)<br>Read contacts(contact:contact:readonly)<br>Read Contacts as an app(contact:contact:readonly_as_app)
unit_ids | string\[\] | List of unit custom IDs bound to the department, currently only one is supported.<br>**Required field scopes (Satisfy any)**:<br>Obtain department's organizational structure in contacts(contact:department.organize:readonly)<br>Access Contacts as an app(contact:contact:access_as_app)<br>Read contacts(contact:contact:readonly)<br>Read Contacts as an app(contact:contact:readonly_as_app)
member_count | int | The number of users (including department heads) in the current department and its subordinate departments.<br>**Required field scopes (Satisfy any)**:<br>Obtain department's organizational structure in contacts(contact:department.organize:readonly)<br>Access Contacts as an app(contact:contact:access_as_app)<br>Read contacts(contact:contact:readonly)<br>Read Contacts as an app(contact:contact:readonly_as_app)
status | department_status | Department status.<br>**Required field scopes (Satisfy any)**:<br>Obtain department's basic information(contact:department.base:readonly)<br>Access Contacts as an app(contact:contact:access_as_app)<br>Read contacts(contact:contact:readonly)<br>Read Contacts as an app(contact:contact:readonly_as_app)
is_deleted | boolean | Whether it is deleted.<br>**Possible values are:**<br>- true<br>- false
leaders | departmentLeader\[\] | Head of department.
leaderType | int | Person in charge type.<br>**Optional values are**:<br>- 1：Main person in charge<br>- 2：Deputy responsible person
leaderID | string | The user ID and ID type of the person in charge are consistent with the user_id_type value of the query parameter.<br>**Required field scopes (Satisfy any)**:<br>Obtain department's organizational structure in contacts(contact:department.organize:readonly)<br>Access Contacts as an app(contact:contact:access_as_app)<br>Read contacts(contact:contact:readonly)<br>Read Contacts as an app(contact:contact:readonly_as_app)
group_chat_employee_types | int\[\] | Personnel type restrictions for department groups. Possible values for person type are as follows:<br>- 1: Regular employee<br>- 2: Intern<br>- 3: Outsourcing<br>- 4: Labor services<br>- 5: Consultant<br>If it is a custom person type, the corresponding number will be returned. You can call the [Query Personnel Type](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/employee_type_enum/list) interface to obtain the custom employee type information corresponding to the corresponding number (enum_value) .
department_hrbps | string\[\] | List of user IDs for department HRBP. The ID type is consistent with the value of the query parameter user_id_type.<br>**Required field scopes**:<br>View department HRBP info(contact:department.hrbp:readonly)
primary_member_count | int | The number of primary members of the current department and its subordinate departments (that is, the member's primary department is the current department).<br>**Required field scopes (Satisfy any)**:<br>Obtain department's organizational structure in contacts(contact:department.organize:readonly)<br>Access Contacts as an app(contact:contact:access_as_app)<br>Read contacts(contact:contact:readonly)<br>Read Contacts as an app(contact:contact:readonly_as_app)
page_token | string | Page identifier, when has_more is true, a new page_token will also be returned. Otherwise, page_token will not be returned
has_more | boolean | Whether the response body has more parameters

### Response body example
```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "items": [
            {
                "name": "DemoName",
                "i18n_name": {
                    "zh_cn": "Demo name",
                    "ja_jp": "Name",
                    "en_us": "Demo Name"
                },
                "parent_department_id": "D067",
                "department_id": "D096",
                "open_department_id": "od-4e6ac4d14bcd5071a37a39de902c7141",
                "leader_user_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
                "chat_id": "oc_5ad11d72b830411d72b836c20",
                "order": "100",
                "unit_ids": [
                    "custom_unit_id"
                ],
                "member_count": 100,
                "status": {
                    "is_deleted": false
                },
                "leaders": [
                    {
                        "leaderType": 1,
                        "leaderID": "ou_7dab8a3d3cdcc9da365777c7ad535d62"
                    }
                ],
                "group_chat_employee_types": [
                    1
                ],
                "department_hrbps": [
                    "ou_7dab8a3d3cdcc9da365777c7ad535d62"
                ],
                "primary_member_count": 100
            }
        ],
        "page_token": "AQD9/Rn9eij9Pm39ED40/RD/cIFmu77WxpxPB/2oHfQLZ%2BG8JG6tK7%2BZnHiT7COhD2hMSICh/eBl7cpzU6JEC3J7COKNe4jrQ8ExwBCR",
        "has_more": true
    }
}
```

### Error code

HTTP status code | Error code | Description | Troubleshooting suggestions
---|---|---|---
400 | 48001 | invalid param | Parameter error. Check the parameter.
500 | 48002 | Internal Server Error | System error. Try again first. If the problem still cannot be solved, please consult [Technical Support](https://applink.feishu.cn/TLJpeNdW).

For more error code information, see [General error codes](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN).

