News

2024.R1 Pro API updates

• Check out the What's New section for important news going forward!
• New: Added a full suite of Recruiting API resources and operations, over 100 in total. Be sure to check out the new Recruiting content in the Pro API specification.
• Enhancement: Completely rewrote, updated, and enhanced the Payroll Earnings Import resource.
• Enhancement: The Employee New Hire API has been updated to include these fields: ResidentStateTotalAllowancesClaimedCurrencyAmount and WorkStateTotalAllowancesClaimedCurrencyAmount. These fields each have a 10-digit maximum and can only include whole dollar amounts (decimals are not supported). Note: These fields are only to be used by Iowa locations. The Developer Hub entry for the Employee New Hire Service as well as the Employee New Hire Service API Guide, available in the UKG Community Library, have been updated to include these new field-level details.

Expanded default/max pagination parameters

The following API updates were made in January 2022:

A number of published APIs include default pagination parameters for your reference. The default/max for those pages was 100 per page. The pagination parameters have been updated to 10,000 per page.

The following pages include default pagination and have been updated accordingly:

• Company Details
• Compensation Details
• Employee Contact Details
• Employee Contract Details
• Employee Direct Deposit Details
• Employee Education
• Employee Job History
• Employee National Documents
• Employment Details
• Global Employee Direct Deposit Details
• Global Employee Localization Details
• Global Employee Payments and Deductions
• International Employees
• Person Details.

New API Import Tool

A new import tool API allows users to POST encoded XML transactions to the Import Tool. Transaction results can be viewed in UKG Pro by navigating to Administration > Integration Studio > Import Tool > Results. Reference the Import Tool XML and Configuration Settings Guide for transaction details.

A GET API allows users to see the status of an Import Tool transaction. StagingID is from the response of a previous POST.

The headers goes as follows:

• Headers - US-Customer-Api-Key
• Authorization (base64 encoded {username}:{password})

UKG Pro Web Service Account Permission Changes

The Personnel Integration Service Account permissions (in UKG Pro: Menu > System Configuration > Security > Service Account Administration) have been separated into these separate Service Account permissions: (1) Global Employee Direct Deposit, (2) Employee Job History Details, (3) Employee Person Details, and (4) Employee Compensation Details. If View Only was granted for Personnel Integration, then View Only is now granted for these new Service Account permissions as well.

The Payroll Integration Service Account permissions (in UKG Pro: Menu > System Configuration > Security > Service Account Administration) have been separated into these separate Service Account permissions: Personnel Integration, Employee Direct Deposit, Global Employee Direct Deposit, Employee Job History Details, Employee Person Details, Employee Compensation Details

More Details:

In an effort to reduce vulnerabilities we have split out APIs containing sensitive information such as employee data into their own permission items. Previously these APIs were grouped under Personnel Integration and some customers were uncomfortable giving their developers access to sensitive data.

How this affects customers & partners:

More granular API permissions can now be assigned. If customers want to exclude APIs containing sensitive employee data they can now do so by only granting access to the Personnel Integration set.
Are existing accounts/permissions going to be affected?

Existing account permissions are not going to be impacted/changed.
A script was run to opt-in all existing users of the above APIs to ensure their permissions were enabled/maintained.

UKG Pro Generate Web Service Password Changes

The UKG Pro Add/Change Service Account page (in UKG Pro: Menu > System Configuration > Security > Service Account Administration > Add) has been modified so that Web Service Account passwords must be randomly generated by checking the Generate New Password box. The Generate New Password box is automatically selected when adding a new Service Account. After entering the remaining required information and selecting Save, a New Password window displays with the randomly generated password. You can copy the password and save it in a secure location. You will not be able to see this password again after closing the New Password page. If the password is lost or forgotten, a new one will need to be generated.

In an effort to reduce vulnerabilities we changed the way we generate passwords for webservice accounts. Today, webservice account passwords are manually created by customers and follow a generic password policy.

How this works for customers:

• The password for web service accounts will be randomly generated.
• The password field has been removed from the page.
• The password will be random, alphanumeric, and contain a minimum of at least 2 special characters allowed. No spaces.
• The password length will be determined by the password policy enforced for site administrators. (same site policy as site admins).
• When the password is generated it will follow an access policy where you create it, see it for the first time, and allow you to copy/paste only 1 time.
• Are existing accounts/passwords going to automatically reset at some point?
• Existing passwords are not going to be impacted/changed.
• Applications should not have to be rebuilt or modified because of this change. There should be a mechanism within applications consuming UKG Pro Web Service accounts to update the password.

API Gateway Identifier for Partners in UKG Pro

Confidential - For UKG Customer and Partner Use Only

UKG is now implementing identification & tracking of API calls by partners. The purpose is to be able to distinguish calls from different partners for analytics & support purposes. This information will be logged by our API gateway and may be used to correlate to log records in support scenarios.

Many UKG APIs currently include a client identifier in their headers but this does not identify which partner is calling the API. In order to positively identify each partner we are implementing a new header in API calls named "X-Partner-Id". Partners will add a header to all API calls to UKG named X-Partner-Id along with a string identifying their name. UKG Alliances technical support will provide each partner with an appropriate value for this header. Any partner identifiers other than those defined by UKG will be ignored by our API gateway.

Below is an example of X-Partner-Id in Postman for REST APIs:

> curl -X GET \
  'https://{hostname}/personnel/v1/person-details' \
  -H 'authorization: Basic UFRVU0c2M1ASDFSTpwYXNzd29yZDEh' \
  -H 'cache-control: no-cache' \
  -H 'us-customer-api-key: ZX24U' \
  -H 'X-Partner-Id: PartnerName'

Here is an example of X-Partner-Id for UKG Pro SOAP Services:

\
<s:Header>
<X-Partner-Id>PartnerName</X-Partner-Id>
<s:/Header>

UKG Pro Company Access Code

• Question: What is a company Access code?
  Answer: The company access code is the code an HR/System Admin creates when they are setting up the UKG Pro mobile app. The code is unique to the company and once set it cannot be changed. This code is used on the first screen of the app to tie together the tenant and the app.

• Question: Is the Access code the same for all component companies under the Master Company in UKG Pro?
  Answer: Yes - only one access code is provided

• Question: How do I find my company Access code?
  Answer: If your HR administrator has has turned on the advertising widget for UKG Pro mobile, you should see what's shown on the left side of the image below for Company Access Code when you login to the desktop version of UKG Pro. If you don't see this, please contact your HR administrator to get the code directly from them.

For urgent questions regarding UKG Pro, or if you are unable to access UKG Pro, please submit a case via the Customer Success Portal or reach out to your support representative.

API Rate Limiting

UKG Pro API management strategy employs an API gateway to manage quotas and rate limits for how many API calls an API client can make over a particular time period, normally 1 minute. If the rate of requests has been too high the server is not willing to accept this and will return to the API client an HTTP Status Code 429.

Receiving a status 429 from one of UKG Pro APIs is not an error, it is the server kindly asking you to please reduce the rate at which your client is making requests. The IETF explanation for HTTP Status Code 429 can be found here.

You should not seek to dodge this nor to circumvent server security settings by trying to spoof your IP. Applications must respect the server's answer by not sending too many requests.

We are considering implementing a "Retry-after" header in the future along with the 429 response. This header would specify the number of seconds an API client should wait before making another call. The proper way to deal with this would to read this header and to sleep your request process for that many seconds. If you desire you can put an optional check in your code now to check for this header and use the value if it's present.

Until a Retry-after header is implemented and in case you call an API that does not yet use it, a default looping delay value of 1 second should be used before resuming the subsequent calls to the API that returned a 429.

If you are concerned with making calls at 1 second intervals until the limit window resets resulting in a response other than 429, you may choose to use an exponentially increased delay.

Introducing Model Domains

Ultimate is restructuring our API solution/project structure to be domain based.

The primary goal is to standardize API URL 'domain paths' around UKG Pro key domains (based on DDD- Domain Driven Design and bounded context considerations), and then organize our codebase along these boundaries. Structuring the codebase & URLs in this way will allow us to gain all the key benefits of DDD. This will also allow us to perform minor releases or hot-fixes with good code isolation and less impact to you our valued customers.

UKG Pro Standard Model Domains:

• /configuration
• /personnel
• /payroll
• /tax
• /talent
• /time

Note: These new domains will be affecting new endpoints only and not have any impact on existing like SOAP services, third party pay, etc...

API Deprecation Strategy

APIs are best thought of as a contract provided by UKG to its customers and internal developers. Customers or third-party developers and partners can work with our APIs to build integrations on their own systems. Sometimes it is necessary to phase out an API endpoint (or version). For example, this may be necessary if a field is no longer supported in the result or a business functionality behind an endpoint has to be shut down. There could be other reasons as well.

Sunset Period:

Sunset period provides our API consumers with an adequate time to upgrade to a newer version or retire the functionality before the API stops working. In order to provide a smooth transition for our customers and internal developers, UKG defines sunset period as a combination of 6 months of fully functional and supported API and another 6 months of functional API with no additional support.

Versioning:

Proper API versioning helps to deprecate API reliably and effectively. Multiple versions of the same functional API can live simultaneously. Release of the next API version may permit deprecation of a previous version. E.g. release of API v2 may permit deprecation of API v1 by beginning the sunset period for API v1. New API version does not necessarily mean deprecating the previous version - sometimes it is desired to keep both versions for compatibility or contractual obligations.

Communication to our API Consumers:

Communication to the API consumers, customers and internal developers, is an important part of API deprecation phase. For this reason, we send an initial message announcing the intended deprecation, with the proposed deprecation "sunset", next version release schedule (if applicable), and additional information such as support, contact information, etc.

Reflect Deprecation in the API Definition:

API deprecation is part of the OpenAPI definition. If a method on a path or a whole API endpoint should be deprecated, UKG will set deprecated=true on each method/path element that will be deprecated. If deprecation needs to happen on a more granular level (i.e. query parameter, payload etc.), UKG will set deprecated=true on the affected method/path element and add further explanation to the description section. If deprecated is set to true, UKG will describe what our clients should use instead and when the API will be shut down in the description section of the API definition. UKG's API documentation will reflect the deprecated API:

Adding a Warning Header to Responses:

During deprecation phase, UKG will add a Warning header (see RFC-7234) to the API response: Warning: 299 "https://(hostname)/personnel/v1/employees" "The API is deprecated and will be removed on [Sat, 25 Aug 2012 00:00:00 GMT]", where date is in HTTP-date format defined by RFC-2616. The square brackets are intended to help our customers with date parsing automation. Consumers will be able to read Warnings, automatically detect, and include this information into logs for human attention.

Monitoring for Warning Header:

It is important for all of our API consumers to monitor Warning headers in HTTP responses to see if an API will be deprecated in the future. Warnings headers written into logs by the HTTP Clients help developers to detect API forthcoming deprecation and migrate to newer version in a timely fashion.

Helping Our Customers to Avoid Problems:

As an API provider, we help our consumers avoid possible errors within their products due to API deprecation. After an API is deprecated, these are few simple steps that UKG takes that will help our API consumers.

• If the endpoint functionality is completely removed, we will respond with 409 "Gone" status instead of 404 "Not Found". This allows our consumers to have different error handling which avoids confusion with incorrectly implemented or missing API.
• If the endpoint functionality was replaced with a newer implementation, we will respond with 301 "Moved Permanently" status providing a newer endpoint URL. This allows our consumers to call an alternative API as a fallback fault tolerant strategy.
• UKG will keep documentation for deprecated endpoints for a prolonged period of time, replacing its content with reference to the newer implementation, or (if it was removed completely) provide a note indicating this.

Swagger API Documentation

Swagger is one of the leading standards in API documentation, it's been around ever since 2011 and is the product of SmartBear, the company that made a similar tool in SOAPUI. The community is pretty active and it currently support a wide range of languages: Clojure, Go, JS, Java, .Net, Node, PHP, Python, Ruby, Scala, for each of these languages many frameworks are supported. Swagger ultimately provides a JSON file which can be interpreted by the Swagger UI or any other Custom Tool that supports it. If the framework in use is not supported by Swagger it's easy to build this JSON file as part of a custom strategy in the project, and any of the custom UI tools should work, provided the JSON file complies with the Swagger standard.

Integration:

Because Swagger is basically a JSON file following the standard, documenting Swagger can be achieved via different ways such us, Static Files, Manually crafted JSON, Code inspection, Code comments, static annotations or Runtime generation.

There are many tools that follow the annotation path, usually in a manner similar to javadoc or .NET documentation, then use a parsing and codegen module tailored to the service's programming language or framework, along with Swagger UI, to generate the interactive interface to the REST APIs. Swagger annotations are kept inline with the source, colloquially speaking is good to just have it 'there', while making changes to resources, one can easily update the documentation without forgetting. It also means that in order to update Documentation, one has to modify source files, this may delay the documentation update depending on the team deployment/testing strategy.

If the documentation gets generated at runtime, no external tool needs to run on the CI process. This is best practice to keep documentation in sync with the API.

A good example of this for .Net: ASP Net WEB API Documentation Using Swagger
Swashbuckle on Github: Github Swashbuckle
or if you want to use Nuget packages:Nuget Swashbuckle
Tags

Postman - Simplify Your Integration Experience

Integrating with a partner's API can be a complicated process. At UKG, we strive to make your integration with our services as seamless as possible. For this reason, we recommend that your team use Postman to experiment and test out our services prior to integrating within your own applications.

Note: It should be understood that we are only using Postman for UKG Pro's REST API's and it is not used with SOAP services.

Download Postman

Get Started

POSTMAN COLLECTIONS

Collections will take your team's productivity to the next level. A collection lets you group individual requests together. These requests can be further organized into folders to accurately mirror your API. Requests can also store sample responses when saved in a collection. You can add metadata like name and description too so that all the information that a developer needs to use your API is available easily. Collections are listed in the sidebar alphabetically. You can search through collection requests using the search form for quick access. Our team is working to create Postman collections for registered users of UPC (UltiPro Connect). These collections can easily be shared between developers or teams and imported for quick use.

Collections are merely JSON documents and can be imported by:

• File upload
• Paste raw text
• Download from link

How To Use And Share Postman Collections

POSTMAN ENVIRONMENTS

While working with APIs, you will often need to have different setups. For example, your local machine, the development server, or the production API. Environments give you the ability to customize requests using variables. This way you can easily switch between different setups without changing your requests. You won't have to worry about remembering all those values once they are in Postman. Environments can be downloaded and saved as JSON files and uploaded later. Each environment is a set of key-value pairs. These can be edited using the key-value editor. The key is the variable or property name. This makes it really simple to have results from one API request populate the properties or access tokens for subsequent requests. All of this can be saved for ease of reuse.

Much like the collections, the environments can easily be shared between developers or teams and imported for quick use.

How To Use Postman Environments

Terminology

Here are some common terms you can expect to see throughout this website:

• API: Application program interface (API) is a set of routines, protocols, and tools for building software applications. An API specifies how software components should interact.
• Authentication: Also known as AuthN. Answers the questions "Who am I?" and "Am I who I say I am?" AuthN involves validating credentials or tokens and extracting claims about the identity.
• Authorization: Also known as AuthZ. Answers the question "Am I allowed to do this?" AuthZ involves correlating an identity with some access management system to see if the identity has access to the resource(s) requested.
• Controlled Release: Clearly defined & closely monitored roll out plan for a select number of new customers of different sizes & market segments.
• Identity: UKG Pro's centralized source for authentication & authorization information
• JWT: JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties.
• POC: Proof of Concept
• Postman: GUI platform to build, test, document, and share API requests.
• PSR: Performance, Scalability, & Reliability test cases generally referred together as PSR testing.
• REST: Representational state transfer (REST) or RESTful web services allow requesting systems to access and manipulate textual representations of web resources using a uniform and predefined set of stateless operations.
• Sandbox: Development & testing environment that isolates untested code changes and outright experimentation from the production environment.
• Swagger: Swagger.io is an open source framework backed by a large ecosystem of tools to design, build, document, and consume RESTful APIs.

Web Service Accounts

UKG Pro APIs using Basic Authentication are only accessible with a web service account. UKG Pro users with system administrator rights can create web service accounts in UKG Pro by navigating to System Configuration > Security > Service Account Administration. Like user accounts, web service accounts requires a unique username, password, and granular permissions. Permissions can be granted to one or more resource or method.

Best Practice:

• For security, only grant access to the API resources and actions a web service account will use.
• Each web service account is assigned a unique user API key. This user API key along with the web service account username and password is necessary for authentication to an endpoint.

Service Endpoints:

UKG Pro system administrators can locate the service endpoints in UKG Pro by navigating to System Configuration > Security > Web Services. Each endpoint is made up of two parts: base service URL and resource path. The base service URL will be similar to "https://(hostname)/services/", but will vary by customer datacenter and production/test environments.