---
title: "Fetch attendance summaries"
method: POST
path: "/attendance/summaries/search"
tags: ["Attendance"]
---

# Fetch attendance summaries

`POST /attendance/summaries/search`

This endpoint returns aggregated attendance summary metrics for one or more employees within a specified date range. Results are returned as a summary per employee per date range and can include total worked hours, payable hours, overtime, breaks, and other attendance metrics (based on the fields you request).

This is a read operation that uses POST because it requires a structured request body (filters, field selection, and pagination parameters). <p><b>Before using this endpoint:</b></p> <ul> <li>Explore the <a href="/docs/explore-attendance-api" target="_blank">Attendance API</a> for more details on usage, rate limits, permissions, and more.</li> <li>You must provide both `dateRange` and `employeeId` filters in the request.</li> <li>Only fields mentioned in the `fields` parameter are returned in the response.</li> <li><b>Pagination:</b> Use `limit` and `cursor` parameters to paginate through results. The `cursor` value for the next page is returned in `response_metadata.next_cursor`. To learn more, see <a href="https://apidocs.hibob.com/docs/pagination" target="_blank">Pagination in Bob's API</a>.</li> </ul> <p><b>Testing notes</b>:</p>
  <ul>
  <li>Use the testing widget's <b>Try It!</b> option to test this endpoint.</li>
  <li>Use the <b>Examples > Request Example</b> option to see how to initiate body parameters.</li>
  </ul>

## Request body

- AttendanceSummarySearchRequest — Request schema for searching attendance summaries
  - `fields` string[], required — List of field IDs to include in the response. Standard fields are listed above. Custom fields following the pattern `/attendanceSummary/field_<number>` are also supported. **Required**: The array must include `/attendanceSummary/employeeId`.
  - `filters` object[], required — List of filters to apply. You must provide exactly two filters: 1. One `dateRange` filter (fieldId: `/attendanceSummary/dateRange`) with exactly 2 dates [startDate, endDate] 2. One `employeeId` filter (fieldId: `/attendanceSummary/employeeId`) with one or more employee IDs
    - `fieldId` '/attendanceSummary/dateRange' | '/attendanceSummary/employeeId', required — Field ID for the filter. Use `/attendanceSummary/dateRange` for date range filter or `/attendanceSummary/employeeId` for employee ID filter.
    - `operator` 'equals', required — Filter operator. Only `equals` is supported.
    - `values` string[], required — Filter values. For `dateRange` filter: provide exactly 2 dates [startDate, endDate] in ISO format (YYYY-MM-DD). For `employeeId` filter: provide one or more employee IDs.
  - `limit` integer — Maximum number of items to return per page. Defaults to 100.
  - `cursor` string — Opaque cursor for pagination. Use the value from `response_metadata.next_cursor` in the previous response to get the next page. Do not provide in the first request.
  - `includeHumanReadable` boolean — This property is not currently supported for this endpoint. Whether to include human-readable formatted values alongside raw values in the response

## Response `200`

Attendance summaries matching the search criteria

- AttendanceSummarySearchResponse
  - `items` AttendanceSummarySearchResponseObject[] — Array of attendance summary objects matching the search criteria
    - `objectType` 'attendanceSummary' — Type of the object
    - `fields` object — Attendance summary fields. Only fields requested in the search are included.
      - `/attendanceSummary/employeeId` object — The employee ID
        - `value` string
      - `/attendanceSummary/dateRange` object — The date range that was requested for this summary
        - `value` string[] — Array with two dates [startDate, endDate] in ISO format
      - `/attendanceSummary/hoursWorked` object — Total hours worked in the date range
        - `value` number, double
      - `/attendanceSummary/potentialHours` object — Total potential hours based on attendance policy
        - `value` number, double
      - `/attendanceSummary/payableHours` object — Total payable hours (worked hours + adjustments)
        - `value` number, double
      - `/attendanceSummary/regularHours` object — Regular working hours (excluding overtime)
        - `value` number, double
      - `/attendanceSummary/overtimeHours` object — Overtime hours
        - `value` number, double
      - `/attendanceSummary/doubleOvertimeHours` object — Double overtime hours
        - `value` number, double
      - `/attendanceSummary/unpaidBreaks` object — Total unpaid break hours deducted
        - `value` number, double
      - `/attendanceSummary/premiumPayEligibleHours` object — Hours eligible for premium pay (e.g., bank holidays)
        - `value` number, double
      - `/attendanceSummary/specialRateEligibleHours` object — Hours eligible for premium pay on days covered by the policy’s special day-of-week rate (for example configured weekends or other off days). If that day is a bank holiday, bank holiday premium rules apply instead.
        - `value` number, double
      - `/attendanceSummary/totalOvertimeHours` object — Total overtime hours (overtime + double overtime)
        - `value` number, double
      - `/attendanceSummary/offset` object — Difference between potential hours and payable hours
        - `value` number, double
      - `/attendanceSummary/workedRegularHours` object — Regular hours actually worked (excluding overtime)
        - `value` number, double
  - `response_metadata` object
    - `next_cursor` string, nullable — Opaque cursor for the next page. Provide this value in the `cursor` parameter of the next request to get the next page. When null, there are no more pages.

## Other responses

- `400` — The request is malformed or includes invalid parameters
- `401` — Authentication failed. Check your service user credentials
- `403` — The service user or token is missing the required permissions to access the requested data
- `404` — Feature not enabled for this company
- `429` — Rate limit exceeded - see <a href="https://apidocs.hibob.com/reference/attendance#rate-limiting">Rate limits</a>
- `500` — An unexpected error occurred. Try again or contact support if the issue persists.

---

[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/versions/0781ebbdda91/schema)