UKG Ready API Essential Guide

What type of API does UKG Ready provide?

Based on the search results, UKG Ready has both REST and SOAP APIs. Here are the key points:

Types of APIs

1. UKG Pro offers both REST and SOAP APIs:

   • REST APIs are available for various operations
   • SOAP-based web services are also provided

2. The UKG Pro API enables integration via SOAP-based and REST-based web services.

API Details

• The REST APIs use JSON or XML.
• The SOAP APIs use Simple Object Access Protocol (SOAP) 1.2 and WS-* specifications.
• Both APIs use HTTPS/SSL for secure communication.

Authentication

• REST APIs use Basic Authentication with a web service account.
• Some REST APIs (onboarding and recruiting) require an Authorization Token.
• SOAP services require authentication information including username, password, Customer API key, and User API key.

Key Considerations

• Managing UKG Pro web services requires familiarity with software development, web service technologies, and using APIs.
• UKG recommends reviewing the Login Service API guide first to understand the login process.
• There are multiple ways to identify employees when retrieving and updating data, including employee number, SSN, SIN (for Canadian companies), and email address.

Best Practices

1. Use a UKG Pro Service Account for API access rather than a regular web user account.
2. Familiarize yourself with the general functionality and authentication requirements before diving into specific API endpoints.
3. When updating employee data, ensure you're using a unique identifier to avoid unintended updates.

In summary, UKG Ready provides both REST and SOAP APIs, offering flexibility for different integration needs. The REST APIs are more modern and use JSON/XML, while the SOAP APIs use the older SOAP protocol. Both require proper authentication and careful consideration of employee identifiers when performing operations.

Does the UKG Ready API have webhooks?

Availability of Webhooks

Yes, the official UKG Ready API does have webhooks. UKG Webhooks is a feature that allows you to subscribe to specific events and receive notifications in near real-time when those events are triggered in your UKG Pro solution.

Types of Events You Can Subscribe To

UKG Webhooks allows you to subscribe to various types of events, including:

1. Employee-related events:

   • Employee creation: employee.created
   • Employee updates: employee.updated
   • Other employee-related events (using wildcard): employee.*

2. Document-related events:

   • Document generation: document_generation.created
   • Signature tasks: signature_tasks.signed

3. Account-related events:

   • Various account events (using wildcard): account.*

4. Organization-related events:

   • Various organization events (using wildcard): organization*

5. Platform configuration changes:

   • Various events related to account, employee, and organization changes

Key Points to Consider

1. Event Catalog: UKG provides a Webhooks Events Catalog that lists all available events you can subscribe to.

2. Wildcards: UKG HR Service Delivery webhooks support wildcards, allowing you to subscribe to a group of events from a specific event category (e.g., employee.*).

3. Configuration: You can configure webhooks by specifying the events you want to subscribe to, along with a callback URL where you'll receive the notifications.

4. Security: UKG Webhooks supports Hash-Based Message Authentication Codes (HMAC) to ensure the security of the messages.

5. Testing: You can test your webhook subscriptions using the UKG Webhooks application to ensure your endpoint can receive notifications.

6. Limitations: There are some caveats and scenarios where events might not be delivered, such as during trigger removal, database restores, or mass updates.

To get started with UKG Webhooks, you'll need to log in to the UKG Webhooks application, create a subscription, and configure the events you want to receive notifications for. The UKG Webhooks User Guide provides detailed instructions on how to set up and manage your webhooks.

Rate Limits and other limitations

Based on the search results provided, here are the key points regarding the API Rate Limits of the UKG Ready API:

API Rate Limiting

UKG Pro employs an API gateway to manage quotas and rate limits for API calls [1]. The main points about their rate limiting are:

1. Rate limits are typically applied over a 1-minute time period [1].

2. If the rate of requests is too high, the server will return an HTTP Status Code 429 [1].

3. Receiving a 429 status code is not an error, but a request to reduce the rate of API calls [1].

4. Applications must respect the server's response and not attempt to circumvent the rate limits [1].

Handling Rate Limits

When encountering rate limits, UKG recommends the following:

1. They are considering implementing a "Retry-after" header in the future, which would specify how long to wait before making another call [1].

2. Until the "Retry-after" header is implemented, a default looping delay of 1 second should be used before resuming subsequent calls to an API that returned a 429 [1].

3. Alternatively, developers may choose to use an exponentially increased delay to avoid making calls at 1-second intervals until the limit window resets [1].

Key Considerations

• The specific rate limits (e.g., number of calls allowed per minute) are not explicitly stated in the provided information.
• Rate limiting is an important aspect of API usage and should be factored into application design when integrating with UKG Ready API.
• Proper handling of rate limit responses (429 status codes) is crucial for maintaining a good relationship with the API and ensuring smooth operation of integrations.

It's worth noting that while these details are provided for the UKG Pro API, they may also apply to the UKG Ready API. However, the search results do not provide specific information about UKG Ready API rate limits. For the most accurate and up-to-date information, it would be best to consult the official UKG Ready API documentation or contact their support directly.

Latest API Version

Based on the search results provided, here are the key points regarding the most recent version of the UKG Ready API:

Current API Version

The search results do not explicitly mention the most recent version number of the UKG Ready API. However, they do provide some information about recent updates and changes:

• The most recent major update mentioned is for UKG Pro 2024.R1 APIs, which were released approximately 4 months ago [5].

Key Updates and Changes

1. New Recruiting API:

   • A full suite of Recruiting API resources and operations was added, with over 100 new endpoints [5].

2. Payroll Earnings Import:

   • The Payroll Earnings Import resource was completely rewritten, updated, and enhanced [5].

3. Employee New Hire API:

   • Updated to include new fields: ResidentStateTotalAllowancesClaimedCurrencyAmount and WorkStateTotalAllowancesClaimedCurrencyAmount [5].

4. Universal Device Manager:

   • A new top-level domain was added covering Universal Device Manager API resources and operations [5].

5. AppKey Retirement:

   • The AppKey is no longer needed to call API operations. If defined, it is now ignored [5].

API Documentation

• The UKG Pro API documentation is available on the UKG Developer Hub.
• API specifications can be found in the left panel of the documentation page.
• Historical REST API operation information can be viewed in the Version History.

Authentication

• UKG Pro core REST APIs use Basic Authentication and require a web service account.
• UKG Pro onboarding and recruiting REST APIs require an Authorization Token for authentication.

Best Practices

1. Always refer to the most recent API documentation for the latest updates and changes.
2. Check the Version History for each API to stay informed about new features and modifications.
3. Be aware of the authentication requirements for different parts of the API.
4. Keep an eye on the changelog for important updates and deprecations.

While the exact version number is not provided, the information about the 2024.R1 release suggests that this is likely the most recent major update to the UKG Ready API. For the most up-to-date and precise version information, it's recommended to consult the official UKG Ready API documentation or contact UKG support directly.

How to get a UKG Ready developer account and API Keys?

Steps to Get a Developer Account

1. Ensure Administrator Access: Make sure you have administrator privileges in your company's UKG Ready instance.

2. Find Your Company Short Name:

   • Log into your UKG Ready account
   • Go to settings > Global Setup > Company Setup
   • Open Company Info
   • Find and copy the Company Short Name under Company Address

3. Obtain or Generate an API Key:

   • In Company Setup, go to Login Config
   • Scroll to API Keys
   • Copy the existing API Key or generate a new one if none exists

4. Create a Security Profile:

   • This step is necessary to set up proper permissions for API access

5. Create a Service Account:

   • This account will be used specifically for API access

6. Access the UKG Developer Hub:

   • Visit the UKG Developer Hub (https://developer.ukg.com/)
   • This platform provides API documentation, specifications, and resources

7. Review API Documentation:

   • Familiarize yourself with the API structure, authentication methods, and available endpoints

What can you do with the UKG Ready API?

Based on the search results provided, here is a list of data models that can be interacted with using the UKG Ready API, along with what is possible for each:

Employee Data

• Retrieve employee details
• Update employee information
• Search for employees using multiple filter criteria
• Access all employee data the user is authorized to see

Payroll Data

• Import payroll earnings data
• Update payroll information

Recruiting Data

• Access a full suite of recruiting resources and operations (over 100 in total)
• Manage job postings, applications, candidates, etc.

Personnel Data

• Retrieve person details
• Update personnel information

New Hire Data

• Create new employee records
• Update new hire information, including fields like:
  • ResidentStateTotalAllowancesClaimedCurrencyAmount
  • WorkStateTotalAllowancesClaimedCurrencyAmount

Company Data

• Access company-level information

Security and Authentication

• Manage web service accounts
• Handle authentication and permissions

Reporting

• Access IBM Cognos reports through Report-as-a-Service

Import Tool

• POST encoded XML transactions for data import
• GET status of import transactions

General API Capabilities

• Perform CRUD (Create, Read, Update, Delete) operations on various data models
• Search and filter data
• Handle pagination of results
• Manage API rate limits and quotas

It's important to note that the specific operations and data models available may vary depending on the particular UKG Ready implementation and the permissions granted to the API user. Additionally, the API is subject to ongoing updates and improvements, so new data models and capabilities may be added over time.