---
title: "Fetch Employee Data from Humi HR API with Python"
description: "Learn how to fetch employee data using the Humi HR API. This guide covers prerequisites, endpoints, pagination, common pitfalls, FAQs, and best practices for reliable Humi HR API integration."
source_url: "https://www.getknit.dev/blog/fetch-employee-data-from-humi-hr-api-with-python"
page_type: "blog"
---

_This is an educational blog post from Knit's blog: “Fetch Employee Data from Humi HR API with Python”._

# Fetch Employee Data from Humi HR API with Python

## Introduction

This article is part of an ongoing series that explores the [**Humi HR API**](https://www.getknit.dev/blog/humi-api-directory-5N1RxB) in depth. In this post, we focus specifically on how to retrieve employee data using the Humi HR API, one of the most commonly used use cases when integrating HR systems.

If you’re looking for a broader overview of HR APIs, including authentication, rate limits, and other supported endpoints, you can find the complete guide [here](https://www.getknit.dev/blog/everything-you-need-to-know-about-hris-api-integration).

### Prerequisites

Before you can access employee data from the Humi HR API, ensure the following:

*   You have a **Humi Partners API Token**
*   The token is included in the `Authorization` header for every request
*   API tokens are issued by Humi and must be requested by contacting [**support@humi.ca**](mailto:support@humi.ca)

Without a valid token, requests to the employee endpoints will fail.

### 1\. Retrieve All Employees

To fetch a list of all employees, send a `GET` request to the `/v1/employees` endpoint.  
The API supports pagination, allowing you to control how many records are returned per request.

```
import requests

url = "https://partners.humi.ca/v1/employees"
headers = {
}
params = {
    "page[size]": 5,
    "page[number]": 1
}

response = requests.get(url, headers=headers, params=params)
print(response.json())
```

Use pagination parameters to efficiently process large employee datasets and avoid oversized responses.

### 2\. Retrieve a Specific Employee

To retrieve details for a single employee, use the employee ID with the `/v1/employees/:employeeId` endpoint.

```
import requests

employee_id = "valid-employee-id-here"
url = f"https://partners.humi.ca/v1/employees/{employee_id}"
headers = {
}

response = requests.get(url, headers=headers)
print(response.json())
```

This endpoint is useful when syncing or updating records for a specific employee rather than pulling the full directory.

## Common Pitfalls to Avoid

*   **API token exposure**  
    Never hard-code or publicly share your Humi API token. Treat it like a password.
*   **Ignoring pagination limits**  
    The maximum supported page size is **25**. Requests exceeding this limit may fail or return unexpected results.
*   **Assuming deleted employees are included**  
    Deleted employee records are not returned by the API and should not be expected in responses.
*   **Missing authorization headers**  
    Every request must include a valid `Authorization: Bearer` header, or it will be rejected.

## FAQs

**1\. How do I get a Humi Partners API token?**  
You must request the token directly from Humi by contacting [**support@humi.ca**](mailto:support@humi.ca).

**2\. What authentication method does the Humi HR API use?**  
The API uses Bearer token–based authentication via the `Authorization` header.

**3\. What is the maximum number of employees returned per request?**  
The maximum page size is **25** records per request.

**4\. Can I retrieve terminated or deleted employees?**  
No. Deleted employees are not included in API responses.

**5\. Does the API support pagination?**  
Yes. Pagination is supported using `page[size]` and `page[number]` parameters.

**6\. What happens if my token is invalid or expired?**  
The API will return an authorization error, and the request will fail.

**7\. Can I use this API for real-time employee syncs?**  
The API supports programmatic access, but sync frequency should respect pagination limits and API usage guidelines.

## Knit for Humi HR API Integration

If you’re looking to reduce integration overhead, **Knit** provides a faster way to work with the [Humi HR API](https://www.getknit.dev/integration/humi-hr). By integrating with Knit once, you can avoid managing authentication, token handling, and long-term maintenance yourself.

Knit handles authorization, API changes, and operational complexity, allowing you to focus on consuming employee data instead of maintaining the integration.


## Related pages

- [How Knit works](https://md.getknit.dev/how-knit-works)
- [Unified API product](https://md.getknit.dev/products/unified-api)