Developer guide to get employee data from WorQ API

Introduction

The WorQ API 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.

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-by-Step Guide

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",
    "partner_key": "your_partner_key"
}

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, 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.