Time off & holidays

Get Hris Employee Leave Balance

Returns per-leave-type taken, pending, statutory and entitlement figures for an employee and year.

GEThttps://api.toku.com/hris/get-hris-employee-leave-balance

Required scope: time:read. With an API key, roleInOrgID must be set: a key has no person of its own.

curl --request GET \
  --url 'https://api.toku.com/hris/get-hris-employee-leave-balance' \
  --header 'Authorization: Bearer <token>'
200 response
{
  "roleInOrgID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "year": 0,
  "countryCode": "string",
  "balances": [
    {
      "leaveType": "string",
      "daysTaken": 0,
      "pendingDays": 0,
      "statutoryMinimumDays": 0,
      "policyType": "string",
      "isHalfDayAllowed": true,
      "leaveTypeKey": "string",
      "leaveTypeKind": "builtin",
      "customLeaveTypeID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "displayName": "string",
      "countsAsLeaveType": "string",
      "entitlementPolicyType": "string",
      "entitlementTotalPerYear": 0,
      "entitlementSource": "string",
      "accrualFrequency": "string",
      "accrualEffectiveFrom": "2026-01-01",
      "accruedToDate": 0,
      "accruedRemainingDays": 0,
      "accrualHistory": [
        {
          "periodKey": "string",
          "periodStart": "2026-01-01",
          "periodEnd": "2026-01-01",
          "days": 0,
          "isProrated": true,
          "source": "string",
          "postedAt": "2026-01-01T00:00:00Z"
        }
      ],
      "openingBalanceDays": 0,
      "openingBalanceNote": "string"
    }
  ],
  "vacation": {
    "year": 0,
    "vacationCustomLeaveTypeIDs": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "statutory": {
      "entitledDays": 0,
      "takenDays": 0,
      "upcomingDays": 0,
      "pendingDays": 0,
      "availableDays": 0,
      "source": "country_rule",
      "minimumDays": 0,
      "carriedOverDays": 0,
      "nextExpiry": {
        "days": 0,
        "on": "2026-01-01"
      },
      "mandatoryUse": {
        "requiredDays": 0,
        "usedDays": 0,
        "useByDate": "2026-01-01",
        "status": "MET"
      }
    },
    "company": {
      "entitledDays": 0,
      "takenDays": 0,
      "upcomingDays": 0,
      "pendingDays": 0,
      "availableDays": 0,
      "policy": "string",
      "customLeaveTypeID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string"
    },
    "overBalanceDays": 0,
    "requests": [
      {
        "hrisTimeOffID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "status": "REQUESTED",
        "statutoryDays": 0,
        "companyDays": 0,
        "overBalanceDays": 0
      }
    ]
  }
}

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is an access token from a Toku sign-in. See Authentication in the API reference.

Query parameters

roleInOrgIDstring<uuid>
yearinteger

Allowed: 2000 to 2100

Response

200Successful response
roleInOrgIDstring<uuid>required
yearintegerrequired
countryCodestring | nullrequired
balancesobject[]required
Show child attributes
leaveTypestringrequired
daysTakennumberrequired
pendingDaysnumberrequired
statutoryMinimumDaysnumber | nullrequired
policyTypestring | nullrequired
isHalfDayAllowedbooleanrequired
leaveTypeKeystringrequired
leaveTypeKindstringrequired

Available options: builtin, custom

customLeaveTypeIDstring | null<uuid>required
displayNamestring | nullrequired
countsAsLeaveTypestring | nullrequired
entitlementPolicyTypestring | nullrequired
entitlementTotalPerYearnumber | nullrequired
entitlementSourcestring | nullrequired
accrualFrequencystring | nullrequired
accrualEffectiveFromstring | null<date>required
accruedToDatenumber | nullrequired
accruedRemainingDaysnumber | nullrequired
accrualHistoryobject[]required
Show child attributes
periodKeystringrequired
periodStartstring<date>required
periodEndstring<date>required
daysnumberrequired
isProratedbooleanrequired
sourcestringrequired
postedAtstring<date-time>required
openingBalanceDaysnumberrequired
openingBalanceNotestring | nullrequired
vacationobjectrequired
Show child attributes
yearintegerrequired
vacationCustomLeaveTypeIDsstring<uuid>[]required
statutoryobject | nullrequired
Show child attributes
entitledDaysnumber | nullrequired
takenDaysnumberrequired
upcomingDaysnumberrequired
pendingDaysnumberrequired
availableDaysnumber | nullrequired
sourcestringrequired

Available options: country_rule, employee_entitlement

minimumDaysnumber | nullrequired
carriedOverDaysnumberrequired
nextExpiryobject | nullrequired
Show child attributes
daysnumberrequired
onstring<date>required
mandatoryUseobject | nullrequired
Show child attributes
requiredDaysnumberrequired
usedDaysnumberrequired
useByDatestring<date>required
statusstringrequired

Available options: MET, ON_TRACK, AT_RISK, NOT_MET

companyobject | nullrequired
Show child attributes
entitledDaysnumber | nullrequired
takenDaysnumberrequired
upcomingDaysnumberrequired
pendingDaysnumberrequired
availableDaysnumber | nullrequired
policystringrequired
customLeaveTypeIDstring | null<uuid>required
namestringrequired
overBalanceDaysnumberrequired
requestsobject[]required
Show child attributes
hrisTimeOffIDstring<uuid>required
statusstringrequired

Available options: REQUESTED, APPROVED, REJECTED, CANCELLED

statutoryDaysnumberrequired
companyDaysnumberrequired
overBalanceDaysnumberrequired
400Bad request
401Unauthorized
403Forbidden
404Not found
409Conflict
429Response 429
Was this page helpful? Suggest edits