Contact Us
Time Off Balances
The balance object
| Attribute | Type | Description |
|---|---|---|
pto_type |
object | Nested time off policy object containing id, name, color, and icon. |
is_requestable |
boolean | Whether the policy is currently active and requestable by the user. |
year |
integer | The reporting year evaluated for the balance. |
as_of |
date | The evaluation date of the balance. |
is_unlimited |
boolean | Whether this policy has unlimited allowance. |
requires_approval |
boolean | Whether requests booked under this policy require approval. |
effective_accrual_type |
string | Effective accrual mode for this user and policy. |
accrual_schedule |
string | Effective accrual interval. |
accrued_days |
decimal | Days accrued as of the balance date. |
carryover_days |
decimal | Carryover days credited from the previous year. |
available_days |
decimal | Total days available to take for the year. |
used_days |
decimal | Confirmed days already taken. |
pending_days |
decimal | Days requested that are pending approval. |
remaining_days |
decimal | Available days minus used and pending days. |
used_hours |
decimal | Working hours already used. |
pending_hours |
decimal | Working hours pending approval. |
used_fraction |
decimal | Fraction of days used. |
pending_fraction |
decimal | Fraction of days pending. |
Required permissions
The PTO API is currently being rolled out gradually. Requests from unavailable accounts return 403 Forbidden.
Administrators can retrieve time off balances for any user in the company.
Non-administrators can only retrieve their own time off balances. Naming another user in user_id will result in a 403 Forbidden status code.
Retrieve time off balances
Returns time off balances broken down per policy for a specific user and year.
GET /v2/pto/balances
| Parameter | Type | Description |
|---|---|---|
user_id |
integer | The ID of the user. Optional for administrators (defaults to authenticated user). Non-administrators must leave empty or specify their own ID. |
year |
integer | The year to calculate balances for (defaults to current year). |
as_of |
date | Calculate balances as of this date (defaults to today). |
Example Request:
curl "https://api.harvestapp.com/v2/pto/balances?year=2026" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"user": {
"id": 1782959,
"name": "Kim Allen"
},
"year": 2026,
"as_of": "2026-09-03",
"balances": [
{
"pto_type": {
"id": 101,
"name": "Vacation",
"color": "blue",
"icon": "vacation"
},
"is_requestable": true,
"year": 2026,
"as_of": "2026-09-03",
"is_unlimited": false,
"requires_approval": true,
"effective_accrual_type": "fixed",
"accrual_schedule": "monthly",
"accrued_days": "25.0",
"carryover_days": "2.0",
"available_days": "27.0",
"used_days": "10.0",
"pending_days": "3.0",
"remaining_days": "14.0",
"used_hours": "80.0",
"pending_hours": "24.0",
"used_fraction": "0.3704",
"pending_fraction": "0.1111"
}
]
}