Developer guide to get employee data from Folks HR API

Introduction

This article is part of our ongoing series exploring the HRIS API in depth. In this edition, we’ll walk through how to retrieve employee data using the Folks HR API, including prerequisites, endpoints, and example code.

You can find details on other HRIS API here.

Get Employee Data from Folks HR API

Overview

The Folks HR API provides endpoints to fetch data for individual employees or all employees within an organization. This guide outlines how to access this data step by step, from prerequisites and endpoint details to practical Python code snippets.

Prerequisites

Before you begin, ensure you have:

• Access to the Folks HR API with the required employees:read scope.
• Valid API authentication credentials (API key or OAuth token).
• A Python environment with the requests library installed.

API Endpoint

• Get a specific employee: GET /api/v2/employees/{employee}


Step-by-Step Guide

1. Retrieve Data for a Specific Employee

To fetch data for a specific employee, use the endpoint:

GET /api/v2/employees/{employee}


Replace {employee} with the employee’s ID.

Python Code Example

import requests

def get_employee(employee_id, api_key):
    url = f"https://api.folkshr.com/api/v2/employees/{employee_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        return response.json()
    else:
        return {
            "error": response.status_code,
            "message": response.text
        }

# Example usage
employee_data = get_employee(186415, "your_api_key_here")
print(employee_data)

Common Pitfalls

1. Using an incorrect API endpoint URL.
2. Missing or invalid authentication credentials.
3. Insufficient permissions (missing employees:read scope).
4. Invalid or non-existent employee ID.
5. Network or connectivity issues.
6. Not handling non-200 HTTP responses properly.
7. Ignoring API rate limits.

Frequently Asked Questions

1. What is the base URL for the Folks HR API?
https://api.folkshr.com

2. How do I authenticate API requests?
Use an API key or OAuth token in the Authorization header.

3. What format does the API return data in?
Responses are provided in JSON format.

4. What should I do if I receive a 404 error?
Confirm that the employee ID exists and is correct.

5. Can I include related models in the response?
Yes. Use the _embed[] query parameter to include related models such as country, province, or jobStatus.

Knit for Folks HR API Integration

If you’re looking for a faster, simpler, and more scalable way to connect with the Folks HR API, Knit makes it effortless.

With just one integration, Knit manages everything, from authentication and authorization to ongoing updates and maintenance, so your team can focus on building great products instead of managing integrations. t’s the easiest way to ensure your Folks HR API connection remains secure, reliable, and always up to date.

‍