REST

✅Professional ✅Premium ✅Enterprise

As of Ultimo version 18.04 (2018R2), the possibility to retrieve data through a REST API has been added. For cloud customers on Azure, additional functionality to insert and update data (in batch) is now also available.

How to set up

To connect to the REST API, a specific API key has to be created for a client. API keys can be defined in the Ultimo Configuration Tool. An API key contains a definition of available objects (entities) and/or workflows and generates an API key secret to authorise requests. To set up a new API key quickly, it is possible to use an API key template.

Note: For more information on how to configure API keys please contact your Ultimo consultant.

How to connect

The basic URL for requesting entities has the following format:

The service root is the same for every request or query. It contains the environment name, which is the URL to your Ultimo environment. The resource path refers to the specific information you request. The query options determine which parts of this information are presented and how.

Authentication

When sending a request to the REST API, an API key secret should be provided in the header of the request. The API key secret can be generated in the API key manager in the Ultimo Configuration Tool.

Headers

The following (Ultimo specific) headers can/must be used when sending a request:

• The API key secret (required) must be specified in the following format: ApiKey: {API KEY SECRET}

• You can optionally specify in which language you receive the response. If not specified the default user language is returned. The language is returned in the header of the response. You can specify the language in the following format:

  • Accept-Language: NL

  • Accept-Language: en-US

• You can optionally specify for which company you want to make a request. This header is only required when the API key in Ultimo is configured to work with multiple companies. If only one company is available, that company will always be used no matter the API configuration or the header. The company can be specified in the following format:

  • Ultimo-Company: 000001

Record authorisation

Record authorisation is taken from the system user which is linked to the API key.

When record authorisation is applied on a table, for example the Department table, it is only possible to retrieve, update, or delete records that refer to the authorised department(s) or records from tables that are not related to the Department table.

To insert records that refer to the authorised department(s), the desired department needs to be specified in the request body. If the ‘Department’ property is not added to the request body, the default value will automatically be used.

Note: For more information on how to configure record authorisation please contact your Ultimo consultant.

Response format

Ultimo REST API always returns a JSON response.