---
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}`

## Request

- Base URL: `https://gateway.remote.com`
- URL: `https://gateway.remote.com/v1/timeoff-balances/{employment_id}`
- Auth: one of:
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `https://gateway.remote.com/company.manage`
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `timeoff:read`
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `all:read`
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `all:write`
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `timeoff:read`
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `all:read`
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `all:write`
  - HTTP bearer

> **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.

## Authentication

This endpoint accepts any one of the following token types:

- **Company-scoped access token** (`OAuth2AuthorizationCode`) — obtained by a company manager through the Authorization Code flow or the Refresh Token flow. See [Authentication for partners](https://developer.remote.com/docs/authentication-for-partners).
- **Company-scoped access token (assertion)** (`OAuth2CompanyManagerAssertion`) — obtained through the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant for a company manager. See [OAuth Assertion](https://developer.remote.com/docs/authorization-method-oauth-assertion).
- **Customer API token** (`CustomerAPIToken`) — generated by the customer on their Integration Settings page, with the scopes they choose there. See [Authorization for customers](https://developer.remote.com/docs/authorization-for-customers).

## Scopes

Any one of the scopes in a token type's row is enough. `all:read` and `all:write` work too.

| Token type | Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|---|
| Company-scoped access token | Manage timeoffs (`time_and_attendance`) | View timeoffs (`timeoff:read`) | Manage timeoffs (`timeoff:write`) |
| Company-scoped access token (assertion) | Manage timeoffs (`time_and_attendance`) | View timeoffs (`timeoff:read`) | Manage timeoffs (`timeoff:write`) |
| Customer API token | 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.dev/remote-com/apis/time-attendance.md) - [All operations](https://skmtc.dev/remote-com/apis/time-attendance/llms.txt) - [OpenAPI document](https://skmtc.dev/remote-com/apis/time-attendance/revisions/84de0ccef126?raw)