Time & Attendance
Time Off Balances

Show Time Off Balance

Changed on

Shows the time off balance for the given employment_id.

Deprecated since February 2025 in favour of List Leave Policies Summary endpoint.

Authentication

This endpoint accepts any one of the following token types:

  • Company-scoped access token (OAuth2AuthorizationCode) — obtained through the Authorization Code flow or the Refresh Token flow. See Authentication for partners.
  • Customer API token (CustomerAPIToken) — generated by the customer on their Integration Settings page. See Authorization for customers.

Scopes

CategoryRead only ScopeWrite only Scope (read access implicit)
Manage timeoffs (time_and_attendance)View timeoffs (timeoff:read)Manage timeoffs (timeoff:write)
get/v1/timeoff-balances/{employment_id}

Request

  • Base URL: https://gateway.remote.com
  • URL: https://gateway.remote.com/v1/timeoff-balances/{employment_id}
  • Auth: HTTP bearer and OAuth 2 (authorization code, authorization URL /auth/oauth2/authorize, token URL /auth/oauth2/token, scopes: https://gateway.remote.com/company.manage, timeoff:read, timeoff:write, time_and_attendance, all:write, all:read)

Path parameters

employment_idstring required

Employment ID for which to show the time off balance

Headers

Authorizationstring required

Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.

The refresh token needs to have been obtained through the Authorization Code flow.

Response

Success

Example response

{
  "data": {
    "timeoff_balance": {
      "contractual_entitled": {
        "days": 25,
        "hours": 0
      },
      "leave_entitlements": [
        {
          "entitled": {
            "days": 28,
            "hours": 0
          },
          "expiry_date": "2022-12-31",
          "name": "Annual paid time off",
          "remaining": {
            "days": 25,
            "hours": 0
          },
          "taken": {
            "days": 3,
            "hours": 0
          },
          "type": "annual_paid_timeoff"
        },
        {
          "entitled": {
            "days": 3,
            "hours": 0
          },
          "expiry_date": "2022-12-31",
          "name": "Extra days for good performance",
          "remaining": {
            "days": 3,
            "hours": 0
          },
          "taken": {
            "days": 0,
            "hours": 0
          },
          "type": "additional_pto"
        }
      ],
      "taken": {
        "days": 3,
        "hours": 0
      },
      "total_entitled_days": 31,
      "working_hours_per_day": 8
    }
  }
}

Changes

  • 84069084fd5eRevision changes
    • warning

      added the new resource_not_found enum value to the /// response property for the response status