REST API v2

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

Endpoints

UKG HR Service Delivery REST API Endpoints (swagger documentation).

Base URLs

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

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.

The 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, you should just 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

Wrong application_id or application_secret:

HTTP/1.1 401 Unauthorized

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

Wrong client_id:

HTTP/1.1 400 Bad Request

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

Wrong scope:

HTTP/1.1 400 Bad Request

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

Wrong grant_type (should be client_credentials):

HTTP/1.1 400 Bad Request

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

Access Token usage

The OAuth access_token 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 attempts to return appropriate HTTP status codes for every request:

  • HTTP 200: the request is a success

  • HTTP 201: the resource has been created

  • HTTP 400 Bad Request: The request was invalid or cannot be otherwise served. Please review the error message in the body of the response for more details

  • HTTP 401 Unauthorized: Authentication credentials were missing or incorrect

  • HTTP 403 Forbidden: The request is understood, but it has been refused or access is not allowed

  • HTTP 404 Not Found: The URI requested is invalid or the resource requested does not exist

  • HTTP 422 Unprocessable Entity: When updating or creating resources, sending invalid fields results in a 422 Unprocessable Entity response with a JSON body containing error details on each field.

Error messages

When the API returns error messages, it does so in JSON format, with the following keys:

  • code: machine-parseable error code refining the HTTP status code

  • message: human readable description of the error

  • errors: (optional) In case of input field validation errors (HTTP 422 Unprocessable Entity), the errors attribute contains the list of validation field errors. Each validation field error object has the following attributes:

    • field: key of the field in the input json payload

    • code: machine-parseable error code of the error

    • message: human readable description of the error.

HTTP 401 Unauthorized Example:

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

HTTP 422 Unprocessable Entity Example:

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

HTTP 422 Unprocessable Entity Example Nested example:

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

HTTP 422 Unprocessable Entity Nested list example:

{
  "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"
    }
  ]
}

Error codes

The following list describes the main error codes. It is not an exhaustive list.

  • invalid_request: The request is missing a required parameter, includes an unsupported parameter or parameter value, repeats the same parameter, uses more than one method for including an access token, or is otherwise malformed. The server responds with the HTTP 400 Bad Request status code.

  • invalid_token: The access token provided is expired, revoked, malformed, or invalid for other reasons. The server respond with the HTTP 401 Unauthorized status code.

  • invalid_credentials: The credentials are missing or invalid. The server respond with the HTTP 401 Unauthorized status code.

  • insufficient_scope: The request requires higher privileges than provided by the access token. The server responds with the HTTP 403 Forbidden status code.

  • invalid_client_id: Client not valid or not found. The server respond with the HTTP 400 Bad Request status code

  • validation_error: The input payload contains validation errors. The server respond with the HTTP 422 Unprocessable Entity status code

Date format

All dates returned or expected in the API should be in the ISO 8601 format:

  • Dates: aaaa-mm-qq format, example: “2018-12-31”

  • Datetimes: aaaa-mm-qqThh:mi:sszzzzzz or aaaa-mm-qqThh:mi:ss,nzzzzzz format, example: “1999-04-22T01:23:45+00:00”

Changelog

  • 2017-04-10 - First version