How to retrieve employee leave data from Breathe HR API

Introduction

This article is part of an in-depth series on the Breathe HR API and focuses on a specific, high-utility use case: fetching employee leave data. Leave data is a core HR signal and is often required for payroll processing, workforce analytics, compliance reporting, and downstream integrations with finance or planning systems.

If you are looking for a broader understanding of the Breathe HR API, including authentication, rate limits, and other supported use cases, you can refer to the comprehensive guide linked earlier in this series. This post stays focused on leave data retrieval and how to do it correctly and reliably.

Prerequisites

Before you begin, ensure the following are in place:

• Active access to the Breathe HR API with a valid API key
• A Python environment with required libraries installed (such as requests)
• Basic familiarity with making authenticated HTTP requests

API Endpoints

Get Leave Data for All Employees

Use the following endpoint to retrieve leave requests across all employees:

GET https://api.breathehr.com/v1/leave_requests

Optional query parameters:

• start_date: Returns leave requests starting on or after the specified date
• end_date: Returns leave requests starting on or before the specified date
• exclude_cancelled_requests: Excludes cancelled leave requests from the response
• page: Specifies the page of results to fetch
• per_page: Controls the number of records returned per page

Get Leave Data for a Specific Employee

To retrieve leave data for a single employee, use:

GET https://api.breathehr.com/v1/employees/{id}/leave_requests

Replace {id} with the employee’s unique identifier.

Optional query parameter:

• exclude_cancelled_requests: Excludes cancelled leave requests

Python Code Snippets

Retrieve Leave Data for All Employees

import requests

api_key = 'YOUR_API_KEY'
headers = {'Authorization': f'Bearer {api_key}'}

response = requests.get(
    'https://api.breathehr.com/v1/leave_requests',
    headers=headers
)

leave_data = response.json()
print(leave_data)

Retrieve Leave Data for a Specific Employee

import requests

employee_id = 'EMPLOYEE_ID'
api_key = 'YOUR_API_KEY'
headers = {'Authorization': f'Bearer {api_key}'}

response = requests.get(
    f'https://api.breathehr.com/v1/employees/{employee_id}/leave_requests',
    headers=headers
)

leave_data = response.json()
print(leave_data)

Common Pitfalls

1. Sending requests over HTTP instead of HTTPS, which can result in rejected or insecure calls
2. Missing or incorrectly formatted API keys in the request headers
3. Ignoring API rate limits, leading to throttling or temporary access blocks
4. Failing to implement pagination when working with large volumes of leave records
5. Not validating or handling error responses returned by the API
6. Using invalid or outdated employee IDs in employee-specific requests
7. Forgetting to explicitly exclude cancelled leave requests when required for reporting or payroll logic

Frequently Asked Questions

1. How do I obtain an API key?
   API keys are issued by Breathe HR. Contact their support team to request access.
2. What are the API rate limits?
   Rate limits are defined by Breathe HR and can vary. Refer to their official API documentation for the latest limits.
3. Can leave requests be filtered by department?
   Yes, department-level filtering is supported using the department_id query parameter where applicable.
4. How should pagination be handled?
   Use the page and per_page parameters to iterate through large result sets in a controlled manner.
5. What response format does the API return?
   All responses are returned in JSON format.
6. Is it possible to exclude cancelled leave requests?
   Yes, set exclude_cancelled_requests to avoid receiving cancelled records.
7. Is a sandbox or test environment available?
   Availability of a sandbox environment depends on your Breathe HR plan. Confirm this directly with their support team.

Knit for Breathe HR API Integration

If your goal is to minimize integration effort and long-term maintenance, Knit provides a streamlined alternative. By integrating with Knit once, you gain consistent access to the Breathe HR API without managing authentication flows, token refreshes, or ongoing API changes yourself.

This approach reduces engineering overhead, improves reliability, and allows teams to focus on using leave data rather than maintaining the integration layer.

‍