- 1. Introduction
- 2. Prerequisites
- 3. Base URL
- 4. Authentication
- 5. Errors
- 6. Generic APIs
- 7. Other APIs
- 8. API Examples for often-used objects in Asset
- 8.1.1 Get a list of organizations
- 8.1.2 Get a list of persons
- 8.1.3 Get a list of buildings
- 8.1.4 Get a list of areas
- 8.1.5 Get a list of assets
- 8.1.6 Get a list of asset categories
- 8.1.7 Get a list of requests.
- 8.1.8 Get a list of problem types
- 8.1.9 Get a list of members per service group
- 8.1.10 Get a list of corrective work orders
- 8.1.11 Get a list of preventive work orders
- 8.1.12 Create an asset
- 8.1.13 Create a request
- 8.2 Postman project
1. Introduction
Web services enable the retrieval, creation, and updating of data within an Asset environment.
The Asset API is built on a REST-based framework, with authorization handled through Bearer tokens and a pre-shared key.
This document focuses on incoming web services related to our Generic Functions API. At the customer level, additional outgoing web services can be developed—using custom scripts and integrations—to connect with external applications on a case-by-case basis.
2. Prerequisites
To be able to use the APIs, some pre-conditions apply. A (technical) consultant can setup these pre-conditions.
An Asset environment with the following sub-conditions:
- Incoming web services are enabled via the following access rules (Client settings → Authentication tab → Access rules include):
- [This step is only nessecary when using OAuth 2.0. as apose to basic auth, as described below] An API Connector object (which can also be created via the Authentication tab on the general settings as a level 3 administrator) with a trust relation (key type = AES shared key) is available with the authorized system user of the trust relation, also linked to the API Connector in the system user tab:
- Make sure to add the domain in the 'Allowed origins for REST web services' field (Client settings → Authentication tab), if you want to allow external domains to access the generic web services asynchronously (Cross-Origin Resource Sharing (CORS)).
2.1 Required parameters
The following parameters are needed to set up the API calls successfully:
Parameter | Description | Example |
|---|---|---|
server | The base URL of the tenant, either the tenant-specific domain or a general server. | https://demotenant.axxerion.com |
client_reference | The reference of the environment | demotenant |
username | The username of the system user on behalf of whom you want to authenticate. Relevant for the bearer token authentication. This user must be linked to the API Connector via the system user tab. [Relevant when using OAuth 2.0. instead of basic auth] | demo_api |
app_id | The reference of the API Connector. Relevant for the bearer token authentication. [Relevant when using OAuth 2.0. instead of basic auth] | DTW-EA-001 |
x_access_id_value | The Access ID of the trust relation. Relevant for the bearer token authentication. [Relevant when using OAuth 2.0. instead of basic auth] | demo_api_id |
secret_key | The secret key of the trust relation. Relevant for the bearer token authentication [Relevant when using OAuth 2.0. instead of basic auth] | DB2E51543E463290B946602B8047CC9E16048E2C99728DB2E51543E463290B946602B8047CC9E16048E2C99728 |
authentication_mode | Fixed value: 'GENERIC' Relevant for the OAuth 2.0-based bearer token authentication. [This is only required for the automated scripting for token requests in Postman when using OAuth 2.0. instead of basic auth] | GENERIC |
3. Base URL
Every endpoint consists of a base URL: https://{server}/webservices/{{client_reference}}/rest/functions
Both ‘server' and ‘client_reference’ should be filled in based on the environment parameters (see ‘Required parameters’ in the chapter above).
4. Authentication
There are two methods supported related to authentication for the APIs:
- basic Auth
- OAuth 2.0
4.1 Basic Auth
Basic authentication - Using a username and password of a user with relevant authorizations configured in the client - is supported. However, as this is both less secure and will eventually be completely replaced by OAuth 2.0, it is advised to use the OAuth 2.0 with bearer token method of authentication, as described in the next part.
4.2 API OAuth 2.0 authorization scheme
General
To obtain access to the resources exposed by the Asset REST API, clients must first request a bearer token. The procedure for this is outlined below:
Grant type
Bearer tokens can be obtained using the OAuth grant type ‘Resource Owner Password Credentials’. Even though this grant type suggests that a password is used, this is not the case in this authorization scheme. Instead of a password, a token request message should be encrypted using a pre-shared AES key, which the endpoint will validate, and a bearer token will be returned when authentication succeeds. Resource data returned by the resource endpoints depends on user access rights to the relevant resources.
Token request message
The token request message is a JSON message which should contain the following data where terms between brackets should be replaced by their literal values:
jsonwide760note92b97441dc10It is possible to use the literal alias “axx::access::admin” as username (without the additional quotes). When doing this, instead of using the actual username of the user requesting the resources, access will be requested on behalf of the default authorized system user linked to the (pre-shared AES key based) trust relation used by the external application.
It is possible to use the literal alias “axx::access::admin” as username (without the additional quotes). When doing this, instead of using the actual username of the user requesting the resources, access will be requested on behalf of the default authorized system user linked to the (pre-shared AES key based) trust relation used by the external application.
Encrypting the token request message
The token request message should now be encrypted using the pre-shared AES key, which can be generated in Asset using AES-CBC mode, resulting in a cipher text and an IV (initialization vector). Now build a string using the following format:
wide760This resulting string should be sent in the actual token request as “encrypted-params”; see next paragraph.
Create an actual HTTP request for the token endpoint
Now, to form the HTTP request for the token endpoint, a POST request should be generated to the following endpoint (where the server should be replaced by the server domain):
The request should contain at least the following headers (where the terms between brackets should again be replaced by the actual values):
wide760The request body should contain form URL-encoded data as described in the table below:
key | value |
|---|---|
| [encrypted-params] |
When the server grants the authorization request, 200 OK responses should be received containing the bearer token that can be used for accessing the resource endpoints as long as the token is valid.
An example of the script can be found via the example Postman Collections in the Pre-request script tab, which can be downloaded at the bottom of this document.
5. Errors
The API can return the following error codes:
Error Code | Meaning | Description |
|---|---|---|
400 | Bad Request | Your request is invalid |
401 | Unauthorized | The provided credentials are invalid, or the user does not have sufficient access |
403 | Forbidden | Access to the requested resource is denied due to insufficient permissions |
404 | Not Found | The requested resource could not be found on the server. This often means the endpoint or object does not exist. |
405 | Method Not Allowed | The HTTP method used is not supported for this resource (e.g., using POST, where only GET is allowed) |
412 | Precondition Failed | One or more required conditions were not met. |
500 | Internal Server Error | An unexpected error occurred on the server. |
503 | Service Unavailable | The server is temporarily unavailable. Please try again later. |
6. Generic APIs
Most objects in Asset can be created, updated, and/or archived/deleted via the same endpoints, using object-specific parameters within these endpoints. This removes the need for using specific endpoints for each type of object.
The following parameters are used in the API endpoints described below, next to some of the parameters already described above:
parameter | description | example |
|---|---|---|
| The type of object (e.g. the object class). All available object types can be found in the client layer environment as ‘objects’. | Request |
| Some types of objects also have categories, and a new instance is created within such a category. If the category is not provided, the instance is created in the first available category. It is advised to always specify the category if applicable, as changes to the available categories can occur, resulting in unintended behavior, if not specified. For more information on categories, see: Categories | 720000000000296 |
| When updating an existing instance you need to provide the ID value of that instance. When a new instance is created via the API, both the uniqueReference (if applicable) and the DatabaseId are included in the response. | 5005958a-7a14-45bf-a3da-5e2aaecff011::g1 OR: 720000000000296 |
| When creating a new instance in the context of another instance, you need to provide the type of object of the context instance. | See object_name |
| When creating a new instance in the context of another instance, you need to provide the uniqueReference or the DatabaseId value of the instance in context. See ' | See object_id |
| This is used when executing a workflow function on behalf of a user (for example, to submit a request). You need to use the actual workflow function name for this. The available function names can be found in the page definition of the page used in the workflow. | submit |
| This is used when updating fields on an instance. Both for existing instances, as well as when creating a new instance. The field name needs to be the technical field name. For more details, see below in createupdate ‘updating the fields’. | |
| This is used when updating fields on an instance; together with the field_name, the field_value is used to specify the actual value the field needs to get. For more details, see below in createupdate ‘updating the fields’. | “john.doe@spacewell.com“ |
The following general API functions are supported:
6.1 createupdate
POST call to create a new object and update the specified fields on that object. The endpoint should also contain the correct object name (e.g. Area, Asset, Contact, Request).
POST https://{server}/webservices/{client_reference}/rest/functions/createupdate/{object_name}
If the object also has Categories, the databaseId of the category should also be specified in the endpoint, to create the object in that category:
POST https://{server}/webservices/{client_reference}/rest/functions/createupdate/{object_name}/{category_folder_id}
To get the relevant categoryId, the quickest way is to create a report that returns the (relevant) category folders and fetch this report via a completeReportResult, as the Id of the categories will be part of the result.
Updating the fields:
In almost all cases, it is relevant to also set some fields when creating an object. The fields and the values need to be provided in the body of the call.
The fieldnames need to be the actual fieldnames as found in the system (to be found via object → fields)
The values are the desired values that need to be set. How to provide the values depends on the type of field. Some of the most often used field types and how to set these is shown in the table below:
Type of field | input | example |
|---|---|---|
Text | text | “My example text“ |
Date/time | Date/time fields must be entered in ISO 8610 Combined date and time representations (See https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) | “2024-11-30T10:00:00Z“ |
Integer | number | 10 |
Object selection (e.g., to set a contact as the requestor in a request) | The databaseId value or (if available) the uniqueReference of the object. See | “720000000000002” or “076bc687-d25f-4555-acda-ea74864fefe0::g1” |
Bolean | True or False | True |
Enumeratie value | integer value of the enumeration [can be found in the client layer via enumerations] | 2000 |
Info
Per specific field, other limitations or more specific inputs can be required. E.g., some text fields only allow a limited number of characters, other fields might require specific inputs, depending on the field and the implementation of the field.
Example body:
{
"exampleTextField" : "My example text",
"exampleDateTimeField" : “2024-11-30T10:00:00Z“,
"exampleIntegerField" : 10,
“exampleObjectField” : “076bc687-d25f-4555-acda-ea74864fefe0::g1”,
“exampleBoleanField“ : True,
“exampleEnumerationField“ : 2000 ;
}
6.1.1 Create in the context of another object
It is also possible to create a new object in the context of another object. For instance, areas are always part of a building (object “Property”). By also specifying the context object type and context object ID, this can be achieved.
POST https://{server}/webservices/{client_reference}/rest/functions/createupdate/{object_name}/{context_object_name}/{context_object_id}
N.b. the same can be achieved by specifying the relevant field in the regular createUpdate body. For instance, set the propertyId to the ID value of the property in context when creating an area. However, certain business logic might not be executed correctly if the object is not created in context directly, but by field update.
6.2 update
PUT call to update fields on an existing object. The endpoint should also contain the correct object name (e.g., Area, Asset, Contact, Request) as well as the ID (databaseId or uniqueReference) value of the specific object to update.
PUThttps://{server}/webservices/{client_reference}/rest/functions/update/{object_name}/{object_id}
The fields that need to be updated and the values need to be provided in the body of the call. This is similar to the createUpdate call described above.
Whether or not a field can be updated can depend on multiple reasons, as the access the user has to the field can depend on specific user rights, a workflow that is used for the object that determines the access to fields for a given status, or other specific business logic.
6.3 delete
DELETE call to delete a specific object. The endpoint should also contain the correct object name (e.g., Area, Asset, Contact, Request) as well as the ID (databaseId or uniqueReference) value of the specific object to delete.
DELETE https://{server}/webservices/{client_reference}/rest/functions/delete/{object_name}/{object_id}
Whether or not an object can be deleted can depend on multiple reasons, for instance, the access the user has to the object, as well as if the object is allowed to be deleted, as some objects can only be archived. For more general information about deleting vs archiving, see: Deleting and archiving - Knowledge Base - Knowledge Base
6.4 archive
DELETE call to archive a specific object. The endpoint should also contain the correct object name (e.g., Area, Asset, Contact, Request) as well as the ID (databaseId or uniqueReference) value of the specific object to archive.
DELETE https://{server}/webservices/{client_reference}/rest/functions/archive/{object_name}/{object_id}
The fields that need to be updated and the values need to be provided in the body of the call. This is similar to the createUpdate call described above.
Whether or not an object can be archived can depend on multiple reasons, for instance, the access the user has to the object.
6.5 restore
PUT call to restore a specific object from the bin (after a delete) or the archive (after an archive function was performed). The endpoint should also contain the correct object name (e.g., Area, Asset, Contact, Request) as well as the ID (databaseId or uniqueReference) value of the specific object to restore.
PUThttps://{server}/webservices/{client_reference}/rest/functions/restore/{object_name}/{object_id}
6.6 executefunction
PUT call to execute a workflow function (a step in the workflow) for objects that have an active workflow connected. The workflow function needs to be specified in the endpoint. The endpoint should also contain the correct object name (e.g., Area, Asset, Contact, Request) as well as the ID (databaseId or uniqueReference) value of the specific object for which the workflow function should be executed. Workflow function names can be found in the client layer via the relevant enumeration based on the status field used in the workflow (e.g., the Request workflow uses the status field ‘RequestStatusCode’, which has the corresponding enumeration ‘RequestStatus’. In this enumeration, the relevant statuses can be found.
PUT https://{server}/webservices/{client_reference}/rest/functions/executefunction/{object_name}/{object_id}/{workflow_function_name}
It is only possible to execute a workflow function if the current status of the workflow for the given object allows for this function to be executed (the workflow needs to be in the right place) and the user has the task/rights to execute this function. Next to that, any specific condition in the workflow connector that is used when executing the function should also allow the execution of the function (e.g., it might require certain fields to be filled in).
6.7 findall
GET call to return all instances of a given object type. The endpoint needs to contain the object name (e.g., Area, Asset, Contact, Request)
GET https://{server}/webservices/{client_reference}/rest/functions/findall/{object_name}
The result will contain every field of the objects returned. It is important to notice that not every field is relevant, and the actual fields relevant for a customer might only be a small subset.
This endpoint does not offer any filter options or options to either limit the fields in the response, or change the way certain fields are returned (e.g., show the name of a contact instead of the databaseId).
For more finetuned filter options, please refer to the CompleteReportResult option below. This is also the preferred method, as it can be created with the specific needs in mind.
6.8 findbyfield
GET call to return all instances of a given object type based on a single field value. The endpoint needs to contain the object name (e.g., Area, Asset, Contact, Request) as well as the field to filter on and the value of that field.
GET https://{server}/webservices/{client_reference}/rest/functions/findbyfield/{object_name}/{field_name}/{field_value}
The result will contain every field of the objects returned. It is important to notice that not every field is relevant, and the actual fields relevant for a customer might only be a small subset.
This endpoint does not offer the option to filter on more than 1 field, or options to either limit the fields in the response, or change the way certain fields are returned (e.g., show the name of a contact instead of the databaseId). For more finetuned filter options, please refer to the CompleteReportResult option below. This is also the preferred method, as it can be created with the specific needs in mind.
6.9 CompleteReportResult
POST call via which a specific report can be executed. The body of this call needs to contain the report reference and can contain filter fields and values of those fields, based on the available filter fields of the given report.
POST https://{server}/webservices/{client_reference}/rest/functions/completereportresult
Minimal body:
{
"reference":"{report_reference}"
}
body with filter fields:
{
"reference":"{reportReference}",
"filterFields":["{filterfield1}","{filterfield2}"],
"filterValues":["{filterFieldvalue1}","{filterFieldvalue2}"]
}
This call gives the most flexible options with regard to pulling data, as it can be used to execute any available report, including any custom report created. This gives complete freedom over the filter values (as well as any desired fixed filters in the report, that do not need to be specified in the API call (e.g., always return only open requests) and the fields in the result.
Available reports, and details regarding which filter fields are available, as well as the option to create additional reports, is available via the ‘Reports’ option in a tenant environment as a (level 3) administrator user.
7. Other APIs
The following APIs are available for specific purposes, not related to every object:
7.1 Import connectors:
7.1.1 Upload documents to an FTP connector
POST call to upload one or more documents (.csv files) to the FTP connector with the FTP connector reference specified in the endpoint. The content type must be multipart/form-data, which allows uploading multiple files with one REST request. The specification of multipart/form-data is publicly available.
POST https://{server}/webservices/{client_reference}/rest/functions/v2/connectors/{ftpconnector_reference/document
The resulting action (importing data in the system) is an asynchronous action and therefore the REST response is:
{"status":status,"uuid":uuid,"type":"ConnectorDocumentResponse","infoMessage":"The FTP connector will be started in the background.""response":{"submitted":date-time-submitted,"status":status}}
where:
- status indicates the status of the REST request.
- date-time-submitted is the date and time that the document was submitted for upload.
For more general information about imports and import connectors, see: Default imports.
7.1.2 Check the import status of the FTP connector
GET call to check the status of the latest import of the FTP connector with the FTP connector reference specified in the endpoint. Since the API to upload a document to an FTP connector results in an asynchronous action to perform the import, this APi call can be used to fetch the current status.
GET https://{server}/webservices/{client_reference}/rest/functions/v2/connectors/{ftpconnector_reference}/status
The REST response is:
{"status":status,"uuid":uuid,"type":"ConnectorStatusResponse","response": {
"message":message, "filesProcessed":number-of-files-processed, "startTime":start-date-time, "endTime":end-date-time, "warnings":number-of-warnings, "errors":number-of-errors, "created":number-of-objects-created, "updated":number-of-objects-updated, "deleted":number-of-objects-deleted, "interrupted":boolean-value, "status":status }}
where:
- status indicates the status of the REST request.
- message is the message that the FTP connector returns.
- number-of-files-processed is the number of files that the FTP connector has processed.
- start-date-time is the date and time that the last import has started. If this value is not present, the FTP connector did never start an import.
- end-date-time is the date and time that the last import has ended. If this value is not present, the FTP connector did never start an import, or it is still running.
- number-of-warnings is the number of warnings from the FTP connector.
- number-of-errors is the number of errors from the FTP connector.
- number-of-objects-created is the number of objects that were created by the import.
- number-of-objects-updated is the number of objects that were updated by the import.
- number-of-objects-deleted is the number of objects that were deleted by the import.
- boolean-value is either
"true"or"false", and it indicates whether or not the import was interrupted.
You can use start-date-time and end-date/time to check if all imports have finished. If the start date and time are later than the start date and time from the previous REST request, and the end date and time are not empty (that is, it has a value), all imports have finished.
Note: You cannot execute this REST command more than once per minute, to prevent overloading the system.
7.1.3 Retrieve import log
GET call to retrieve the log file of type log-type of the latest import of the FTP connector with the FTP connector reference specified in the endpoint. If the setting Save documents has value Yes, an FTP connector creates two log files for each import: an info log, which is a log file of type info, and an error log, which is a log file of type error. The info log is always present; the error log is only present if errors occurred.
GET https://{server}/webservices/{client_reference}/rest/functions/v2/connectors/{ftpconnector_reference}/document?type=info
The REST response, of type application/octet-stream, is the import log file.
Note: You cannot execute this REST command more than once per minute, to prevent overloading the system.
7.2 Documents
7.2.1 Download a document
GET call to download a document with the document reference specified in the endpoint.
https://{server}/webservices/{client_reference}/rest/functions/v2/documents/{document_reference}
To only download the preview of the document, use the following parameter: format=preview
Using the uniqueReference value instead of the regular reference:
Since the regular reference (e.g., D-XXXXXX) does not have to be unique, it is also possible to use the UniqueReference of the document as documentReference value in the endpoint; however, in order for this to work, the following parameter should be added: idForRef=true
7.2.2 Uploading a document
POST call to upload a file in the system and link it to the object specified in the endpoint via the {instanceId} value. The type of object of this instanceId should also be specified via the {ObjectName} value in the endpoint. The filename can be specified in the endpoint as well:
https://{server}/webservices/{client_reference}/rest/functions/upload/{object_name}/{object_id}?name=file-name
The REST request header must specify the content type of the file. The content types that are accepted are:
- binary/octet-stream
- application/pdf
- application/msword
- application/vnd.ms-excel
- image/png
- image/gif
- image/jpeg
Note the following:
- The
object_idmust be the databaseId of the object in context. Using the Unique Reference is not (yet) supported when uploading a document - If
object_nameis Document, the system does not create a Document instance. Instead, Axxerion creates a new DocumentVersion instance linked to the Document instance with id instance-id, and attaches the file to this DocumentVersion instance. - If the size of the file is greater than the maximum file size that Axxerion accepts, Axxerion returns an error to the service requester.
7.3 Event log
POST call to create an event log.
Query Parameters
Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
type | String | NO | info | Event log type: info, warning, error, debug |
Path Parameters
Parameter | Type | Description |
|---|---|---|
objectName | String | Object name (e.g., Asset, Request) OR numeric objectNameId |
instanceId | String | Instance ID (numeric) OR unique reference (e.g., f3ea04a9-6153-430e-a96d-80fdf378c806::g1) |
Request Body
The request body should contain the log message as plain text.
Content-Type | Description |
|---|---|
text/plain | The log message text (stored in EventLog.detailsClob) |
Automatically Set Fields
- clientId - From authenticated session
- externalAppId - From session context (if available)
- logId - Set via "RestApi" LogName
Event log without linking it to a specific object in Asset:
wide760Event log linked to a specific object, by adding the ‘objectName’ and ‘instanceId’.
wide760wide760Event log linked to a specific object, by adding the ‘objectName’ and ‘instanceId’ (uniqueReference) plus the type of log included (info/warning/error).
wide760Success Response:
wide760Error Response:
wide760When an Event Log is created via this endpoint, relevant system fields (such as date and the API Connector in context) are automatically populated.
8. API Examples for often-used objects in Asset
The following section gives detailed examples on how to create, fetch, and update certain often-used data in Asset, using the generic APIs described above. For the completereportresult API’s, the relevant reports to use as filter, including additional filter fields, are described:
8.1.1 Get a list of organizations
This POST call will fetch all the organizations (Own organizations and suppliers) in the tenant with the relevant information per organization.
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/completereportresult
Body:
{ "reference":"API_Report_Organizations_01", "filterFields":["Email"], "filterValues":["example@email.com"]}
The reference is mandatory; this determines the correct report to be executed: API_Report_Organizations_01
The filter fields are optional.
Available filter fields:
It is possible to filter the organizations based on an email address: Email
Example result:
8.1.2 Get a list of persons
This POST call will fetch all the persons in the tenant with the relevant information per person.
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/completereportresult
Body:
{ "reference":"API_Report_Contacts_01", "filterFields":["Email"], "filterValues":["noreply@spacewell.com"]}
The reference is mandatory; this determines the correct report to be executed: API_Report_Contacts_01
The filter fields are optional.
Available filter fields:
It is possible to filter the persons based on an email address: Email
Example result:
8.1.3 Get a list of buildings
This POST call will fetch all the buildings in the tenant with the relevant information per building.
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/completereportresult
Body:
{ "reference":"API_Report_Properties_01"}
The reference is mandatory; this determines the correct report to be executed: API_Report_Properties_01
This call does not support any additional filter fields
Example result:
8.1.4 Get a list of areas
This POST call will fetch all the areas in the tenant with the relevant information per area.
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/completereportresult
Body:
{ "reference":"API_Report_Areas_01", "filterFields":["Property"], "filterValues":[[1210000000000849]]}
The reference is mandatory; this determines the correct report to be executed: API_Report_Areas_01
The filter fields are optional.
Available filter fields:
It is possible to filter the areas based on a specific building: Property
The filter value needs to be the Id of the building, as fetched via the building API call.
Example result:
8.1.5 Get a list of assets
This POST call will fetch all the assets in the tenant with the relevant information per asset.
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/completereportresult
Body:
{ "reference":"API_Report_Asset_01", "filterFields":["Property","Area"], "filterValues":[[1000066632],[1000212917]]}
The reference is mandatory; this determines the correct report to be executed: API_Report_Asset_01
The filter fields are optional.
Available filter fields:
It is possible to filter the assets based on a specific building: Property
It is possible to filter the assets based on a specific area: Area
The filter value needs to be the Id of the building and/or area, as fetched via building and area API calls.
Example result:
8.1.6 Get a list of asset categories
This POST call will fetch all the asset categories in the tenant. The Id of an asset category can be used to create a new asset in the desired category (See Create an Asset). E.g., Car, Bike, Coffee machine.
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/completereportresult
Body:
{ "reference":"API_Report_Asset_Categories_01"}
The reference is mandatory; this determines the correct report to be executed: API_Report_Asset_Categories_01
This call does not support any additional filter fields
Example result:
8.1.7 Get a list of requests.
This POST call will fetch all the requests in the tenant with the relevant information per request.
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/completereportresult
Body:
{ "reference":"API_Report_Requests_01", "filterFields":["CreatedSince","CreatedUntil"], "filterValues":["2023-01-01T00:00:00Z","2023-08-01T00:00:00Z"]}
The reference is mandatory; this determines the correct report to be executed: API_Report_Requests_01
The filter fields are optional.
Available filter fields:
It is possible to filter the requests based on the create times: CreatedSince and CreatedUntil
Date/time filters must be entered in ISO 8610 Combined date and time representations (See https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations)
The following filter fields can also be used (not shown in the body above):
- Asset (Specify the ID value of an Asset, to get the requests linked to this asset)
- Area (Specify the ID value of an Area, to get the requests linked to this area)
- Property (Specify the ID value of a Property, to get the requests linked to this property)
Example result:
8.1.8 Get a list of problem types
This POST call will fetch all the problem types (A problem type is used to determine the type of request and which service group will be assigned to handle the request) in the tenant with the relevant information per problem type.
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/completereportresult
Body:
{ "reference":"API_Report_ProblemTypes_01"}
The reference is mandatory; this determines the correct report to be executed: API_Report_ProblemTypes_01
This call does not support any additional filter fields
Example result:
8.1.9 Get a list of members per service group
This POST call will fetch all the contacts in a service group (A service group is used in a problem type and will be used to determine which group will be assigned to handle the request) in the tenant with the relevant information per service group.
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/completereportresult
Body:
{ "reference":"API_Report_ServiceGroupMembers_01"}
The reference is mandatory; this determines the correct report to be executed: API_Report_ServiceGroupMembers_01
This call does not support any additional filter fields
Example result:
8.1.10 Get a list of corrective work orders
This POST call will fetch all the corrective work orders (work orders created on a request) in the tenant with the relevant information per work order.
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/completereportresult
Body:
{ "reference":"API_Report_Corrective_WorkOrders_01", "filterFields":["CreatedSince","CreatedUntil"], "filterValues":["2023-01-01T00:00:00Z","2023-09-01T00:00:00Z"]}
The reference is mandatory; this determines the correct report to be executed: API_Report_Corrective_WorkOrders_01
The filter fields are optional.
Available filter fields:
It is possible to filter the work orders based on the create times: CreatedSince and CreatedUntil
Date/time filters must be entered in ISO 8610 Combined date and time representations (See https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations)
The following filter fields can also be used (not shown in the body above):
- Asset (Specify the ID value of an Asset, to get the corrective work orders linked to this asset)
- Area (Specify the ID value of an Area, to get the corrective work orders linked to this area)
- Property (Specify the ID value of a Property, to get the corrective work orders linked to this property)
- Request (Specificy the ID value of a Request, to get the corrective work orders for this Request)
Example result:
8.1.11 Get a list of preventive work orders
This POST call will fetch all the preventive work orders (work orders created via a maintenance schedule) in the tenant with the relevant information per work order.
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/completereportresult
Body:
{ "reference":"API_Report_Preventive_WorkOrders_01", "filterFields":["CreatedSince","CreatedUntil"], "filterValues":["2023-01-01T00:00:00Z","2024-01-01T00:00:00Z"]}
The reference is mandatory; this determines the correct report to be executed: API_Report_Corrective_WorkOrders_01
The filter fields are optional.
Available filter fields:
It is possible to filter the work orders based on the create times: CreatedSince and CreatedUntil
Date/time filters must be entered in ISO 8610 Combined date and time representations (See https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations)
The following filter fields can also be used (not shown in the body above):
(Since preventive work orders can be linked to multiple objects (e.g. maintenance for 10 elevators), the filtering works a bit differently for corrective work orders. One preventive work order can be returned more than once, depending on the number of objects it is linked to. To filter on a specific object, the ID of the object can be added. This can be an Asset, Area, or building (Be aware, if the work order is linked to a specific asset, it won’t return results if filtered on the building on that asset, it must be filtered specifically on that asset (Or no filter)).
- Object (Specify the ID value of an Asset, Area, or Building to get the preventive work orders linked to this object)
Example result:
8.1.12 Create an asset
This Post call is used to create a new asset
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/createupdate/Asset/{{assetCategory}}
The '{{assetCategory}' in the endpoint URL should be set to an asset category id value (Fetched via the get a list of Asset categories call)
Body with example values:
{ "name": "Example laptop 2", "externalReference": "987654321", "serialNumber": "123456789", "tradeName": "DTwin turbo", "modelName": "model X1", "quantity": "1", "manufacturerContactId": "1210000000005286", "supplierContactId": "", "purchaseDate": "2023-01-01T00:00:00Z", "propertyId": "1210000000000849", "areaId": "1210000000048836", "parentAssetId": "1210000000008548"}
The following fields can be set via the body (all optional):
Parameter | Description |
|---|---|
Name | Free text (255 characters max) |
ExternalReference | Free text (255 characters max) |
serialNumber | Free text (255 characters max) |
modelName | Free text (255 characters max) |
quantity | Integer |
manufacturerContactId | Id value of an organization or person (Fetched via the get a list of organizations or get a list of persons API calls) |
supplierContactId | Id value of an organization or person (Fetched via the get a list of organizations or get a list of persons API calls) |
purchaseDate | Date/time filters must be entered in ISO 8610 Combined date and time representations (See https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) |
propertyId | Id value of a building (Fetched via the get a list of a buildings API call) |
areaId | Id value of an area ( Fetched via the get a list of an areas API call) |
parentAssetId | Id value of an asset ( Fetched via the get a list of an assets API call) |
The response will be the Id value and the UniqueReference of the newly created asset:
8.1.13 Create a request
This Post call is used to create a new request
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/createupdate/Request/1000000786
Body with example values:
{ "fromContactId": "1210000000004567", "name": "Test request", "description": "Test request", "problemTypeId": "1210000000005757", "propertyId": "12100000000057634", "areaId": "1210000000005764", "assetId": "1210000000005734"}
The following fields can be set via the body (all optional):
Parameter | Description |
|---|---|
fromContactId | Id value of an organization or person (Fetched via the get a list of organizations or get a list of persons API |
name | Free text (255 characters max) |
description | Free text (255 characters max) |
problemTypeId | Id value of a problem type (Fetched via the get a list of problem types API call) |
propertyId | Id value of a building (Fetched via the get a list of buildings API call) |
areaId | Id value of an area ( Fetched via the get a list of areas API call) |
assetId | Id value of an asset( Fetched via the get a list of assets API call) |
The response will be the Id value and the UniqueReference of the newly created request
8.2 Postman project
The following links contain an example Postman project and a (dummy) environment based on the API calls described above. The environment should be filled in based on the environment parameters actually to use.