# Query recurring payment records
Query recurring payment records
## Request
Facts |
---|---
HTTP URL | https://open.feishu.cn/open-apis/compensation/v1/recurring_payment/query
HTTP Method | POST
Rate Limit | [10 per second](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
Supported app types | Custom App
Required scopes
**To use this API, you must have at least 1 of the listed scopes.** | 经常性支付记录读权限(corehr:compensation.recurring_payment:read)
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.
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 | **Example value**: 10
**Data validation rules**:
- Value range: `1` ～ `500`
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**: eVQrYzJBNDNONlk4VFZBZVlSdzlKdFJ4bVVHVExENDNKVHoxaVdiVnViQT0=
user_id_type | string | Yes | User ID categories
**Example value**: open_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**: `open_id`
**When the value is `user_id`, the following field scopes are required**:
Obtain user ID(contact:user.employee_id:readonly)
### Request body
Parameter | Type | Required | Description
---|---|---|---
ids | string\[\] | No | Recurrent payment record id
**Example value**: ["7337149697626801708"]
**Data validation rules**:
- Length range: `0` ～ `500`
unique_ids | string\[\] | No | Recurring payment record unique_id, unique_id specified upstream at creation time
**Example value**: ["7337149697626801708"]
**Data validation rules**:
- Length range: `0` ～ `500`
user_ids | string\[\] | No | Employee id, specified by user_id_type in imported parameter
**Example value**: ["7337149697626801708"]
**Data validation rules**:
- Length range: `0` ～ `500`
item_ids | string\[\] | No | Salary item id (query through the [[query salary item]] (/ssl: ttdoc/uAjLw4CM/ukTMukTMukTM/compensation-v1/item/list) interface)
**Example value**: ["7337149697626801708"]
**Data validation rules**:
- Length range: `0` ～ `500`
start_date_gte | string | No | Issuance start date greater than or equal to
**Example value**: "2023-04-01"
**Data validation rules**:
- Length range: `0` ～ `255` characters
start_date_lte | string | No | Issuance start date less than or equal to
**Example value**: "2023-04-01"
**Data validation rules**:
- Length range: `0` ～ `255` characters
end_date_gte | string | No | Issuance end date greater than or equal to
**Example value**: "2025-04-01"
**Data validation rules**:
- Length range: `0` ～ `255` characters
end_date_lte | string | No | Issuance end date less than or equal to
**Example value**: "2025-08-01"
**Data validation rules**:
- Length range: `0` ～ `255` characters
create_time_gte | string | No | Creation time greater than or equal to (East 8th District)
**Example value**: "2023-04-01 12:34:56"
**Data validation rules**:
- Length range: `0` ～ `255` characters
create_time_lte | string | No | Creation time is less than or equal to (East 8th District)
**Example value**: "2023-04-01 12:34:56"
**Data validation rules**:
- Length range: `0` ～ `255` characters
modify_time_gte | string | No | Update time greater than or equal to (East 8th District)
**Example value**: "2023-04-01 12:34:56"
**Data validation rules**:
- Length range: `0` ～ `255` characters
modify_time_lte | string | No | Update time is less than or equal to (East 8th District)
**Example value**: "2023-04-01 12:34:56"
**Data validation rules**:
- Length range: `0` ～ `255` characters
company_ids | string\[\] | No | Company ID (can be queried through the [【company】](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/company/list) interface)
**Example value**: ["7337149697626801708"]
**Data validation rules**:
- Length range: `0` ～ `500`
service_company_ids | string\[\] | No | Service company ID (can be queried through the [【company】](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/company/list) interface)
**Example value**: ["7337149697626801708"]
**Data validation rules**:
- Length range: `0` ～ `500`
department_ids | string\[\] | No | Department ID (can be queried through the [【department】](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/department/batch_get) interface)
**Example value**: ["7337149697626801708"]
**Data validation rules**:
- Length range: `0` ～ `500`
job_family_ids | string\[\] | No | Job family ID (can be queried through the[【job family】](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/job_family/list) interface)
**Example value**: ["7337149697626801708"]
**Data validation rules**:
- Length range: `0` ～ `500`
job_level_ids | string\[\] | No | Job level ID (can be queried through the [【job level】](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/job_level/list) interface)
**Example value**: ["7337149697626801708"]
**Data validation rules**:
- Length range: `0` ～ `500`
work_location_ids | string\[\] | No | Work location ID (can be queried through the [【work location】](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/location/list) interface)
**Example value**: ["7337149697626801708"]
**Data validation rules**:
- Length range: `0` ～ `500`
employee_type_ids | string\[\] | No | Employee type ID (can be queried through [【employee type】](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/employee_type/list) interface)
**Example value**: ["7337149697626801708"]
**Data validation rules**:
- Length range: `0` ～ `500`
onboard_date_gte | string | No | Onboard date greater than or equal to
**Example value**: "2023-04-01"
**Data validation rules**:
- Length range: `0` ～ `255` characters
onboard_date_lte | string | No | Onboard date less than or equal to
**Example value**: "2023-04-01"
**Data validation rules**:
- Length range: `0` ～ `255` characters
offboard_date_gte | string | No | Separation date greater than or equal to
**Example value**: "2023-04-01"
**Data validation rules**:
- Length range: `0` ～ `255` characters
offboard_date_lte | string | No | Separation date less than or equal to
**Example value**: "2023-04-01"
**Data validation rules**:
- Length range: `0` ～ `255` characters
### Request body example
```json
{
"ids": [
"7337149697626801708"
],
"unique_ids": [
"7337149697626801708"
],
"user_ids": [
"7337149697626801708"
],
"item_ids": [
"7337149697626801708"
],
"start_date_gte": "2023-04-01",
"start_date_lte": "2023-04-01",
"end_date_gte": "2025-04-01",
"end_date_lte": "2025-08-01",
"create_time_gte": "2023-04-01 12:34:56",
"create_time_lte": "2023-04-01 12:34:56",
"modify_time_gte": "2023-04-01 12:34:56",
"modify_time_lte": "2023-04-01 12:34:56",
"company_ids": [
"7337149697626801708"
],
"service_company_ids": [
"7337149697626801708"
],
"department_ids": [
"7337149697626801708"
],
"job_family_ids": [
"7337149697626801708"
],
"job_level_ids": [
"7337149697626801708"
],
"work_location_ids": [
"7337149697626801708"
],
"employee_type_ids": [
"7337149697626801708"
],
"onboard_date_gte": "2023-04-01",
"onboard_date_lte": "2023-04-01",
"offboard_date_gte": "2023-04-01",
"offboard_date_lte": "2023-04-01"
}
```
## Response
### Response body
Parameter | Type | Description
---|---|---
code | int | Error codes, fail if not zero
msg | string | Error descriptions
data | \- | \-
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
records | recurring_payment\[\] | Recurring Payment Grant Record
id | string | Recurrent payment record id
unique_id | string | External idempotent id, determined by upstream business
user_id | string | Employee id, specified by user_id_type in imported parameter
item_id | string | Salary item id
issuance_type | string | Issuance type
**Optional values are**:
- with_salary：Pay with salary
- with_cash：cash distribution
- with_physical_distribution：in-kind distribution
- with_year_end_bonus：With annual bonus
each_amount | string | Single issuance amount
start_date | string | Issuance start date
end_date | string | Issuance end date
issuance_period | string | Issuance frequency
**Optional values are**:
- year：year
- half_year：half a year
- quarterly：quarter
- bimonthly：bimonthly
- month：month
- biweekly：bi-weekly
- week：week
- day：day
- hour：hour
currency_id | string | currency id
remark | string | Remarks
### Response body example
```json
{
"code": 0,
"msg": "success",
"data": {
"page_token": "eVQrYzJBNDNONlk4VFZBZVlSdzlKdFJ4bVVHVExENDNKVHoxaVdiVnViQT0=",
"has_more": true,
"records": [
{
"id": "7397033607132351532",
"unique_id": "7402510801304718380_7309316347007764012_7402523725868058156_1726070400000_10000",
"user_id": "7337149697626801708",
"item_id": "7411039006180312620",
"issuance_type": "with_salary",
"each_amount": "24.00",
"start_date": "2024-01-10",
"end_date": "2025-01-20",
"issuance_period": "year",
"currency_id": "6863329932261459464",
"remark": "这是个备注"
}
]
}
}
```
### Error code
HTTP status code | Error code | Description | Troubleshooting suggestions
---|---|---|---
400 | 2290001 | param is invalid | Parameter exception
500 | 2290002 | server error | Abnormal server level