---
title: "List of yearly leave balances for each leave type."
method: GET
path: "/v2/providers/employers/employees/employments/{employmentId}/leavebalances"
tags: ["Leave balance"]
---

# List of yearly leave balances for each leave type.

`GET /v2/providers/employers/employees/employments/{employmentId}/leavebalances`

## Request

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

__Activity name :__ <a href="https://developer.loket.nl/Activities/GetLeaveBalancesByEmploymentId" target="_blank">GetLeaveBalancesByEmploymentId</a> <br/>  <br/>  Returns the yearly leave balances for each leave type.

## Path parameters

- `employmentId` string, uuid, required

## Query parameters

- `filter` string
- `orderBy` string
- `pageNumber` integer
- `pageSize` integer

## 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
  - `_embedded` LeaveBalance[]
    - `year` integer: The year to which the balance of the leave type applies.
    - `leaveType` object: 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.
    - `usageThroughToday` number, double: The amount of leave units used for the leave type starting from the beginning of the year up to and including the referenceDate.
    - `usageAfterToday` number, double: The amount of leave units used for the leave type in the year after the referenceDate.
    - `usageFirstHalfYear` number, double: The amount of leave units used for the leave type in the first half of the year
    - `balance` number, double: The remaining leave balance for the year and leave type. The balance takes into account the leave usage in the future.
    - `unitType` object, nullable: If known indicates what the unit type (hours or days) is for `balance`, `usageAfterToday`, `usageThroughToday` , `usageTotal` , `accrual` and `balancePreviousYear` . Otherwise the field will be null.
      - `key` integer: The key for the unit type
      - `value` string: The description for the unit type
    - `expires` number, double: <ul> <li>This field is only relevant for the following leave types:</li> <li><strong>Wettelijk verlof:</strong> Accrued statutory leave from previous years that expires on July 1 of the selected year.</li> <li><strong>Bovenwettelijk verlof:</strong> Accrued extra-legal leave from 5 years ago and earlier, which expires on Jan 1 of the selected year + 1.</li> <li><strong>Verlof:</strong> The sum of the two leave types above.</li> </ul>

## 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)