---
title: "Show Time Off Balance"
method: GET
path: "/v1/timeoff-balances/{employment_id}"
tags: ["Time Off Balances"]
deprecated: true
---

# Show Time Off Balance

`GET /v1/timeoff-balances/{employment_id}`

> **Deprecated.**

Shows the time off balance for the given employment_id.

Deprecated since February 2025 in favour of **[List Leave Policies Summary](#tag/Leave-Policies/operation/get_index_leave_policies_summary)** endpoint.


## Scopes

| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage timeoffs (`time_and_attendance`) | View timeoffs (`timeoff:read`) | Manage timeoffs (`timeoff:write`) |

## Path parameters

- `employment_id` string, required

## Headers

- `Authorization` string, required

## Response `200`

Success

- TimeoffBalanceResponse — Time Off Balance response
  - `data` object, required
    - `timeoff_balance` TimeoffBalance, required
      - `contractual_entitled` integer — Number of time off days for the employment, based on their contract. The value of this field is `0` if the employment's contract does not include that information.
      - `contractual_leave_entitlement_type` string, required — Leave entitlement type for the employment, based on their contract. The value of this field is `fixed` when the employment has a fixed limit of time off days to be taken, and `unlimited` otherwise.
      - `taken` object, nullable, required — Number of time off days taken by the employment as of today. You can get a list of taken time off data for this employment using the [list time off endpoint](#tag/Time-Off/operation/get_index_timeoff).
        - `days` integer — The number of whole days.
        - `hours` integer — The number of additional hours beyond whole days.
      - `timeoff_entitlements` TimeoffEntitlement[], required — A list of individual time off entitlements for the employment. This list gives more granular details for the type of time off that's available to the employment.
        - `can_expire` boolean, required — Indicates whether this entitlement can expire. When `false`, `expiry_date` will be `nil`.
        - `entitled` object, required — Indicates how much this time off this entitlement contributes to the total time off entitlement.
          - `days` integer — The number of whole days.
          - `hours` integer — The number of additional hours beyond whole days.
        - `expiry_date` string, date, nullable, required — Indicates the date this entitlement expires and is no longer counted towards the total time off entitlement for the employment. When this entitlement doesn't expire, `expiry_date` will be set to `nil`. Use the `can_expire` parameter to determine whether an entitlement can expire or not.
        - `name` string, nullable, required — A human-readable name for this entitlement (e.g., "Annual paid time off", "Extra days for good performance"). Null for the default contractual entitlement.
        - `remaining` object, required — Indicates how much time off the employment has remaining in this entitlement.
          - `days` integer — The number of whole days.
          - `hours` integer — The number of additional hours beyond whole days.
        - `taken` object, required — Indicates how much time off the employment has taken from this entitlement.
          - `days` integer — The number of whole days.
          - `hours` integer — The number of additional hours beyond whole days.
        - `type` 'carryover_pto' | 'additional_pto' | 'transfer_pto' | 'annual_paid_timeoff', required — Indicates the type of the time off entitlement. `annual_paid_timeoff` entitlements are calculated from the employment's contract. All other time off entitlements are granted by the employer or automatically by the country of employment.
      - `total_entitled_days` integer — Number of time off days for the employment, based on their contract and any additional time off that's granted to them. This is the sum of all `entitled` fields in the `leave_entitlements` array, but does not take the hours into account.
      - `upcoming_approved` object, nullable, required — Number of future, approved time off days for the employment, as of today. You can get a list of approved time off data for this employment using the [list time off endpoint](#tag/Time-Off/operation/get_index_timeoff).
        - `days` integer — The number of whole days.
        - `hours` integer — The number of additional hours beyond whole days.
      - `upcoming_requested` object, nullable, required — Number of future, requested time off days for the employment, as of today. You can get a list of requested time off data for this employment using the [list time off endpoint](#tag/Time-Off/operation/get_index_timeoff).
        - `days` integer — The number of whole days.
        - `hours` integer — The number of additional hours beyond whole days.
      - `working_hours_per_day` integer, required — The number of working hours per day as defined in the employment's contract. Used to convert between days and hours.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — TimeoffBalanceNotFoundResponse
- `422` — Unprocessable Entity
- `429` — Too many requests

---

[API](https://skmtc.net/remote-com/apis/remote.md) · [All operations](https://skmtc.net/remote-com/apis/remote/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/remote-com/remote/revisions/7e6a0c61ac82/schema)