Overview

Ultimate's global HR Service Delivery (HRSD) solutions help HR teams upgrade the employee experience, improve HR agility, and ease compliance management through employee case management technology, a knowledge portal, process automation, and file management capabilities.

Please be aware the UltiPro HRSD APIs vary slightly from your regular UltiPro APIs (authentication, base urls, etc...) They will converge at a later stage for easier consumption. 

 

Solutions

Ultimate's HRSD solution include:

  • UltiPro Employee File Management helps HR teams actively and securely manage employee documents in order to meet local compliance requirements. HR can create, store, access, share, and delete employee files in one place, accessible on any device and available wherever you are.
  • UltiPro Employee Case Management enables your HR team to deliver a consumer-level employee experience by easily helping employees, anytime, anywhere, from a simple question to a complex event, including access to a personalized knowledge portal. With process automation capabilities built in, you automate and optimize almost any HR event, including those that span multiple systems and teams.

Base URLs

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

Production Base URLs:

Staging Base URLs:

 

Authentication

The authentication on UltiPro HRSD API endpoints requires the retrieval of a specific 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.

Your application credentials (application_id, application_secret and client_id) will be provided for you on request during the setup phase by your Customer Success Manager.

 

Getting 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.

 

Using the access_token

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.

 

Pagination

Pagination links are available in the Header of the answers under the field Link. Its format follows the Web Links specifications as described on https://tools.ietf.org/html/rfc5988. In addition, two response headers contain the next and previous cursors:

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 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”

 

Error codes & Response

HTTP Status codes

The UltiPro HRSD API attempts to return appropriate HTTP status codes for every request:

  • HTTP 200: The request is a success
  • HTTP 201: The resource is created
  • HTTP 400 Bad Request: The request is invalid or cannot be otherwise served. An accompanying error message provides more details
  • HTTP 401 Unauthorized: Authentication credentials are missing or incorrect
  • HTTP 403 Forbidden: The request is understood, but it is not fulfilled 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 will result 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-parsable 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-parsable 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 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 responds with the HTTP 401 Unauthorized status code.
  • invalid_credentials: The credentials are missing or invalid. The server responds 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 responds with the HTTP 400 Bad Request status code
  • validation_error: The input payload contains validation errors. The server responds with the HTTP 422 Unprocessable Entity status code