Step by Step Guide to Building a UKG Ready API Integration in Python

Aug 11, 2024 • 6 minute read

Introduction

Hey there, fellow developer! Ready to dive into the world of UKG Ready API integration? You're in for a treat. This guide will walk you through building a robust integration using Python, allowing you to tap into the power of UKG Ready's workforce management capabilities. Whether you're looking to streamline HR processes or automate payroll tasks, this integration will be your new best friend.

Prerequisites

Before we jump in, let's make sure you've got your ducks in a row:

A Python environment (3.6+ recommended)
Essential libraries: requests and json (you know the drill: pip install requests)
Your UKG Ready API credentials (if you don't have these, time to sweet-talk your admin!)

Authentication

First things first, let's get you authenticated:

import requests
import json

def get_access_token(client_id, client_secret):
    url = "https://api.ultipro.com/oauth/token"
    payload = {
        "grant_type": "client_credentials",
        "client_id": client_id,
        "client_secret": client_secret
    }
    response = requests.post(url, data=payload)
    return response.json()["access_token"]

access_token = get_access_token("your_client_id", "your_client_secret")

Pro tip: Implement token caching and refresh to avoid unnecessary auth calls!

Basic API Request Structure

Now that you're authenticated, let's structure our requests:

base_url = "https://api.ultipro.com"
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

def make_request(endpoint, method="GET", data=None):
    url = f"{base_url}/{endpoint}"
    response = requests.request(method, url, headers=headers, json=data)
    return response.json()

Implementing Core API Calls

Time to put our function to work:

# GET request
employees = make_request("personnel/v1/employees")

# POST request
new_employee = {
    "firstName": "John",
    "lastName": "Doe",
    # ... other employee details
}
create_response = make_request("personnel/v1/employees", method="POST", data=new_employee)

# PUT request
updated_data = {"phoneNumber": "555-1234"}
update_response = make_request("personnel/v1/employees/123", method="PUT", data=updated_data)

# DELETE request
delete_response = make_request("personnel/v1/employees/123", method="DELETE")

Handling Responses

Always expect the unexpected:

def handle_response(response):
    if response.status_code == 200:
        return response.json()
    elif response.status_code == 401:
        # Refresh your token here
        pass
    else:
        raise Exception(f"API request failed: {response.status_code} - {response.text}")

Don't let large datasets slow you down:

def get_all_employees():
    employees = []
    page = 1
    while True:
        response = make_request(f"personnel/v1/employees?page={page}")
        if not response["data"]:
            break
        employees.extend(response["data"])
        page += 1
    return employees

Rate Limiting and Best Practices

Play nice with the API:

import time

def rate_limited_request(endpoint, method="GET", data=None):
    response = make_request(endpoint, method, data)
    if response.status_code == 429:
        retry_after = int(response.headers.get("Retry-After", 60))
        time.sleep(retry_after)
        return rate_limited_request(endpoint, method, data)
    return response

Example Use Cases

Let's put it all together:

# Fetch employee data
employees = get_all_employees()

# Update time off request
time_off_request = {
    "employeeId": "123",
    "startDate": "2023-07-01",
    "endDate": "2023-07-05",
    "type": "Vacation"
}
update_time_off = rate_limited_request("time-management/v1/time-off-requests", method="POST", data=time_off_request)

# Get payroll information
payroll_data = rate_limited_request("payroll/v1/payroll-details/123")

Testing and Debugging

Always test your code:

import unittest

class TestUKGIntegration(unittest.TestCase):
    def test_get_employees(self):
        employees = get_all_employees()
        self.assertIsInstance(employees, list)
        self.assertTrue(len(employees) > 0)

if __name__ == "__main__":
    unittest.main()

Conclusion

And there you have it! You've just built a solid foundation for your UKG Ready API integration. Remember, this is just the beginning. As you grow more comfortable with the API, you'll find countless ways to extend and customize your integration to fit your specific needs.

Additional Resources

Want to dive deeper? Check out these resources:

Now go forth and integrate! Your HR team will thank you, and you'll be the office hero. Happy coding!