---
title: "Search for actual payments"
method: POST
path: "/people/actual-payments/search"
tags: ["Employee Tables"]
---

# Search for actual payments

`POST /people/actual-payments/search`

This endpoint allows you to search for actual payments based on various filters.<br /> <br />  **<b>Pagination</b>** <br />  This endpoint uses cursor-based pagination to handle large number of table entries. To learn more, see <a href="https://apidocs.hibob.com/docs/pagination" target=”_blank”>Pagination in Bob's API</a> <br><br> <b>Required permissions</b><br> **For all the actual payments table entries**: People's Data > Payroll > View selected employees' Payroll section histories. <br />  **For the employees**: People's Data > Access data for > Make sure the employees are in the list. Employees that are not listed and were specifically requested will be listed under `errors` in the response. <br><br>**Testing notes**:<br/> 1. Use the testing widget's **Try It!** option to test this endpoint. <br> 2. Request Example: Use the **Examples > Request example** option to see how to initiate body parameters.<br />  3. **To test more than a single filter**, copy the example to an external API testing app like Postman for better filtering options.<br>  4. Response Example: View the response payload using the **Response > Response example** option in the response on the right.

## Request body

- ActualPaymentsSearchRequest
  - `filters` union[], required — <p>An array of filter criteria, each containing a field ID, operator, and values. Supported fields for filtering are:</p> <ul> <li>`employeeId` (required): Filter by the the employee ID. All queries must specify the employee Ids to fetch. Each call can retrieve up to 200 employees.</li> <li>`payDate` (optional): Filter by the date of the pay period.</li> </ul> <p>Important: The array must include a filter for employeeId, as it is required for all requests. <br>The structure of the filters may vary slightly depending on the field being used.</p>
    - union
      - object — Comma-separated list of employee IDs to filter by. Each call can retrieve up to 200 employees.
        - `fieldPath` string, required — The identifier of the employeeId field.
        - `operator` 'equals', required — The comparison operator for the employee IDs.
        - `values` string[], required — A comma-separated list of employeeIDs to fetch by. For example: "100001,200001". Each call can retrieve up to 200 employees.
      - object — payDate to filter by
        - `fieldPath` string, required — The payDate field ID to filter by.
        - `operator` 'greaterThanOrEquals' | 'lessThanOrEquals', required — The comparison operator when filtering by date.
        - `value` string, required — The date value to compare against.
  - `pagination` object — Optional pagination parameters.
    - `limit` number, required — Specifies the number of table entries to include on each page of the results. Defaults to 50 if not supplied.
    - `cursor` string — A marker representing the first item on the next page to read. Should not be provided in the first call. To learn more, see <a href="https://apidocs.hibob.com/docs/pagination" target="_blank">Pagination in Bob's API</a>.
  - `includeArchived` boolean — By default (false), archived columns are excluded from the response. When set to true, archived columns are included.

## Response `200`

Search results for actual payments.

- ActualPaymentsSearchResponse
  - `results` object[]
    - `employeeId` string
    - `id` number — The backend-ID of the actual payment table entry
    - `payDate` string, date
    - `payType` 'Bonus' | 'Executive bonus' | 'Commission' — The list of payment types comes with the above out-of-the-box values. To obtain additional user-defined values, you should fetch the list values call the <a href="https://apidocs.hibob.com/reference/get_company-named-lists-listname"> Get all company lists Metadata API</a> with `payType` in the listname path parameter.
    - `amount` CurrencyValue
      - `value` number, double, required
      - `currency` string, required — Three-letter currency code.
    - `change` object
      - `reason` string
      - `changedBy` string
      - `changedById` string
    - `customColumns` object
  - `response_metadata` object
    - `next_cursor` string — Contains a string value if there is a 'next' page of data. `null` if there is no more data. Use this value as the `cursor` parameter for pagination to get the next page.

## Other responses

- `400` — Bad request.
- `401` — Missing authentication credentials.
- `403` — Forbidden. The service user does not have the required permissions.

---

[API](https://skmtc.net/hibob/apis/employee-data-api.md) · [All operations](https://skmtc.net/hibob/apis/employee-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hibob/employee-data-api/revisions/0781ebbdda91/schema)