Fetch Employee Data from Humi HR API with Python

Introduction

This article is part of an ongoing series that explores the Humi HR API 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.

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

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

Step-by-Step Guide

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 = {
    "Authorization": "Bearer your-token-here"
}
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 = {
    "Authorization": "Bearer your-token-here"
}

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.

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. 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.