The Time Off API enables you to manage time-off policies, user balances, and time-off requests programmatically. Integrate with your HR systems to automate leave management.
Policy types are categories of time off (e.g., Vacation, Sick Leave, Personal Days). Each policy type can contain multiple policies with different accrual rules.
Policies define the rules for a specific time-off type, including:
- Name (e.g., "Vacation - Full-time Employees")
- Unit (hours or days)
- Accrual and balance rules
Each user assigned to a policy has a balance - the amount of time off available to them.
Time-off requests are submitted by users (or on their behalf) and can be approved, pending, or denied.
| Method | Endpoint | Description |
|---|
| GET | /time-off/v1/policy-types | Get all policy types and their policies |
| Method | Endpoint | Description |
|---|
| GET | /time-off/v1/policy-types/{policyTypeId}/balances | Get user balances for a policy type |
| PUT | /time-off/v1/policy-types/{policyTypeId}/balances/{userId} | Update a user's balance |
| Method | Endpoint | Description |
|---|
| POST | /time-off/v1/requests | Create a time-off request |
| PUT | /time-off/v1/requests/{requestId} | Update a time-off request |
| Method | Endpoint | Description |
|---|
| PUT | /time-off/v1/time-off-policies/{timeOffPolicyId}/assignments | Assign user to a policy |
| Status | Description |
|---|
approved | Request has been approved |
pending | Request is awaiting approval |
denied | Request has been denied |
| Unit | Description |
|---|
hours | Balance tracked in hours |
days | Balance tracked in days |
| Constraint | Value |
|---|
| Max balances per GET | 100 |
| Date format | YYYY-MM-DD |
| Time format | HH:MM:SS |
| Timezone | Tz format (e.g., America/New_York) |
All endpoints require authentication via API key or OAuth 2.0.
| Scope | Operations |
|---|
| time_off.read | GET policy types, GET balances |
| time_off.write | PUT balances, POST/PUT requests, policy assignments |
- Get policy types to understand available time-off categories
- Assign users to policies with initial balances
- Create requests for time off (as approved or pending)
- Manage balances by updating as needed
📝Users must be assigned to a policy before you can create time-off requests or manage their balances for that policy type.
API Reference
