# Batch query department version information According to the department ID list, batch query all department version information within the start and end time, including department name, department type, superior, code, person in charge, whether it is enabled, description and other information **Notice**：- Delay description: The delay of the database leader/follower is within 2s, that is, calling this interface within 2s after directly creating the rank may not query the data. ## Request Facts |   ---|--- HTTP URL | https://open.feishu.cn/open-apis/corehr/v2/departments/query_multi_timeline HTTP Method | POST Rate Limit | [10 per second](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN) Supported app types | Custom App、Store App Required scopes
**To use this API, you must have at least 1 of the listed scopes.**
Enable any scope from the list | Get department information(corehr:department:read)
Update department information(corehr:department:write) 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.
Get department cost center field info(corehr:department.cost_center_id:read)
Get custom field in department information(corehr:department.custom_fields:read)
Get department manager(corehr:department.manager:read)
Get department structure(corehr:department.organize:read)
Obtain user ID(contact:user.employee_id:readonly) ### Request header Parameter | Type | Required | Description ---|---|---|--- Authorization | string | Yes | `tenant_access_token`
**Value format**: "Bearer `access_token`"
**Example value**: "Bearer t-7f1bcd13fc57d46bac21793a18e560"
[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 ---|---|---|--- page_size | int | Yes | Page size, up to 100
**Example value**: 100
**Data validation rules**:
- Value range: `1` ～ `100` 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
**Example value**: 6891251722631890445 user_id_type | string | No | User ID categories
**Example value**: people_corehr_id
**Optional values are**:
- 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)
- 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)
- 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)

**Default value**: `people_corehr_id`
**When the value is `user_id`, the following field scopes are required**:
Obtain user ID(contact:user.employee_id:readonly) department_id_type | string | No | The type of department ID used in this call
**Example value**: people_corehr_department_id
**Optional values are**:
- open_department_id：[Feishu] is used to identify a department in a specific application, and the same department_id open_department_id the same in different applications.
- department_id：[Feishu] is used to identify a unique department within a tenant.
- people_corehr_department_id：[Feishu Personnel] is used to identify departments in "Feishu Personnel".
**Default value**: `people_corehr_department_id` ### Request body Parameter | Type | Required | Description ---|---|---|--- department_ids | string\[\] | Yes | Department ID List，Request[搜索部门信息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/department/search)。
**Example value**: ["7094136522860922111"]
**Data validation rules**:
- Length range: `1` ～ `10` effective_date_start | string | No | Effective date begins (inclusive)
**Example value**: "2024-01-01"
**Data validation rules**:
- Length range: `10` ～ `10` characters
- Regular expression: `^((([0-9]{3}[1-9]|[0-9]{2}[1-9][0-9]{1}|[0-9]{1}[1-9][0-9]{2}|[1-9][0-9]{3})-(((0[13578]|1[02])-(0[1-9]|[12][0-9]|3[01]))|((0[469]|11)-(0[1-9]|[12][0-9]|30))|(02-(0[1-9]|[1][0-9]|2[0-8]))))|((([0-9]{2})(0[48]|[2468][048]|[13579][26])|((0[48]|[2468][048]|[3579][26])00))-02-29))$` effective_date_end | string | No | End of effective date (inclusive)
**Example value**: "2024-12-31"
**Data validation rules**:
- Length range: `10` ～ `10` characters
- Regular expression: `^((([0-9]{3}[1-9]|[0-9]{2}[1-9][0-9]{1}|[0-9]{1}[1-9][0-9]{2}|[1-9][0-9]{3})-(((0[13578]|1[02])-(0[1-9]|[12][0-9]|3[01]))|((0[469]|11)-(0[1-9]|[12][0-9]|30))|(02-(0[1-9]|[1][0-9]|2[0-8]))))|((([0-9]{2})(0[48]|[2468][048]|[13579][26])|((0[48]|[2468][048]|[3579][26])00))-02-29))$` fields | string\[\] | No | List of fields to return. The list of fields that can be filled in is as follows:
- department_name: Department name
- sub_type: Department Subtype
- tree_order: Tree sort
- list_order: List sort
- is_root: whether the root department
- is_confidential: Confidentiality
- staffing_model: Post Position Mode
- cost_center_id: department default cost center
- code: Department code
- active: whether to enable
- parent_department_id: Higher Department ID
- manager: Person in charge
- description: Department description
- effective_date: Effective date of current version
- expiration_date: Expiration date of current version
- custom_fields(Custom field, specific "custom_api_name" needs to be passed in)See [Get custom field list](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/custom_field/query) ,For example :"shifouleixing_7795__c"
**Example value**: ["department_name"]
**Data validation rules**:
- Length range: `0` ～ `100` ### Request body example ```json { "department_ids": [ "7094136522860922111" ], "effective_date_start": "2024-01-01", "effective_date_end": "2024-12-31", "fields": [ "department_name" ] } ``` ## Response ### Response body Parameter | Type | Description ---|---|--- code | int | Error codes, fail if not zero msg | string | Error descriptions data | \- | \- items | department_timeline\[\] | Department information id | string | Department ID version_id | string | Department Version ID(default return) names | i18n\[\] | Department name lang | string | language, Chinese with zh-CN; English with en-US. value | string | content sub_type | enum | Department type
- Obtained by [Get Field Details](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/custom_field/get_by_param) query. Request parameters: object_api_name = department; custom_api_name = subtype. enum_name | string | enumeration value display | i18n\[\] | enumerated multilingual display lang | string | Language coding (IETF BCP 47) value | string | text content parent_department_id | string | The ID of the superior department, the detailed information can be obtained through the [Query a single department](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/department/get) interface
- This field will not be displayed if the query is for a first-level department
**Required field scopes**:
Get department structure(corehr:department.organize:read) manager | string | Department head, fill in the employee's employment ID
Detailed information can be obtained through the [Search employee information](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/employee/search) interface
**Required field scopes**:
Get department manager(corehr:department.manager:read) code | string | encoding effective_date | string | Version Effective date
- Return format: YYYY-MM-DD (minimum unit to day)
- Date range: 1900-01-01～9999-12-31 active | boolean | Whether to enable descriptions | i18n\[\] | describe lang | string | Language, support Chinese and English. Chinese with zh-CN; English with en-US. value | string | content custom_fields | custom_field_data\[\] | Custom field types, see [Get custom field list](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/custom_field/query)
**Required field scopes**:
Get custom field in department information(corehr:department.custom_fields:read) custom_api_name | string | Custom field apiname, which is the unique identifier of the custom field name | custom_name | Custom field name zh_cn | string | Chinese en_us | string | English type | int | Custom field types, see [Get custom field list](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/custom_field/query) value | string | Field value, is the string escaped by json, according to the metadata definition, the field format is different (such as 123, 123.23, "true", ["id1", "id2"], "2006-01-02 15:04:05") expiration_date | string | Version Expiration date
- Return format: YYYY-MM-DD (minimum unit to day)
- Date range: 1900-01-01~ 9999-12-31 tree_order | string | Tree order,Indicates the sorting sequence number of departments at the same level
- Data type is string, sorted by actual numeric value. The smaller the value, the earlier peer departments are displayed; it only applies to direct subordinate departments under the same parent department.
- Number generation rules:
- The length of the number is dynamically determined by the quantity of departments at the same level: 6-digit numbers if there are no more than 10 departments at the same level, 7-digit numbers for 10 to 20 departments, and unified 16-digit numbers for more than 100 departments, and so on.
- Automatically assigned by the system when creating a new department: The number of a new peer department is generated by adding a fixed value to the previous department number. For instance, add 1000 each time for 6-digit numbers, and add 10000 each time for 7-digit numbers.
- Rearrangement trigger: Global rearrangement of numbers at the same level will be triggered when the number of peer departments exceeds the accommodating range of the current number length, or positions cannot be normally inserted after multiple drag sorting operations. All department numbers will be regenerated in accordance with new length and accumulation rules, which may lead to a noticeable increase in values.
- Abnormalities may occur during system maintenance of sorting numbers when there are more than 1000 subordinate departments under the same parent department.
- Update timing:
- tree_order will not be generated in real time when creating departments, and will be updated within 10 minutes.
- tree_order can be generated in real time when dragging departments to adjust sorting on the page.
- Changing the superior department will clear tree_order and trigger recalculation of list_order and tree_order, which will be finished within 10 minutes. (list_order is formed by concatenating all tree_order values of superior paths of the department with hyphens "-") list_order | string | List order, representing the mixed sorting numbers of all departments, splicing with "-" for all tree_order on the superior path of the department
- This field is not updated immediately in the new/update scenario, and the update will be delayed after 10 minutes
- Since list_order changes will cause [department change interface](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/department/events/updated) to generate a large number of events, the event interface will not synchronize change events for this field. If you need to subscribe, please contact [Oncall](https://applink.feishu.cn/TLJpeNdW) to open it separately
- When the number of departments at the same level (same superior) exceeds 1000, this field will no longer be updated is_root | boolean | Is it the root department(default return) is_confidential | boolean | Is it confidential(This feature is temporarily unsupported and can be ignored.) staffing_model | enum | Post management mode
- For detailed enumeration types, please refer to the definition of staffing_model in [enumeration scene](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/feishu-people-enum-constant) enum_name | string | enumeration value display | i18n\[\] | enumerated multilingual display lang | string | Language, Chinese with zh-CN, English with en-US value | string | text content cost_center_id | string | Cost center id
**Required field scopes**:
Get department cost center field info(corehr:department.cost_center_id:read) 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": [ { "id": "4719456877659520852", "version_id": "7238516215202170412", "names": [ { "lang": "zh-CN", "value": "中文示例" } ], "sub_type": { "enum_name": "phone_type", "display": [ { "lang": "zh-CN", "value": "中文示例" } ] }, "parent_department_id": "4719456877659520111", "manager": "6893013238632416777", "code": "D00000456", "effective_date": "2020-05-01", "active": true, "descriptions": [ { "lang": "zh-CN", "value": "中文示例" } ], "custom_fields": [ { "custom_api_name": "name", "name": { "zh_cn": "自定义姓名", "en_us": "Custom Name" }, "type": 1, "value": "\"231\"" } ], "expiration_date": "2020-05-02", "tree_order": "001000", "list_order": "001000-001000", "is_root": false, "is_confidential": false, "staffing_model": { "enum_name": "phone_type", "display": [ { "lang": "zh-CN", "value": "中文示例" } ] }, "cost_center_id": "7142384817131652652" } ], "page_token": "eVQrYzJBNDNONlk4VFZBZVlSdzlKdFJ4bVVHVExENDNKVHoxaVdiVnViQT0=", "has_more": true } } ``` ### Error code HTTP status code | Error code | Description | Troubleshooting suggestions ---|---|---|--- 503 | 1161204 | Request timeout | Contact Feishu OnCall 429 | 1161604 | QPS over limit | Contact Feishu OnCall