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 setup to execution. from HR One API and help you avoid common integration mistakes.

Whether you’re fetching a single employee’s record or syncing a complete employee database, this guide will show you how to build a robust and efficient connection to the HR One API with practical examples in Python.

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.

2. How do I authenticate?
Use a Bearer token in the Authorization header and refresh it regularly to avoid 401 errors.

3. Can I filter employees by department or location?
Yes. Add filters like department or location in your request payload.

4. What date format should I use?
The HR One API uses the RFC3339 (ISO 8601) date format.

5. How can I handle large datasets?
Use pagination and process results in batches to manage performance efficiently.

6. Can I retrieve custom employee fields?
Yes, use the /getempinfo endpoint to fetch additional or custom data attributes.

7. What should I do if I get a 429 or 401 error?
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.