---
title: "Summed up leave balance total and grouped by"
method: GET
path: "/v2/providers/employers/{employerId}/leavebalances/grouped"
tags: ["Leave balance"]
---

# Summed up leave balance total and grouped by

`GET /v2/providers/employers/{employerId}/leavebalances/grouped`

## Request

- Base URL: `https://api.loket.nl`
- URL: `https://api.loket.nl/v2/providers/employers/{employerId}/leavebalances/grouped`
- Auth: none required

__Activity name :__ <a href="https://developer.loket.nl/Activities/GetLeaveBalancesGroupedByEmployerId" target="_blank">GetLeaveBalancesGroupedByEmployerId</a> <br/>  <br/>  Returns the yearly leave balances total per leave type and total per groupBy

## Path parameters

- `employerId` string, uuid, required

## Query parameters

- `referenceDate` string, date
- `leaveType` integer[]
- `orderBy` string
- `pageNumber` integer
- `pageSize` integer
- `groupBy` 'Department' | 'Function', required

## Headers

- `Authorization` string, required
- `Accept` string, required

## Response `200`

OK

- object: a warning indacateds that the given payload is valide, however take notice of the warning this might ifluence behavour.
  - `totalSize` integer: Total number of records, taking into account the given filter.
  - `pageSize` integer: Number of records in the response
  - `totalPages` integer: Number of pages available
  - `currentPage` integer: Current page returned in the response
  - `version` Version
    - `obsoleteDate` string, date, nullable: The date (can be null) on which the `resourceVersion` is no longer supported/available
    - `resourceVersion` string, date: The resource version of the object in the response
  - `messages` object[]
    - `type` string: Indication of the type of message. See [the general documentation for more information](./#section/Response/Messages)
    - `description` string: Describes the message
    - `id` string, uuid, nullable: In some cases when the message may relate to a specific entity, or specific group of entities, this field provides the identifier of that entity
    - `code` integer: Identifying code for the message
    - `properties` string[]: An array that can contain additional information
  - `content` LeaveBalanceEmployerGroupedBy
    - `totals` object[]: Returns the total sum of a leave type for all employments
      - `year` integer: The year to which the balance of the leave type applies.
      - `leaveType` LeaveType3: The type of leave requested by the employee `leaveType` is a metadata field within the employer context. Possible values can be managed by the user.
        - `key` integer: The key for the leave type.
        - `value` string: The description for the leave type. Note that leave types can be overridden at the employer level. In these cases the description at the employer level takes precedence over the default description of the leave type.
        - `balanceExceedsYear` boolean: Indicates whether the balance at the end of the year for this leave type carries over to the next year.
      - `balancePreviousYear` number, double: The remaining leave balance from the previous year for the leave type
      - `accrual` number, double: The amount of leave units accrued for the leave type in the year
      - `usageTotal` number, double: The total amount of leave units used for the leave type in the year.
      - `usageThroughReferenceDate` number, double: The amount of leave units used for the leave type starting from the beginning of the year up to and `referenceDate`
      - `usageAfterReferenceDate` number, double: The amount of leave units used for the leave type in the year after `referenceDate`
      - `balance` number, double: The remaining leave balance for the year and leave type. The balance takes into account the leave usage in the future.
    - `groups` object[]: Returns the total sum of a leave type for all employments in the given group by
      - `group` GroupBy
        - `id` string, uuid: The unique identifier of an object (GUID/UUID)
        - `description` string: The description of the groupBy, either the department or function
      - `year` integer: The year to which the balance of the leave type applies.
      - `leaveType` LeaveType3: The type of leave requested by the employee `leaveType` is a metadata field within the employer context. Possible values can be managed by the user.
        - `key` integer: The key for the leave type.
        - `value` string: The description for the leave type. Note that leave types can be overridden at the employer level. In these cases the description at the employer level takes precedence over the default description of the leave type.
        - `balanceExceedsYear` boolean: Indicates whether the balance at the end of the year for this leave type carries over to the next year.
      - `balancePreviousYear` number, double: The remaining leave balance from the previous year for the leave type
      - `accrual` number, double: The amount of leave units accrued for the leave type in the year
      - `usageTotal` number, double: The total amount of leave units used for the leave type in the year.
      - `usageThroughReferenceDate` number, double: The amount of leave units used for the leave type starting from the beginning of the year up to and `referenceDate`
      - `usageAfterReferenceDate` number, double: The amount of leave units used for the leave type in the year after `referenceDate`
      - `balance` number, double: The remaining leave balance for the year and leave type. The balance takes into account the leave usage in the future.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `500`: Internal Server Error

---

[API](https://skmtc.dev/loket/apis/loket-api.md) - [All operations](https://skmtc.dev/loket/apis/loket-api/llms.txt) - [OpenAPI document](https://skmtc.dev/loket/apis/loket-api/revisions/32170564148f?raw)