Developer guide to get employee data from HR One API

Introduction

This guide is part of our ongoing series exploring HRIS APIs in depth. In this edition, we’ll walk through how to retrieve employee data from the HR One API , from setup to execution, and help you avoid common integration mistakes.

This guide covers both fetching a single employee’s record and syncing a full employee database, with practical Python examples for each.

To get more details on HR One API, click here.

Getting Employee Data from HR One API

Overview

The HR One API provides endpoints to fetch both standard and custom employee data. You can use it to retrieve information for one employee or all employees, depending on your business needs.

Prerequisites

Before you begin, ensure you have:

• Valid access credentials for the HR One API (with employees:read permission).
• A Python environment with the requests library installed.

API Endpoints

• Get Employee Information:
  https://hronemanagedapi.hrone.cloud/dev/api/external/employees
• Get Employee Custom Information:
  https://hronemanagedapi.hrone.cloud/dev/api/external/getempinfo

Step-by-Step Implementation

1. Set up your environment

import requests

2. Define your request payload
The payload must include pagination details and any filters (like employee code or department).

payload = {
  "pagination": { "pageNumber": 1, "pageSize": 10 },
  "employeeCode": "EMP123"
}

‍


3. Make the API request
Use the requests library to send a POST request with your payload and authorization token.

url = "https://hronemanagedapi.hrone.cloud/dev/api/external/employees"
headers = {
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}
response = requests.post(url, json=payload, headers=headers)

‍


4. Handle the response
Always check the status code before parsing the data.

if response.status_code == 200:
    employee_data = response.json()
    print(employee_data)
else:
    print("Error:", response.status_code, response.text)

Common Pitfalls (and How to Avoid Them)

1. Incorrect endpoint: Double-check whether you’re using /employees or /getempinfo depending on the type of data you need.
2. Expired or missing tokens: Tokens expire; set up auto-refresh or reauthentication.
3. Malformed payloads: Validate your JSON structure before sending requests.
4. Ignoring pagination: For large datasets, loop through pages to avoid missing records.
5. Exceeding rate limits: Respect HR One’s rate limits and implement exponential backoff for retries.
6. Not validating responses: Always check for non-200 responses to catch errors early.
7. Hardcoded filters: Make employee filters dynamic so integrations scale as data grows.

Frequently Asked Questions

1. What’s the default page size?
Usually 10, but you can define a custom value in the payload under pageSize. Knit paginates through HR One’s employee data automatically when syncing large datasets, so integrators don’t need to tune this value themselves.

2. How do I authenticate?
Use a Bearer token in the Authorization header and refresh it regularly to avoid 401 errors. Knit generates and refreshes this token behind the scenes for connected HR One accounts, so integrators authenticate through Knit’s own credentials instead of managing HR One tokens directly.

3. Can I filter employees by department or location?
Yes, add filters like department or location in your request payload. Knit exposes equivalent filtering through its own unified query parameters, so the filtering syntax stays the same even if you're pulling from a different HRIS.

4. What date format should I use?
The HR One API uses the RFC3339 (ISO 8601) date format. Knit normalizes dates to this same format across every connected HRIS, so date handling stays consistent regardless of which underlying system the data came from.

5. How can I handle large datasets?
Use pagination and process results in batches to manage performance efficiently. Knit handles this batching automatically for connected HR One instances, so integrators syncing a full employee database don’t need to build their own pagination loop.

6. Can I retrieve custom employee fields?
Yes, use the /getempinfo endpoint to fetch additional or custom data attributes. Knit surfaces these custom fields alongside standard employee data in the same unified response, so integrators don’t need to call a separate endpoint to get the full picture.

7. What should I do if I get a 429 or 401 error?
Knit automatically retries with backoff on 429 rate-limit responses and refreshes expired tokens on 401s for connected HR One instances, so integrators rarely see either error directly. If you’re integrating with HR One directly: a 429 means you’ve hit the rate limit, retry after the suggested interval; a 401 indicates an invalid or expired token, refresh your access token.

Simplify HR One Integration with Knit

If you want to skip the hassle of manual HR One API setup, authentication, and maintenance, you can use Knit, a unified HRIS API that connects to HR One (and dozens of other HR systems) with a single integration.

Knit handles token management, data normalization, and version maintenance behind the scenes, so your team can focus on building great employee experiences, not maintaining complex integrations.