The Leave Balance API and Webhooks: A Developer's Guide

Leave Balance exposes a REST API and a webhook system for developers who need to integrate leave data with custom applications, internal tools, or payroll systems that do not have a native integration. The API provides read and write access to leave requests, balances, employees, and policies. Webhooks push real-time event notifications to your application when something changes in Leave Balance.

This guide covers authentication, key endpoints, webhook configuration, and example payloads. It is written for developers who will be implementing the integration.

Key Takeaways

• The REST API provides full CRUD access to leave requests, balances, employees, and policies
• Webhooks push real-time notifications when leave is requested, approved, cancelled, or balances change
• Authentication uses API keys with role-based permissions scoped to your workspace

Why an API Matters for Leave Management

Most leave management integrations are point-to-point: Slack, Xero, Google Calendar. These cover common use cases, but every organisation has internal tools or custom workflows that need leave data. An API gives developers the flexibility to build any integration without waiting for a native connector.

Common API use cases include:

• Custom payroll integration. Push approved leave data to an internal payroll system that is not supported by a native integration.
• Reporting dashboard. Pull leave data into an internal analytics tool that aggregates HR, payroll, and operational data.
• Employee self-service portal. Display leave balances and history in an existing employee portal built on your company’s internal platform.
• Compliance audit export. Programmatically export leave records for audit or regulatory compliance purposes.
• Custom notification system. Trigger internal notifications when leave events occur, such as posting to an internal chat tool or creating an IT ticket for device access changes.

Webhooks complement the API by pushing data instead of requiring you to poll for changes. This reduces latency and API usage.

Authentication

All API requests require an API key sent in the Authorization header:

Authorization: Bearer YOUR_API_KEY

API keys are workspace-scoped. Each key has role-based permissions that determine what it can access:

Permission	Description
leave_requests:read	View leave requests
leave_requests:write	Create and update leave requests
balances:read	View employee leave balances
employees:read	View employee records
policies:read	View leave policies
webhooks:manage	Create and manage webhook subscriptions

Generate an API key in Settings > API Keys > Generate New Key. Store the key securely — it is displayed once and cannot be retrieved.

Key API Endpoints

Leave Requests

Method	Endpoint	Description
GET	/api/v1/leave-requests	List all leave requests with filtering
GET	/api/v1/leave-requests/:id	Get a specific leave request
POST	/api/v1/leave-requests	Create a new leave request
PATCH	/api/v1/leave-requests/:id	Update a leave request (approve, reject, cancel)

Query parameters for listing:

• status — Filter by pending, approved, rejected, or cancelled
• employee_id — Filter by employee
• leave_type — Filter by leave type (e.g., annual, sick, personal)
• from and to — Date range filter (ISO 8601 format)

Leave Balances

Method	Endpoint	Description
GET	/api/v1/balances	List all employee balances
GET	/api/v1/balances/:employee_id	Get balances for a specific employee

Employees

Method	Endpoint	Description
GET	/api/v1/employees	List all employees
GET	/api/v1/employees/:id	Get a specific employee

Policies

Method	Endpoint	Description
GET	/api/v1/policies	List all leave policies
GET	/api/v1/policies/:id	Get a specific policy

Webhooks

Webhooks push event notifications to your application when something changes in Leave Balance. Configure webhook subscriptions in Settings > Webhooks.

Supported Events

Event	Description
leave_request.created	A new leave request is submitted
leave_request.approved	A leave request is approved
leave_request.rejected	A leave request is rejected
leave_request.cancelled	A leave request is cancelled
balance.updated	An employee’s leave balance changes

Webhook Payload

{
  "event": "leave_request.approved",
  "timestamp": "2026-07-26T10:30:00Z",
  "data": {
    "id": "lr_abc123",
    "employee_id": "emp_xyz789",
    "employee_name": "Sarah Chen",
    "leave_type": "annual",
    "start_date": "2026-08-01",
    "end_date": "2026-08-05",
    "days": 5,
    "status": "approved",
    "approved_by": "mgr_001",
    "approved_at": "2026-07-26T10:30:00Z"
  }
}

Webhook Security

Each webhook request is signed with an HMAC-SHA256 signature in the X-LeaveBalance-Signature header. Verify the signature against your webhook secret to ensure the payload has not been tampered with.

Retry Policy

Failed webhook deliveries (non-2xx response) are retried up to 5 times with exponential backoff: 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours. After 5 failed attempts, the event is logged in the webhook delivery history for manual review.

Rate Limits

Plan	Requests per minute
Standard	60
Professional	300
Enterprise	1,000

Rate limit headers (X-RateLimit-Remaining, X-RateLimit-Reset) are included in every API response.

Best Practices

• Use webhooks for real-time data. Do not poll the API for changes. Webhooks push data to you, which is faster and uses fewer API calls.
• Verify webhook signatures. Always check the X-LeaveBalance-Signature header to prevent spoofed payloads.
• Handle idempotency. Webhook events include a unique event_id. Use it to prevent duplicate processing if an event is delivered more than once.
• Implement retry logic on your end. If your webhook endpoint returns a non-2xx status, Leave Balance will retry. Make sure your endpoint is idempotent so retries do not create duplicate records.
• Cache employee and policy data. Employee and policy data do not change frequently. Cache these responses and refresh periodically instead of fetching on every request.

FAQ

Where do I get API documentation?

The full OpenAPI specification is available at api.leavebalance.com/docs. It includes all endpoints, request/response schemas, and example payloads.

Can I create leave requests through the API?

Yes. The POST /api/v1/leave-requests endpoint creates leave requests. The request is subject to the same validation and approval workflow as requests created through the UI.

Do I need separate API keys for different environments?

Yes. Each Leave Balance workspace (development, staging, production) has its own API keys. Generate a separate key for each environment.

What happens if I exceed the rate limit?

API requests that exceed the rate limit return a 429 Too Many Requests response. The Retry-After header indicates how many seconds to wait before retrying.

Can I use the API for employee onboarding?

Yes. The employee API supports creating new employee records. This is useful for bulk onboarding from an internal HRIS or ATS system.