Developer guide to get employee data from Kallidus API

Introduction

This guide is part of our in-depth series on the HRIS API. In this edition, we will explore Kallidus API and its functionality, authentication mechanisms, and best practices. We’ll focus on one of the most common use cases, retrieving employee data using the Kallidus API.

Get Employee Data from Kallidus API

Prerequisites

Before you begin, ensure that:

• You have access to the Kallidus (Sapling) API key, which can be generated from your Sapling Admin Settings.
• All requests are made using HTTPS with TLS 1.2 or higher.
• You know your company’s subdomain, which is required to construct the API endpoint.

API Endpoints

• US Data Centers: https://{{subdomain}}.saplingapp.io/api/v1/beta/users
• UK Data Centers: https://{{subdomain}}.kallidus-suite.com/hr/api/v1/beta/users

Step-by-Step Guide

1. Set Up Authentication

import requests

headers = {'Authorization': 'Bearer YOUR_API_KEY'}

‍


2. Get Data for a Single Employee

subdomain = 'your_subdomain'
employee_id = 'specific_employee_id'

url = f'https://{subdomain}.saplingapp.io/api/v1/beta/users/{employee_id}'
response = requests.get(url, headers=headers)

if response.status_code == 200:
    employee_data = response.json()
    print(employee_data)
else:
    print('Error:', response.status_code)

‍


3. Get Data for All Employees

url = f'https://{subdomain}.saplingapp.io/api/v1/beta/users'
response = requests.get(url, headers=headers)

if response.status_code == 200:
    all_employees_data = response.json()
    print(all_employees_data)
else:
    print('Error:', response.status_code)

‍


Common Pitfalls to Avoid

1. Invalid API Key: Ensure your API key is active and correctly formatted in the Authorization header.
2. Outdated TLS Version: The API only supports TLS 1.2 and above.
3. Incorrect Subdomain: Replace {{subdomain}} with your actual company subdomain.
4. Ignoring Pagination: For large datasets, use pagination (?page= parameter) to avoid incomplete responses.
5. Improper Error Handling: Always check HTTP status codes and handle 4xx/5xx errors gracefully.
6. Missing Fields: Not all fields may be present, verify using the fields endpoint before assuming availability.
7. Rate Limiting: While Kallidus doesn’t strictly enforce rate limits, excessive requests may lead to throttling.

Frequently Asked Questions

1. How do I generate an API key for Kallidus?
You can create an API key in your Sapling Admin Settings under API Configuration.

2. What format does the API return data in?
Responses are returned in JSON format.

3. Is there a rate limit for requests?
Currently, there’s no fixed limit, but Kallidus may throttle requests if traffic spikes.

4. Can I access historical employee data?
The API provides current employee data. To track changes over time, set up webhooks.

5. What should I do if I receive a 401 Unauthorized error?
Check that your API key is valid, properly included in the header, and not expired.

6. How do I handle large employee datasets?
Use pagination to retrieve data page by page and ensure you don’t miss any records.

7. What happens if I exceed rate thresholds?
Your requests might be temporarily throttled. Implement retry logic with exponential backoff.

Simplify Kallidus Integration with Knit

Manually handling API integrations can be time-consuming and error-prone. With Knit, you can integrate with the Kallidus API effortlessly through a single, unified connection.

Knit HRIS API takes care of authentication and token refresh, data syncing and normalization as well as ongoing integration maintenance. This not only accelerates your development process but ensures reliable, secure, and scalable API connections.

‍