How to Use UKG PRO WFM (Dimensions) API: Quick Start Guide

This Quick Start guide is designed to assist developers and users in making effective API calls using the UKG API. Follow the steps outlined below to request an authentication token and call the API for seamless integration.

Prerequisites:

Ensure the following prerequisites are met before making API calls:

1. An existing account for your organization.
2. An employee with Developer Admin permissions to generate an app key.
3. Basic understanding of the API structure (refer to the Foundations topic).

Call the API:

Anatomy of an API Call:

Every API call follows this basic flow:

1. Request and receive an OAuth 2.0 token from the authentication server.
2. Invoke the API by making a properly formatted call with the appropriate HTTP method, URL, headers, parameters, and JSON body.
3. Validate the authorization token.
4. If valid, the system processes the API request.
5. The system returns an API response to your application.

Exercises:

Exercise 1: Generate a Token

Using Postman:

1. Open Postman.
2. Create a new request and set the method to POST.
3. Add the authentication URL: https://HOSTNAME/api/authentication/access_token (replace HOSTNAME with your tenant’s URL).
4. In Headers, add key/value pairs:

– Content-Type: application/x-www-form-urlencoded
– appkey: APPKEY (replace with the app key generated by an employee with Developer Admin permissions).

5. In the Body, select x-www-form-urlencoded and add key/value pairs:– username: USERNAME
   – password: PASSWORD
   – client_id: CLIENT ID
   – client_secret: CLIENT PASSWORD
   – grant_type: password
   – auth_chain: OAuthLdapService

6. Send the request to generate and receive an access token.

Exercise 2: Call an API Resource

Retrieve Person by ID:

1. Open Postman.
2. Create a new request and set the method to GET.
3. Add the URL: https://HOSTNAME/api/v1/commons/persons/PERSONID (replace HOSTNAME and PERSONID with your tenant’s URL and a valid person number).
4. In Headers, add key/value pairs:– content-type: application/json
   – appkey: APP_KEY (replace with the app key generated earlier).
   – Authorization: ACCESS_TOKEN (replace with the token generated in Exercise 1). 
5. Send the request to call the API.

Exercise 3: Retrieve Aggregated Data

Using Postman:

1. Open Postman.
2. Create a new request and set the method to POST.
3. Add the URL: https://HOSTNAME/api/v1/commons/data/multi_read (replace HOSTNAME with your tenant’s URL).
4. In Headers, add key/value pairs:– content-type: application/json- appkey: APP_KEY (replace with the app key generated earlier).
   – Authorization: ACCESS_TOKEN (replace with the token generated in Exercise 1).

5. In the Body, choose raw and add a JSON body for the call.
6. Send the request to call the API.

Code Examples:

HTTP GET Request:

cURL

curl -X GET \
https://HOSTNAME/api/v1/commons/persons/PERSONID \
-H 'appkey: APP_KEY' \
-H 'authorization: ACCESS_TOKEN' \
-H 'content-type: application/json'

Java OkHttp Example:

OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://HOSTNAME/api/v1/commons/persons/PERSONID")
.get()
.addHeader("content-type", "application/json")
.addHeader("appkey", "APP_KEY")
.addHeader("authorization", "ACCESS_TOKEN")
.build();
Response response = client.newCall(request).execute();

Note: Ensure to replace HOSTNAME, PERSONID, USERNAME, PASSWORD, CLIENT ID, CLIENT PASSWORD, APPKEY, and ACCESS_TOKEN with your actual values.

This Quick Start guide is designed to streamline your integration with the UKG API. Refer to the official documentation for more details and updates.