---
title: "Developer guide to get employee data from WorQ API"
description: "Learn how to retrieve employee data using the WorQ API with a step-by-step guide, Python examples, common pitfalls, and FAQs. Simplify your HRIS integrations with Knit’s unified API."
source_url: "https://www.getknit.dev/blog/developer-guide-to-get-employee-data-from-worq-api"
page_type: "blog"
---

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

# Developer guide to get employee data from WorQ API

### **Introduction**

The [WorQ API](https://www.getknit.dev/integration/workq-hrms) allows you to retrieve both new and updated employee information through secure endpoints. In this guide, we’ll walk you through how to use the WorQ API to fetch employee details whether for a single employee or your entire workforce.

This article is part of our ongoing series on the **WorQ API**, where we cover authentication, rate limits, integration best practices, and more. You can explore the complete guide [here](https://developers.getknit.dev/docs/worq-usecases).

## **Prerequisites**

Before you begin, make sure you have:

*   Valid access credentials for the WorQ API.
*   An authentication token obtained from the WorQ Authenticate API.
*   The base API URL for your environment (test or live).

## **API Endpoints**

*   **Test Environment:** `https://employee-mss.heptagon.tech/api/v1/get-employee-data`
*   **Production Environment:** `https://employee-mss.worqhub.com/api/v1/get-employee-data`

### **Step 1: Obtain an Authentication Token**

Use the WorQ Authenticate API to get a token, which is required for all subsequent requests.

```
import requests

auth_url = "https://employee-mss.heptagon.tech/api/v1/get-access-token"
auth_payload = {
    "partner_name": "your_partner_name",
}

response = requests.post(auth_url, json=auth_payload)
auth_token = response.json()['result']['token']
```

`    `

### **Step 2: Fetch Employee Data**

Once you have the token, use it to fetch employee details.

```
employee_url = "https://employee-mss.heptagon.tech/api/v1/get-employee-data"
employee_payload = {
    "token": auth_token,
    "customer_code": "your_customer_code",
    "start_date": "2023-11-01",
    "end_date": "2023-11-30",
    "page": 1
}

response = requests.post(employee_url, json=employee_payload)
employee_data = response.json()
```

## **Common Pitfalls to Avoid**

Even simple API calls can fail if small details are missed. Watch out for these:

1.  Using expired or invalid authentication tokens.
2.  Incorrect or mismatched customer codes.
3.  Using the wrong date format (`YYYY-MM-DD` expected).
4.  Missing required fields in your payload.
5.  Ignoring pagination when retrieving large datasets.
6.  Failing to handle error messages gracefully.
7.  Not accounting for rate limits on repeated requests.

## **Frequently Asked Questions**

**1\. What date format should I use in requests?**  
Use the format `YYYY-MM-DD` for all date fields.

**2\. How long is the authentication token valid?**  
Tokens are valid for 30 minutes. After expiration, generate a new one.

**3\. What does the “Invalid customer code” error mean?**  
It usually indicates a mismatch in the customer code provided, double-check your credentials.

**4\. Can I fetch data for a specific employee?**  
Yes, by including the employee ID in your request payload.

**5\. What happens if the token expires mid-request?**  
The API will return an authentication error, you’ll need to reauthenticate.

**6\. Is there a limit on how many employees I can fetch per request?**  
Yes, the API uses pagination. Use the `page` parameter to iterate through all results.

**7\. How can I handle error responses effectively?**  
Check the `status` and `messages` fields in the API response to understand the issue and handle it programmatically.

## **Integrate WorQ API Seamlessly with Knit**

Instead of building and maintaining a one-off integration for [WorQ API](https://www.getknit.dev/integration/workq-hrms), you can connect via **Knit’s unified HRIS API**. With one integration, you can access WorQ API and dozens of other HR platforms, without worrying about authentication, token expiry, or version updates.

Knit handles all the heavy lifting, from syncing employee data to maintaining ongoing compatibility, allowing your team to focus on building products, not managing integrations.


## Related pages

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