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

# Fetch attendance summaries

`POST /attendance/summaries/search`

## Request

- Base URL: `https://api.hibob.com/v1`
- URL: `https://api.hibob.com/v1/attendance/summaries/search`
- Auth: one of:
  - HTTP basic
  - HTTP bearer

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.dev/hibob/apis/attendance-api.md) - [All operations](https://skmtc.dev/hibob/apis/attendance-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hibob/apis/attendance-api/revisions/5415173dcf0d?raw)