Requesting data

With the GET request method, API clients can retrieve information from Ultimo.

Example request

GET https://customer.ultimo.net/api/v1/object/Equipment('00001')

Example response

{
  "Id": "00001",
  "Code": null,
  "Context": 1,
  "Description": "Heftruck 1 type 35 ",
  "InstallDate": "2016-06-20",
  "ManufactureYear": 2013,
  "NextPmMaintenanceDate": "2022-12-25",
  "Status": 2,
  "SerialNumber": "2344-323AA",
  "CostCenter": "05",
  "Department": "05",
  "EquipmentType": "0025",
  "PartOfEquipment": null,
  "ProcessFunction": null,
}

Resource paths

The next examples explain the different uses of resource paths:

• Retrieve a list of entities by using an entity set: GET https://customer.ultimo.net/api/v1/object/Equipment/

• Retrieve a list of custom entities: GET https://customer.ultimo.net/api/V1/Object/_Entity/

• Retrieve a single entity by using an entity key: GET https://customer.ultimo.net/api/v1/object/Equipment('00001')

• Retrieve a single entity with a composite key by using multiple key properties: GET https://customer.ultimo.net/api/v1/object/EquipmentSparePart(Equipment='00001',Article='0191')

• The resource path can be nested so it is possible to retrieve a single entity by following a navigation property from a single entity to another single entity: GET https://customer.ultimo.net/api/v1/object/Equipment('00001')/Department

• Or by following a navigation property from a single entity to a collection of entities: GET https://customer.ultimo.net/api/v1/object/Department('01')/Jobs

• The path segments can be composed recursively: GET https://customer.ultimo.net/api/v1/object/Department('01')/Jobs('0000002')/Equipments

• When retrieving an entity with multiple key properties that includes a navigation property of the related entity the key properties can be omitted: GET https://customer.ultimo.net/api/v1/object/Building('0001')/BuildingParts(Building='0001',Id='001')/BuildingFloors

• The previous example can be shortened to: GET https://customer.ultimo.net/api/v1/object/Building('0001')/BuildingParts('001')/BuildingFloors

Pagination

Loading large datasets can be slow. Pagination is used when retrieving entity lists, to load the data incrementally which improves the response times and the user experience. Ultimo REST API uses Server-Side Pagination, meaning that the server returns the first page of results. If the total number of results is greater than the page size, the server returns the first page along with a nextPageLink that can be used to fetch the next page of results.

Example with nextPageLink in the response body

{
  "nextPageLink": "https://customer.ultimo.net/api/v1/object/Equipment?skip=1000",
  "items": [
    {
      "Id": "00001",
      "Context": 1,
      "Description": "Heftruck 1 type 35 ",
      "Status": 2
    }
    [...]
  ]
}

When requesting large datasets, make sure to always use the provided nextPageLink to retrieve all records until the nextPageLink is no longer provided. The default number of results per page may change over time.

External identifiers

It is possible to retrieve data using an external identifier in the resource path. The external identifier of a resource should be stored in the Ultimo ExternalId property. It is not required to add ExternalId as a property to the API key resources to retrieve data with an external identifier. The combination of ExternalId and DataProvider is unique in Ultimo. Based on this, the record will be identified. Note: when a specific DataProvider is set on the API key definition in Ultimo, the record will only be found if the same DataProvider is set on the record.

The next examples explain the different uses of resource paths using the external identifier:

• Retrieve a single entity: GET https://customer.ultimo.net/api/v1/object/Equipment(ExternalId='00001')

• Retrieve a single entity with a composite key: GET https://customer.ultimo.net/api/v1/object/EquipmentSparePart(ExternalId='0191')

• The resource path can be nested so it is possible to retrieve a single entity by following a navigation property from a single entity to another single entity: GET https://customer.ultimo.net/api/v1/object/Equipment(ExternalId='00001')/Department

• Or by following a navigation property from a single entity to a collection of entities: GET https://customer.ultimo.net/api/v1/object/Department(ExternalId='01')/Jobs

• When retrieving an entity with multiple key properties that includes a navigation property of the related entity the key properties can be omitted: GET https://customer.ultimo.net/api/v1/object/Invoice(ExternalId='001')/Lines

It is NOT possible to use the external identifier when the URL contains a nested path with at least two ExternalId usages, or with a combination of the Ultimo Id and an external Id. Examples of bad requests:

GET https://customer.ultimo.net/api/v1/object/Department(ExternalId='01')/Jobs(ExternalId='002')/Equipments GET https://customer.ultimo.net/api/v1/object/Department(ExternalId='01')/Jobs('0002')/Equipments

Multi-lingual output

It is possible to configure an API key to give multi-lingual output. When this is set, all the available languages will be returned. In this case, the Accept-language header is redundant.

Example of a response with a multi-lingual property:

{ 
    "Id": "01", 
    "Description": { 
        "NL": "NL value", 
        "EN": "EN value", 
        "DE": "DE value", 
        "FR": "FR value", 
        "PL": "PL value", 
        "ES": "ES value", 
        "IT": "IT value", 
        "TR": "TR value" 
    } 
}