# 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* ```json { "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* ```json { "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: {% hint style="danger" %} GET GET {% endhint %} ## 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:* ```json {     "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"     } } ``` ## Stripping HTML from responses Some responses contain HTML-formatted content in HTML columns. If your application requires plain text instead, you can ask the API to remove all HTML markup. Include the following header in your request: `Prefer: strip-html` With this header enabled, the API strips all HTML tags from HTML column values before returning the response. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developer.ultimo.net/api-guide/rest/resource-paths.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.