UKG Pro Workforce Management API Essential Guide

What type of API does UKG Pro Workforce Management provide?

REST API

UKG Pro Workforce Management offers a REST API. The key points about the REST API are:

• It uses JSON or XML for data formats.
• Authentication is done using OAuth tokens.
• It provides access to various workforce management resources and operations.

SOAP API

UKG Pro also offers SOAP-based web services:

• The SOAP API uses Simple Object Access Protocol (SOAP) 1.2.
• It supports WS-* specifications.
• Authentication requires a username/password, Customer API key, and User API key.

Key Considerations

• Both REST and SOAP APIs are available, giving developers flexibility in integration options.
• The REST API appears to be the more modern offering, with detailed documentation in the Developer Hub.
• Authentication methods differ between REST (OAuth) and SOAP (username/password + API keys).

In summary, UKG Pro Workforce Management offers both REST and SOAP API options, with REST being the more modern approach. The REST API in particular is well-documented and follows standard REST principles for workforce management data access and operations.

Does the UKG Pro Workforce Management API have webhooks?

Availability of Webhooks

Yes, the official UKG Pro Workforce Management API does have webhooks. UKG Webhooks is a feature that allows you to subscribe to specific events and receive notifications in near real-time.

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)

2. Document-related events:

   • Document generation (document_generation.created)
   • Signature tasks (signature_tasks.signed)

3. Account and organization events:

   • Account changes (account.*)
   • Organization changes (organization*)

4. Platform configuration changes

Key Points to Consider

1. UKG Webhooks allows you to implement Hash-Based Message Authentication Codes (HMAC) to ensure the security of the messages.

2. Subscriptions can be tested, deactivated, and reactivated at any time.

3. You need to provide a public (exposed) URL to receive webhook callbacks.

4. UKG Webhooks supports wildcards, allowing you to subscribe to groups of events from specific categories (e.g., employee.*).

5. There are some caveats and scenarios where events might not be delivered, such as trigger removal or disablement, SQL access and database restores, and mass updates to the company database.

Setting Up Webhooks

To set up a webhook:

1. Log in to the UKG Webhooks application.
2. Add a subscription by providing an endpoint URL and selecting the events you want to subscribe to.
3. Optionally, you can add an HMAC secret for message verification and customize your webhook requests using free-form headers.

Best Practices

1. Consider using a secondary polling synchronization or nightly report for business-critical integrations to safeguard against missed events.

2. Be aware of the retention time for events in UKG Webhooks, which is 14 days.

3. Test your webhook's endpoint to ensure notifications can be received.

4. Implement proper security measures, such as HMAC verification, to ensure the authenticity of incoming webhook messages.

In conclusion, UKG Pro Workforce Management API does offer webhooks, allowing you to subscribe to various events related to employees, documents, account changes, and more. This feature enables real-time notifications and integration with your systems, providing a powerful tool for automating and streamlining your workflows.

Rate Limits and other limitations

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

API Rate Limiting

UKG Pro employs an API rate limiting strategy with the following characteristics:

• An API gateway is used to manage quotas and rate limits for API calls
• Rate limits are typically applied over a 1 minute time period
• If the rate of requests is too high, the server will return an HTTP 429 status code
• Receiving a 429 status is not an error, but a request to reduce the rate of API calls
• Applications must respect the 429 response and not try to circumvent it

Handling Rate Limits

To handle rate limiting, the following recommendations are provided:

• UKG is considering implementing a "Retry-after" header with the 429 response in the future
• Until then, use a default looping delay of 1 second before retrying after receiving a 429
• Optionally, use an exponentially increasing delay between retries
• When implemented, check for and respect the "Retry-after" header value

Key Points

• Rate limits are applied over short time periods, typically 1 minute
• Exceeding the limit results in a 429 status code response
• Applications should implement proper handling of 429 responses
• A default 1 second delay is recommended between retries
• UKG may add a "Retry-after" header in the future to specify wait times

The documentation does not provide specific numeric rate limit values. The actual limits likely vary by endpoint and may be subject to change. Proper handling of 429 responses is critical for working within the rate limits.

Latest API Version

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

Most Recent Version

The most recent version of the UKG Pro Workforce Management API appears to be the 2024.R1 release. This release was made available approximately 4 months ago.

Key Updates in the Latest Version

1. New Recruiting API resources:

   • Over 100 new Recruiting API resources and operations were added.

2. Enhancements to existing operations:

   • The Payroll Earnings Import resource was completely rewritten, updated, and enhanced.
   • The Employee New Hire API was updated to include new fields for Iowa locations.

3. New Universal Device Manager domain:

   • A new top-level domain for Universal Device Manager API resources and operations was introduced, including UDM Devices and UDM Device Groups.

4. AppKey retirement:

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

5. Other enhancements:

   • The "Stage Payroll Asynchronously" operation was enhanced with a new customFields array.
   • The "Create Rule Set" and "Update Rule Set by ID" operations now support Employee Rule Sets.

Additional Information

• The UKG Pro Workforce Management API documentation is organized into reference and conceptual documentation, accessible through the API specifications and Documentation links in the header.
• The complete API specification is available in the lefthand navigation menu of the Developer Hub.
• Authentication for the UKG Pro core REST APIs uses Basic Authentication and requires a web service account.
• The UKG Pro onboarding and recruiting REST APIs require an Authorization Token for authentication.

It's important to note that while these updates represent the most recent changes, UKG regularly releases updates and enhancements to their APIs. For the most up-to-date information, it's recommended to check the official UKG Developer Hub and release notes.

How to get a UKG Pro Workforce Management developer account and API Keys?

Getting a Developer Account

1. UKG Pro offers API access through their Developer Hub at developer.ukg.com.

2. The Developer Hub is free to access and open to all developers.

3. To become a registered user, you need to sign up on the Developer Hub website.

API Access and Authentication

1. UKG Pro offers two main APIs:

   • HR, Payroll, and Talent API
   • Workforce Management API

2. Authentication requires:

   • A UKG Pro Service Account or Web User account with Web Services permissions
   • A valid Customer API key
   • A User API key

3. For core REST APIs, you need a web service account with Basic Authentication.

4. Some APIs like onboarding and recruiting require an Authorization Token.

What can you do with the UKG Pro Workforce Management API?

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

Universal Device Manager (UDM)

• UDM Device Groups:

  • Retrieve all device groups
  • Create new device groups
  • Update device groups by ID
  • Delete device groups by ID

• UDM Devices:

  • Retrieve all devices

Forecasting Setup

• Labor Constraint Settings:

  • Retrieve all labor constraint settings or by name
  • Create single or multiple labor constraint settings
  • Update multiple labor constraint settings
  • Delete labor constraint settings
  • Retrieve labor constraint settings by ID
  • Update labor constraint settings by ID

• Labor Distribution Group Profiles:

  • Retrieve all labor distribution group profiles or by name
  • Create single or multiple labor distribution group profiles
  • Retrieve labor distribution group profile by location
  • Delete labor distribution group profiles
  • Update labor distribution group profiles
  • Retrieve labor distribution group profile by ID
  • Update labor distribution group profile by ID

Employee Self-Service

• Time Off Requests:

  • Create time off requests as manager
  • Update time off requests as manager
  • Retrieve time off requests as manager
  • Retrieve time off request by ID as manager
  • Update time off request by ID as manager

• Accrual Balance:

  • Retrieve accrual balance as manager

• Request Period and Subtypes:

  • Retrieve request period as manager
  • Retrieve request subtype as manager

• Guided Recommendations:

  • Retrieve guided recommendations for time off requests

UKG Pro Codes

The API allows interaction with various code configurations, including:

• Allergy
• AwardType
• Career Provider
• ChildSupportType
• CobraStatus
• CompanyProperty
• CourseCategory
• CourseDeliveryMet
• CourseSubCategory
• Disability
• EmployeeType
• JobFamily
• LicenseType
• LoanType
• MaritalStatus
• MilitaryBranches
• MilitaryEra
• NamePrefix
• OtherPhoneTypes
• Project
• School
• SkillProficiencyLevel
• Skills
• TermType
• WaiveReason

For each of these code configurations, you can typically:

• Retrieve all configurations
• Create new configurations
• Update single configurations

Global Employee Localization Details

• EmpGlobalLocalizationElement:
  • Get all global employee localization fields added to UKG Pro

Data Hub

While not directly part of the API, the UKG Pro Workforce Management Data Hub provides additional data access capabilities:

• Perform strategic analysis on large volumes of data
• Integrate with third-party data (Enterprise tier)
• Feed data into an external Enterprise Data Warehouse (EDW)
• Analyze data using standard SQL
• Use preferred Business Intelligence (BI) tools for shaping and visualizing WFM data

It's important to note that the actual implementation and availability of these data models and operations may vary depending on your specific UKG Pro Workforce Management setup and subscription level. Always refer to the most up-to-date API documentation for the most accurate information.