---
title: "API documentation"
canonical: "https://knowledgebase.spacewell.com/space/KB/4357490632/API%20documentation"
format: markdown
---
> Macro (toc)

# 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:**

1. Incoming web services are enabled via the following access rules (Client settings → Authentication tab → Access rules include):

![image](media://20b799b7-5cc0-46ff-afe8-500c0e92e5c6)

2. [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:

![image](media://80c87953-f86b-4b54-84ef-9da0a77b8e75)

3. 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)).

![image](media://d3f5c765-16a4-4e26-bd10-486462e47052)

## **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](https://demotenant.axxerion.com)  
OR  
[https://axpr13.axxerion.com](https://axpr13.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.<br>This user must be linked to the API Connector via the system user tab.<br>*[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.<br>*[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.<br>*[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<br>*[Relevant when using OAuth 2.0. instead of basic auth]* | DB2E51543E463290B946602B8047CC9E16048E2C99728DB2E51543E463290B946602B8047CC9E16048E2C99728 |
| authentication_mode | Fixed value: 'GENERIC'<br>Relevant for the OAuth 2.0-based bearer token authentication.<br>*[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:

![image](media://ab8550e9-1481-43ae-8a28-7f428984f613)

**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:

```json
{
  "grant_type": "password,""
  "username": "[username of the resource owner]",
  "password": "",
  "scope": "session v1 v2 v3",
  "app_id": "[external app id]"
}
```

> 📝 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:

```
[length of the base64 encoded ciphertext]:[base64 encoded ciphertext][base64 encoded IV]
```

This 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):

```
https://[server]/axxerion/aaa/registration/oauth2/token
```

The request should contain at least the following headers (where the terms between brackets should again be replaced by the actual values):

```
'Authorization': 'Axx_encryption_key [trust relation access id]',
'axx-client-reference': '[client_reference]'
```

The request body should contain form URL-encoded data as described in the table below:

| **key** | **value** |
| --- | --- |
| `encrypted-params` | [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** |
| --- | --- | --- |
| `object_name` | The type of object (e.g. the object class). All available object types can be found in the client layer environment as ‘objects’. | Request |
| `category_folder_id` | 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.<br>For more information on categories, see: [Categories](https://onespacewell.atlassian.net/wiki/spaces/KB/pages/4357489130) | 720000000000296 |
| `object_id` | When updating an existing instance you need to provide the ID value of that instance.  
For object types that have a uniqueReference field, you can use the uniqueReference value. This value can be obtained by checking the uniqueReference field of the given instance. For object types that do not have a uniqueReference, you can use the DatabaseId value instead. To find this value for an existing instance, use the Inspect Element option in your browser.<br>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<br>OR:<br>720000000000296 |
| `context_object_name` | 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 |
| `context_object_id` | 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 '`object_id'` above for more information. | See object_id |
| `workflow_function_name` | 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 |
| `field_name` | 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](https://onespacewell.atlassian.net/wiki/spaces/KB/pages/edit-v2/4357490632#6.1-createupdate) ‘updating the fields’. | email |
| `field_value` | 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](https://onespacewell.atlassian.net/wiki/spaces/KB/pages/edit-v2/4357490632#6.1-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](https://support.spacewell.com/space/KB/37093383/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](https://onespacewell.atlassian.net/wiki/spaces/KB/pages/4357490632/API+documentation#6.9-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](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 `object_id` in the previous table for more information. | “720000000000002”<br>or<br>“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 |

> ℹ️ 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. 

PUT`https://{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](https://support.spacewell.com/space/KB/15302657/Deleting+and+archiving)

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

PUT`https://{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 ](https://onespacewell.atlassian.net/wiki/spaces/KB/pages/edit-v2/4357490632#6.9-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](https://onespacewell.atlassian.net/wiki/spaces/KB/pages/edit-v2/4357490632#6.9-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](https://support.spacewell.com/space/KB/104595584/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_id `must be the databaseId of the object in context. Using the Unique Reference is not (yet) supported when uploading a document
- If `object_name `is 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:

```
POST https://{server}/webservices/{client_reference}/rest/functions/v2/eventlog
```


Event log linked to a specific object, by adding the ‘**objectName**’ and ‘**instanceId**’.

```
POST https://{server}/webservices/{client_reference}/rest/functions/v2/eventlog/{objectName}/{instanceId}
```

```
POST https://{server}/webservices/{client_reference}/rest/functions/v2/eventlog/Asset/f3ea04a9-6153-430e-a96d-80fdf378c806::g1
```


Event log linked to a specific object, by adding the ‘**objectName**’ and ‘**instanceId**’ (uniqueReference) plus the type of log included (info/warning/error).

```
POST https://{server}/webservices/{client_reference}/rest/functions/v2/eventlog/Asset/f3ea04a9-6153-430e-a96d-80fdf378c806::g1?type=info
```



**Success Response:**

```
{
  "status": "OK",
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "response": "none"
}
```

**Error Response:**

```
{
  "status": "VALIDATION_ERROR",
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "errorMessage": "error_missing_parameter: message is required"
}
```

When 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:

![image](media://96c614de-a8a9-4ab3-8e76-bcc8951dd004)

### **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:

![image](media://ace0f002-fbe9-452a-a753-edcf71194c53)

### **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:

![image](media://a0347797-ca46-46e8-bcbb-59b4f0f63e6c)

### **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:

![image](media://da1656ac-4eb2-4a50-8324-f800e7f6c0f9)

### **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:

![image](media://45b9b592-10ce-49dc-a699-bbc5364b7f63)

### **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:

![image](media://b0d6db76-e903-45fb-9961-8a4ec7d822d5)

### **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](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:

![image](media://5dbe6f0b-1280-4733-85b0-73c00dd92a9d)


### **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:

![image](media://596bdf13-5cf0-4c9b-9670-703d9fe9b5bd)


### **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:

![image](media://a4c9b58a-857d-48ca-baa5-23fba7408c13)

### **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](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:

![image](media://55925c43-9882-46c1-a3b1-b07b7950fd50)

### **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](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:

![image](media://5a1ce53e-6468-45a9-afe5-009973c143a1)

### **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](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:

![image](media://5d5a048b-8bde-4fbb-a7a0-fccc92eee88c)

### **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](https://www.postman.com/) 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.