API Specifications
What's NewUKG.comMarketplaceUKG Pro status

UKG HR Service Delivery REST API Overview

This section describes UKG HR Service Delivery REST API v3 and classic (v2).

UKG HR Service Delivery REST API v3 Overview

This API Document provides endpoints for managing employee documents and document categories. It supports operations such as searching, listing, creating, retrieving, and uploading documents.

Base URL

  • https://{hrsd-dochub-service}/dochub/v1

Authentication

  • All endpoints require bearer token authentication.
  • All endpoints need employee scope.

Request Header

Header NameDescriptionExample
AuthorizationBearer token requiredHeader NameDescriptionExampleAuthorizationBearer token requiredBearer eyJhbGciOiJIUzI1Ni...

Authorization

HRSD supports Authorization and access control by providing rich roles and permission features:

Roles

Navigate to the Document Manager Administration panel > Users > Roles and permissions to view a list of all available roles including the amount of managers profiles that have been assigned to each particular role.

New Role

Click the New role button to open the new role form, then specify the Role Name and Code.

These access rules are applicable on classic HRSD APIs. v3 HRSD APIs leverage the same access rules to access control public APIs. Rest APIs mentioned below leverage Employee Permissions. Permissions which are tagged as New will be added as part of development.

Permissions

Permissions can be defined for each particular role and are divided into:

  • Employees
  • Employee vault
  • Documents
  • Signature
  • Statistics and Platform administration permissions

Core permissions are as follows:

  • Platform Administration:
    • Manage roles - manage_roles
    • Manage users - manage_users
    • Manage data sets - manage_datasets
    • Manage custom fields - manage_custom_fields
    • Manage organizations - manage_organizations
    • Manage employee imports - manage_employee_imports
    • Manage organization imports - manage_organization_imports
    • Manage retention policies for Digital Process Manager and Request Manager - manage_retention_policies
    • Export employee list by .csv - export_employee_csv
    • View the event log - view_audit_trail
  • Employees:
    • View private custom fields - view_private_custom_fields
    • Manage employees - manage_employees
    • Manage employee SAML tokens - manage_employees_saml_token
    • View employees - view_employees
    • Manage employees deletion - delete_employees
    • View employees without registration references - view_employees_without_registration_reference
    • View former employees - view_former_employees
  • Statistics:
    • View advanced analytics - view_advanced_analytics
    • Manage advanced analytics - manage_advanced_analytics

Assign a Role to a Manager

  1. Navigate to Administations > Users and open the manager account which you would like to update.
  2. Under User Profiles, click Add profile.
  3. Using the Role dropdown, select the desired role.
  4. Click Add Profile to assign the role to the manager's profile.

Once complete, managers will be able to operate within this particular role while logged into Document Manager.

UKG HR Service Delivery REST API v2 Overview

This section describes UKG HR Service Delivery REST API version 2.

Endpoints

UKG HR Service Delivery classic (v2) REST API Endpoints.

Base URLs

All URLs described in this document are relative URLs. To get the absolute URL of a method, you have to append the base URL of the environment (staging / prod) of your platform:

Production Base URLs:

  • EU platform: https://apis.eu.people-doc.com/api/v2
  • US platform: https://apis.us.people-doc.com/api/v2

Staging Base URLs:

  • EU platform: https://apis.staging.eu.people-doc.com/api/v2
  • US platform: https://apis.staging.us.people-doc.com/api/v2

UKG / Ultipro Base URLs:

  • ATL platform: https://apis.hrsd.ultipro.com/api/v2
  • TOR platform: https://apis.hrsd.ultipro.ca/api/v2

Authentication

Note
Your application credentials (application_id, application_secret, and client_id) are provided upon request by a Project Manager. Please contact our Support team for assistance.

Authentication on UKG HR Service Delivery endpoints is based on an application OAuth access_token. An access_token identifies your application and can be retrieved by calling the /tokens endpoint using your application credentials in Basic Auth.

Hint
For a more in-depth guide to authenticate with our APIs, read our guide to [connect to UKG HR Service Delivery APIs using OAuth].

How to obtain an application access_token?

cURL example:

# Basic Authentication to get a valid Client OAuth Token
curl -X POST -u "$APPLICATION_ID:$APPLICATION_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/json" \
  -d "grant_type=client_credentials&scope=client&client_id=$CLIENT_ID" \
  "$BASE_URL/api/v2/client/tokens"
# => returns JSON object containing the access_token
{
  "access_token":"eyJhbGciOiJSUzI1NiIsInR5cCI....",
  "token_type":"bearer",
  "expires_in":3600
}

The access_token returned is valid until its expiration date, so you should check the validity of your token before making any call to our API. If the token is expired, request a new OAuth application access token by calling the previous endpoint again.

Errors during access_token creation

If an error occurs during the generation of the access_token, you receive a JSON response with the following keys:

  • error: machine-parseable error code refining the HTTP status code
  • error_description: human readable description of the error

Example cases:

Wrong application_id or application_secret (HTTP 401 Unauthorized)

{
  "error": "invalid_client",
  "error_description": "Client authentication failed."
}

Wrong client_id (HTTP 400 Bad Request)

{
  "error": "invalid_request",
  "error_description": "The request is invalid"
}

Wrong scope (HTTP 400 Bad Request)

{
  "error": "invalid_scope",
  "error_description": "The requested scope is invalid."
}

Wrong grant_type (should be client_credentials) (HTTP 400 Bad Request)

{
  "error": "invalid_grant",
  "error_description": "The provided authorization grant is invalid."
}

Access Token usage

The OAuth access_token must then be provided in each API call in the Authorization HTTP header.

curl -X GET \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  "$BASE_URL/api/v2/client/RESOURCES"

Warning
The access token provided is an application access token. It is meant to be used by a trusted application for server-to-server calls and must NEVER be displayed or leaked to a user device like a browser. If you need a user application running on a device to communicate with our APIs, your application (where your users are authenticated) must act as a proxy.

Error codes & response

HTTP Status codes

Our API returns appropriate HTTP status codes for each request:

  • 200 — request succeeded
  • 201 — resource has been created
  • 400 Bad Request — malformed or invalid request
  • 401 Unauthorized — missing or incorrect credentials
  • 403 Forbidden — understood request but access not allowed
  • 404 Not Found — invalid URI or resource doesn’t exist
  • 422 Unprocessable Entity — input validation errors; response body includes detailed field errors

Error messages

If the API returns error messages, they use JSON with the following keys:

  • code — machine-parseable error code refining the HTTP status
  • message — human readable description
  • errors (optional) — list of validation field errors
    • Each validation error object includes:
      • field: name of the field in input JSON
      • code: machine-parseable error code
      • message: human readable description

Example 401 Unauthorized:

{
  "code": "invalid_token",
  "message": "The authentication token is expired"
}

Example 422 Unprocessable Entity:

{
  "code": "validation_error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "title",
      "code": "too_long",
      "message": "Title is too long"
    }
  ]
}

Nested or list error example:

{
  "code": "validation_error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "category.title",
      "code": "too_long",
      "message": "Title is too long"
    }
  ]
}

Or:

{
  "code": "validation_error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "category.0.title",
      "code": "too_long",
      "message": "Title is too long"
    },
    {
      "field": "category.1.title",
      "code": "too_long",
      "message": "Title is too long"
    }
  ]
}

Pagination

Pagination links are returned in the Link response header, following Web Links specifications (RFC 5988). Two additional headers contain cursor values:

HTTP/1.1 200 OK  
Next-Cursor: 1374004777531007878  
Previous-Cursor: 1374004777531007833  
Link: </api/v2/client/requests/?cursor=1374004777531007833>; rel="previous",  
      </api/v2/client/requests/?cursor=1374004777531007878>; rel="next"

Date format

All dates returned or expected in the API use ISO 8601:

  • Dates: YYYY-MM-DD (e.g. "2018-12-31")
  • Datetimes: YYYY-MM-DDThh:mm:ss±zzzzzz or YYYY-MM-DDThh:mm:ss,n±zzzzzz
    (e.g. "1999-04-22T01:23:45+00:00")

eSignature methods

With API v2, the eSignature API is redesigned to provide a more granular signing process. Though it requires more than one call, it lets you update specific parts of the signature process.

Hint
For a more in-depth guide to using our APIs to launch a signature process, see our guide: How to launch a signature process with UKG HRSD API v2.

Warning
API v1 will be deprecated on 1st Oct 2025. More info: [API lifecycle & deprecation policy].