---
title: "Developer guide to get employee data from Folks HR API"
description: "Learn how to retrieve employee data using the Folks HR API with a detailed step-by-step guide, Python code examples, and key FAQs."
source_url: "https://www.getknit.dev/blog/developer-guide-to-get-employee-data-from-folks-hr-api"
page_type: "blog"
---

_This is an educational blog post from Knit's blog: “Developer guide to get employee data from Folks HR API”._

# 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](https://www.getknit.dev/blog/everything-you-need-to-know-about-hris-api-integration).

### 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}`

#### 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](https://developers.getknit.dev/reference/hris-apps), **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.


## Related pages

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