Willow API Reference (v2.0)

Download OpenAPI specification:Download

Welcome to the Willow API Reference documentation!

We are excited to see what you build with the Willow platform. Ensure you are looking at the correct version of the API documentation as we are always building and incrementing our APIs to provide more value for our customers.

You can find information about how to obtain your Access Token here.

View response samples in the right panel. Check back soon for request samples in your favorite programming language.

For more information about Willow products, visit our product page.

Authentication

Prerequisites

You first need to register your application in the Willow system. You can do so by sending a e-mail to developers@willowinc.com.

Coming Soon - You will be able to Sign Up to create a Developer Account and self-register your application.

Once your application is registered to use the Willow API, you will receive a Client ID and Client Secret that will allow you to request an access token. Review the Authentication Guide for more details.

OAuth2

Security Scheme Type: OAuth2
Flow type: clientCredentials
Token URL: https://api.willowinc.com/v2/oauth2/token

Pagination

In many of our endpoints, we support the Continuation Token method of pagination. When you make a request to an endpoint supporting continuation tokens, you will receive a continuation token string in the response body.

When making a new request for the next page of results, include the continuation token as a query parameter along with the desired page size.

Errors

The Willow API uses HTTP response status codes to indicate the success or otherwise of API requests. While not all codes listed below are used, some may be used in the future. Codes in the 2xx range indicate success, codes in the 4xx range indicate an error, and codes in the 5xx range indicate a server-side error. Note that 4xx and 5xx responses may be returned for any request and clients should cater for them.

Response
Code		 Description
200 Success -- The request was successful.
201 Created -- The resource was successfully created.
400 Bad Request -- General client error, possibly malformed data.
401 Unauthorized -- The API Key was not authorised (or no API Key was found).
402 Payment Required -- The API is not available on your current plan.
403 Forbidden -- The request is not allowed.
404 Not Found -- The resource was not found.
405 Method Not Allowed -- The resource does not accept the HTTP method.
406 Not Acceptable -- The resource cannot return the client's required content type.
408 Request Timeout -- The server would not wait any longer for the client.
409 Conflict - This request attempts to create a duplicate.
415 Unsupported Media Type - The server doesn't accept the submitted content-type.
422 Unprocessable Entity -- The data was well-formed but invalid.
429 Too Many Requests -- The client has reached or exceeded a rate limit, or the server is overloaded.
500, 502,
503, 504		 Server errors - something went wrong with Willow's servers.
These errors are most likely momentary operational errors, and requests should be retried once.

Rate Limiting

API Rate Limits are in place to protect Willow from API traffic spikes and flooding attacks that could put our platform at risk. We therefore measure the amount of requests sent to the API in order to throttle these when they surpass the amount allowed. Upon exceeding the threshold, we will respond with '429 Too Many Requests'.

Willow Rate Limits

X-RateLimit-Limit: 3600
X-RateLimit-Remaining: 3599
X-RateLimit-Reset: 1590793125

The default rate limit for the Willow API is 3,600 API calls per hour at this time. The following response headers are returned with each API call to help your app monitor its rate limiting status.

Header Description
X-RateLimit-Limit Maximum number of requests allowed for the app.
X-RateLimit-Remaining Number of requests left in the current time.
X-RateLimit-Reset The Unix Timestamp when the number of requests will be reset to the maximum limit.

Auth

Authentication is required prior to accessing the Willow API. Refer to Authentication section above for details.

Retrieve an access token

Request
Request Body schema:
clientId
string or null
clientSecret
string or null
Responses
200

Success

post/oauth2/token
Request samples
{
  • "clientId": "string",
  • "clientSecret": "string"
}
Response samples
application/json
{
  • "accessToken": "string",
  • "expiresIn": 0,
  • "tokenType": "string"
}

Sites

Sites are the root node for location objects in the digital twin. The term site is used to refer to buildings, venues, campuses, and other asset classes and geolocations. Because sites are a well understood locations, they are flexible in the exact type of structure or area in which they define. Floors are attached to Sites and can be retrieved by defining the siteId as a path parameter.

List sites

SecurityOAuth2
Responses
200

Success

401

Unauthorized

403

Forbidden

get/sites
Request samples 
Response samples 
application/json
[
  • {
    • "id": "1218614a-9822-43c5-94ca-1ecc29ab80b0",
    • "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
    • "name": "North America HQ",
    • "tzid": "Eastern Standard Time",
    • "location": {
      • "address": "575 5th Ave, 17th Floor",
      • "postCode": "10017",
      • "suburb": "New York",
      • "state": "New York",
      • "country": "United States"
      },
    • "regionId": "string"
    }
]
List floors
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
query Parameters
pageSize
integer or null <int32>   [ 0 .. 100 ] 
 Default:  100
Define the page size (number of elements to return).


 
continuationToken
string or null
String used for pagination. Submit the Continuation Token returned in the previous request to fetch the next page of results.


 
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/floors
Request samples 
Response samples 
application/json
[
  • {
    • "id": "b7d170fd-48fd-4392-a4e9-1ad5880edc62",
    • "name": "Level 10",
    • "code": "L010"
    }
]
Retrieve ADT Status for a Site
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/isadt
Request samples 
Response samples 
application/json
true
Assets
Assets are physical objects located at the site that have a commonly understood identity and value. The WillowTwin product suite refers to the collection of Assets at a site as the Asset Register. These may be Equipment objects such as Electrical Panelboards or Fire Pumps or static objects such as doors, windows, or workstations. Each asset is assigned to a Category such as HVAC - Air Side or Architectural to enable grouping of common pieces of equipment.
Each Asset also has a rich set of parameters, or properties. These parameters may be common across all assets, such as Specification Section, or unique to an Asset type such as VAV-Box Maximum Airflow Rating (CFM).


Retrieve an Asset
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
assetId
required
string <uuid> 
The unique ID of the asset which is given by Willow


 
 Example:  62b1928c-7331-02a3-bc74-3dba18ca91a2
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Not Found


get/sites/{siteId}/assets/{assetId}
Request samples 
Response samples 
application/json
{
  • "id": "62b1928c-7331-02a3-bc74-3dba18ca91a2",
  • "modelId": "dtmi:com:willowinc:FanPoweredBox;1",
  • "twinId": "WLW-NYC-575_5_AVE-FPB-17.02",
  • "name": "Variable Air Volume Box VAV-01.1",
  • "hasLiveData": true,
  • "categoryId": "00300000-0000-0000-0000-000000010976",
  • "categoryName": "Fan Powered Box",
  • "floorId": "b7d170fd-48fd-4392-a4e9-1ad5880edc62",
  • "identifier": "VAV-01.1",
  • "forgeViewerModelId": "b7d170fd-48fd-4392-a4e9-1ad5880edc62",
  • "tags": [
    • {
      • "name": "equip"
      },
    • {
      • "name": "hvac"
      },
    • {
      • "name": "fpb"
      },
    • {
      • "name": "coolOnly"
      }
    ],
  • "points": [
    • {
      • "id": "0fcd55ad-251d-4111-bed9-de32c7addb52",
      • "modelId": "dtmi:com:willowinc:TemperatureSensor;1",
      • "twinId": "WLW-NYC-575_5_AVE-FPB-17.02-ZAT",
      • "trendId": "0fcd55ad-251d-4111-bed9-de32c7addb52",
      • "externalId": "11011AI6",
      • "name": "Zone Temperature Sensor",
      • "description": "FPB 17.02 - Zone Temperature Sensor",
      • "tags": [
        • {
          • "name": "zone"
          },
        • {
          • "name": "air"
          },
        • {
          • "name": "temp",
          • "feature": "3d"
          },
        • {
          • "name": "sensor"
          }
        ],
      • "type": "analog",
      • "currentValue": {
        • "value": 22.5863236278265,
        • "unit": "degC"
        },
      • "displayPriority": 1,
      • "assets": [
        • {
          • "id": "12a81670-1b05-465f-940f-ec5371843e34",
          • "name": "FPB 17.02",
          • "categoryName": "Fan Powered Box"
          },
        • {
          • "id": "09ade39f-a69a-4d95-a8e0-dc28309874e4",
          • "name": "BACnet Controller 17.1",
          • "categoryName": "Controller"
          }
        ],
      • "trenedInterval": 1200,
      • "isEnabled": true,
      • "isDetected": true,
      • "deviceId": "19f770eb-b77f-4c35-b479-63d2c08f35b6",
      • "categoryName": "Temperature Sensor",
      • "properties": {
        • "property1": {
          • "displayName": "phenomenon",
          • "value": "Water",
          • "kind": "string"
          }
        },
      • "metadata": [
        • {
          • "key": "manufacturer",
          • "value": "omega",
          • "dataType": "string"
          }
        ]
      }
    ],
  • "parentId": "d27058e5-32cb-4411-992b-0804dbdb929d",
  • "assetParameters": [
    • {
      • "key": "assetType",
      • "displayName": "Asset Type",
      • "value": "Terminal Unit - VAV Box"
      },
    • {
      • "key": "specificationSection",
      • "displayName": "Specification Section",
      • "value": "23 36 00"
      },
    • {
      • "key": "roomNumber",
      • "displayName": "Room Number",
      • "value": "01-104"
      },
    • {
      • "key": "maxAirflowRating",
      • "displayName": "Maximum Airflow Rating (CFM)",
      • "value": 300
      }
    ]
}
List Asset Categories
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/categories
Request samples 
Response samples 
application/json
[
  • {
    • "id": "00300000-0000-0000-0000-000000010605",
    • "name": "Mechanical - Air Side",
    • "childCategories": [
      • [
        • {
          • "id": "00300000-0000-0000-0000-000000010976",
          • "name": "VAV Boxes",
          • "childCategories": [ ]
          },
        • {
          • "id": "00300000-0000-0000-0000-000000010979",
          • "name": "Fan Coil Units",
          • "childCategories": [ ]
          },
        • {
          • "id": "00300000-0000-0000-0000-000000010980",
          • "name": "Dampers",
          • "childCategories": [ ]
          }
        ]
      ]
    }
]
List Assets
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
categoryId
required
string <uuid> 
The unique ID of the asset category which is given by Willow


 
 Example:  00300000-0000-0000-0000-000000010605
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Not Found


get/sites/{siteId}/categories/{categoryId}/assets
Request samples 
Response samples 
application/json
[
  • {
    • "id": "62b1928c-7331-02a3-bc74-3dba18ca91a2",
    • "modelId": "dtmi:com:willowinc:FanPoweredBox;1",
    • "twinId": "WLW-NYC-575_5_AVE-FPB-17.02",
    • "name": "Variable Air Volume Box VAV-01.1",
    • "hasLiveData": true,
    • "categoryId": "00300000-0000-0000-0000-000000010976",
    • "categoryName": "Fan Powered Box",
    • "floorId": "b7d170fd-48fd-4392-a4e9-1ad5880edc62",
    • "identifier": "VAV-01.1",
    • "forgeViewerModelId": "b7d170fd-48fd-4392-a4e9-1ad5880edc62",
    • "tags": [
      • {
        • "name": "equip"
        },
      • {
        • "name": "hvac"
        },
      • {
        • "name": "fpb"
        },
      • {
        • "name": "coolOnly"
        }
      ],
    • "points": [
      • {
        • "id": "0fcd55ad-251d-4111-bed9-de32c7addb52",
        • "modelId": "dtmi:com:willowinc:TemperatureSensor;1",
        • "twinId": "WLW-NYC-575_5_AVE-FPB-17.02-ZAT",
        • "trendId": "0fcd55ad-251d-4111-bed9-de32c7addb52",
        • "externalId": "11011AI6",
        • "name": "Zone Temperature Sensor",
        • "description": "FPB 17.02 - Zone Temperature Sensor",
        • "tags": [
          • {
            • "name": "zone"
            },
          • {
            • "name": "air"
            },
          • {
            • "name": "temp",
            • "feature": "3d"
            },
          • {
            • "name": "sensor"
            }
          ],
        • "type": "analog",
        • "currentValue": {
          • "value": 22.5863236278265,
          • "unit": "degC"
          },
        • "displayPriority": 1,
        • "assets": [
          • {
            • "id": "12a81670-1b05-465f-940f-ec5371843e34",
            • "name": "FPB 17.02",
            • "categoryName": "Fan Powered Box"
            },
          • {
            • "id": "09ade39f-a69a-4d95-a8e0-dc28309874e4",
            • "name": "BACnet Controller 17.1",
            • "categoryName": "Controller"
            }
          ],
        • "trenedInterval": 1200,
        • "isEnabled": true,
        • "isDetected": true,
        • "deviceId": "19f770eb-b77f-4c35-b479-63d2c08f35b6",
        • "categoryName": "Temperature Sensor",
        • "properties": {
          • "property1": {
            • "displayName": "phenomenon",
            • "value": "Water",
            • "kind": "string"
            }
          },
        • "metadata": [
          • {
            • "key": "manufacturer",
            • "value": "omega",
            • "dataType": "string"
            }
          ]
        }
      ],
    • "parentId": "d27058e5-32cb-4411-992b-0804dbdb929d",
    • "assetParameters": [
      • {
        • "key": "assetType",
        • "displayName": "Asset Type",
        • "value": "Terminal Unit - VAV Box"
        },
      • {
        • "key": "specificationSection",
        • "displayName": "Specification Section",
        • "value": "23 36 00"
        },
      • {
        • "key": "roomNumber",
        • "displayName": "Room Number",
        • "value": "01-104"
        },
      • {
        • "key": "maxAirflowRating",
        • "displayName": "Maximum Airflow Rating (CFM)",
        • "value": 300
        }
      ]
    }
]
Equipment
Equipment is the root node for asset objects in the digital twin. Equipment are physical objects that may optionally have associated Devices, Points, and Live Data. Equipment is associated to a location in the digital twin as well as a parent which enables a user to understand location context as well as system relationships between equipment. The Equipment Object is categorized with a discipline such as HVAC or Electrical to enable grouping of common pieces of equipment.
The digital twin also has tags associated with each Equipment to provide metadata about the object. These tags follow the guidance of Project Haystack but can be customized for each Customer and Site. Tags are strings that can be grouped together into arrays and applied to Equipment to provide metadata about the type, function, or purpose. These arrays are often referred to as Tagsets and are a means of providing standard context about an entity.


List equipment
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
query Parameters
pageSize
integer or null <int32>   [ 0 .. 100 ] 
 Default:  100
Define the page size (number of elements to return).


 
pageStart
integer or null <int32> 
 Default:  0
Index of the page.


 
categoryId
string or null <uuid> 
The unique ID of the category given by Willow which the asset belongs to


 
 Example:  categoryId=00300000-0000-0000-0000-000000010976
floorId
string or null <uuid> 
The unique ID of the floor which is given by Willow


 
 Example:  floorId=b7d170fd-48fd-4392-a4e9-1ad5880edc62
liveDataOnly
boolean or null
 Default:  false
Filter response to only return twins that have live data points associated


 
 Example:  liveDataOnly=true
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Not Found


get/sites/{siteId}/equipment
Request samples 
Response samples 
application/json
{
  • "continuationToken": "string",
  • "data": [
    • {
      • "id": "62b1928c-7331-02a3-bc74-3dba18ca91a2",
      • "modelId": "dtmi:com:willowinc:FanPoweredBox;1",
      • "twinId": "WLW-NYC-575_5_AVE-FPB-17.02",
      • "name": "Variable Air Volume Box VAV-01.1",
      • "hasLiveData": true,
      • "categoryId": "00300000-0000-0000-0000-000000010976",
      • "categoryName": "Fan Powered Box",
      • "floorId": "b7d170fd-48fd-4392-a4e9-1ad5880edc62",
      • "identifier": "VAV-01.1",
      • "forgeViewerModelId": "b7d170fd-48fd-4392-a4e9-1ad5880edc62",
      • "tags": [
        • {
          • "name": "equip"
          },
        • {
          • "name": "hvac"
          },
        • {
          • "name": "fpb"
          },
        • {
          • "name": "coolOnly"
          }
        ],
      • "points": [
        • {
          • "id": "0fcd55ad-251d-4111-bed9-de32c7addb52",
          • "modelId": "dtmi:com:willowinc:TemperatureSensor;1",
          • "twinId": "WLW-NYC-575_5_AVE-FPB-17.02-ZAT",
          • "trendId": "0fcd55ad-251d-4111-bed9-de32c7addb52",
          • "externalId": "11011AI6",
          • "name": "Zone Temperature Sensor",
          • "description": "FPB 17.02 - Zone Temperature Sensor",
          • "tags": [
            • {
              • "name": "zone"
              },
            • {
              • "name": "air"
              },
            • {
              • "name": "temp",
              • "feature": "3d"
              },
            • {
              • "name": "sensor"
              }
            ],
          • "type": "analog",
          • "currentValue": {
            • "value": 22.5863236278265,
            • "unit": "degC"
            },
          • "displayPriority": 1,
          • "assets": [
            • {
              • "id": "12a81670-1b05-465f-940f-ec5371843e34",
              • "name": "FPB 17.02",
              • "categoryName": "Fan Powered Box"
              },
            • {
              • "id": "09ade39f-a69a-4d95-a8e0-dc28309874e4",
              • "name": "BACnet Controller 17.1",
              • "categoryName": "Controller"
              }
            ],
          • "trenedInterval": 1200,
          • "isEnabled": true,
          • "isDetected": true,
          • "deviceId": "19f770eb-b77f-4c35-b479-63d2c08f35b6",
          • "categoryName": "Temperature Sensor",
          • "properties": {
            • "property1": {
              • "displayName": "phenomenon",
              • "value": "Water",
              • "kind": "string"
              }
            },
          • "metadata": [
            • {
              • "key": "manufacturer",
              • "value": "omega",
              • "dataType": "string"
              }
            ]
          }
        ],
      • "parentId": "d27058e5-32cb-4411-992b-0804dbdb929d",
      • "assetParameters": [
        • {
          • "key": "assetType",
          • "displayName": "Asset Type",
          • "value": "Terminal Unit - VAV Box"
          },
        • {
          • "key": "specificationSection",
          • "displayName": "Specification Section",
          • "value": "23 36 00"
          },
        • {
          • "key": "roomNumber",
          • "displayName": "Room Number",
          • "value": "01-104"
          },
        • {
          • "key": "maxAirflowRating",
          • "displayName": "Maximum Airflow Rating (CFM)",
          • "value": 300
          }
        ]
      }
    ]
}
List equipment
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
query Parameters
pageSize
integer or null <int32>   [ 0 .. 100 ] 
 Default:  100
Define the page size (number of elements to return).


 
continuationToken
string or null
String used for pagination. Submit the Continuation Token returned in the previous request to fetch the next page of results.


 
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Not Found


get/sites/{siteId}/equipments
Request samples 
Response samples 
application/json
{
  • "continuationToken": "string",
  • "data": [
    • {
      • "id": "62b1928c-7331-02a3-bc74-3dba18ca91a2",
      • "modelId": "dtmi:com:willowinc:FanPoweredBox;1",
      • "twinId": "WLW-NYC-575_5_AVE-FPB-17.02",
      • "name": "Variable Air Volume Box VAV-01.1",
      • "hasLiveData": true,
      • "categoryId": "00300000-0000-0000-0000-000000010976",
      • "categoryName": "Fan Powered Box",
      • "floorId": "b7d170fd-48fd-4392-a4e9-1ad5880edc62",
      • "identifier": "VAV-01.1",
      • "forgeViewerModelId": "b7d170fd-48fd-4392-a4e9-1ad5880edc62",
      • "tags": [
        • {
          • "name": "equip"
          },
        • {
          • "name": "hvac"
          },
        • {
          • "name": "fpb"
          },
        • {
          • "name": "coolOnly"
          }
        ],
      • "points": [
        • {
          • "id": "0fcd55ad-251d-4111-bed9-de32c7addb52",
          • "modelId": "dtmi:com:willowinc:TemperatureSensor;1",
          • "twinId": "WLW-NYC-575_5_AVE-FPB-17.02-ZAT",
          • "trendId": "0fcd55ad-251d-4111-bed9-de32c7addb52",
          • "externalId": "11011AI6",
          • "name": "Zone Temperature Sensor",
          • "description": "FPB 17.02 - Zone Temperature Sensor",
          • "tags": [
            • {
              • "name": "zone"
              },
            • {
              • "name": "air"
              },
            • {
              • "name": "temp",
              • "feature": "3d"
              },
            • {
              • "name": "sensor"
              }
            ],
          • "type": "analog",
          • "currentValue": {
            • "value": 22.5863236278265,
            • "unit": "degC"
            },
          • "displayPriority": 1,
          • "assets": [
            • {
              • "id": "12a81670-1b05-465f-940f-ec5371843e34",
              • "name": "FPB 17.02",
              • "categoryName": "Fan Powered Box"
              },
            • {
              • "id": "09ade39f-a69a-4d95-a8e0-dc28309874e4",
              • "name": "BACnet Controller 17.1",
              • "categoryName": "Controller"
              }
            ],
          • "trenedInterval": 1200,
          • "isEnabled": true,
          • "isDetected": true,
          • "deviceId": "19f770eb-b77f-4c35-b479-63d2c08f35b6",
          • "categoryName": "Temperature Sensor",
          • "properties": {
            • "property1": {
              • "displayName": "phenomenon",
              • "value": "Water",
              • "kind": "string"
              }
            },
          • "metadata": [
            • {
              • "key": "manufacturer",
              • "value": "omega",
              • "dataType": "string"
              }
            ]
          }
        ],
      • "parentId": "d27058e5-32cb-4411-992b-0804dbdb929d",
      • "assetParameters": [
        • {
          • "key": "assetType",
          • "displayName": "Asset Type",
          • "value": "Terminal Unit - VAV Box"
          },
        • {
          • "key": "specificationSection",
          • "displayName": "Specification Section",
          • "value": "23 36 00"
          },
        • {
          • "key": "roomNumber",
          • "displayName": "Room Number",
          • "value": "01-104"
          },
        • {
          • "key": "maxAirflowRating",
          • "displayName": "Maximum Airflow Rating (CFM)",
          • "value": 300
          }
        ]
      }
    ]
}
Devices
Devices are controller objects that have inputs and outputs that correspond to Point objects receiving and transmitting Live Data. We adopt the use of Devices to follow BACnet terminology. These controllers are often associated with a single Equipment object but may have Point objects that span across multiple pieces of Equipment.


List devices
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
query Parameters
pageSize
integer or null <int32>   [ 0 .. 100 ] 
 Default:  100
Define the page size (number of elements to return).


 
continuationToken
string or null
String used for pagination. Submit the Continuation Token returned in the previous request to fetch the next page of results.


 
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/devices
Request samples 
Response samples 
application/json
{
  • "continuationToken": "string",
  • "data": [
    • {
      • "id": "19f770eb-b77f-4c35-b479-63d2c08f35b6",
      • "modelId": "dtmi:com:willowinc:Controller;1",
      • "twinId": "WLW-NYC-575_5_AVE-FPB-17.02",
      • "registrationId": "string",
      • "registrationKey": "string",
      • "isEnabled": true,
      • "isDetected": true,
      • "connectorId": "string",
      • "points": [
        • {
          • "id": "0fcd55ad-251d-4111-bed9-de32c7addb52",
          • "modelId": "dtmi:com:willowinc:TemperatureSensor;1",
          • "twinId": "WLW-NYC-575_5_AVE-FPB-17.02-ZAT",
          • "trendId": "0fcd55ad-251d-4111-bed9-de32c7addb52",
          • "externalId": "11011AI6",
          • "name": "Zone Temperature Sensor",
          • "description": "FPB 17.02 - Zone Temperature Sensor",
          • "tags": [
            • {
              • "name": "zone"
              },
            • {
              • "name": "air"
              },
            • {
              • "name": "temp",
              • "feature": "3d"
              },
            • {
              • "name": "sensor"
              }
            ],
          • "type": "analog",
          • "currentValue": {
            • "value": 22.5863236278265,
            • "unit": "degC"
            },
          • "displayPriority": 1,
          • "assets": [
            • {
              • "id": "12a81670-1b05-465f-940f-ec5371843e34",
              • "name": "FPB 17.02",
              • "categoryName": "Fan Powered Box"
              },
            • {
              • "id": "09ade39f-a69a-4d95-a8e0-dc28309874e4",
              • "name": "BACnet Controller 17.1",
              • "categoryName": "Controller"
              }
            ],
          • "trenedInterval": 1200,
          • "isEnabled": true,
          • "isDetected": true,
          • "deviceId": "19f770eb-b77f-4c35-b479-63d2c08f35b6",
          • "categoryName": "Temperature Sensor",
          • "properties": {
            • "property1": {
              • "displayName": "phenomenon",
              • "value": "Water",
              • "kind": "string"
              }
            },
          • "metadata": [
            • {
              • "key": "manufacturer",
              • "value": "omega",
              • "dataType": "string"
              }
            ]
          }
        ]
      }
    ]
}
Points
Points can be treated as leaf nodes for asset objects in the digital twin. They are children to both Equipment and Devices and correspond to Live Data that is often being received of transmitted from a device.
Similar to Equipment, tags are associated with each Point to provide metadata about the object. These tags also follow the guidance of Project Haystack and can be customized for each Customer and Site. Tags are strings that can be grouped together into arrays and applied to Points to provide metadata about the type, function, or purpose. These arrays are often referred to as Tagsets and are a means of providing standard context about an entity.


List points
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
query Parameters
pageSize
integer or null <int32>   [ 0 .. 100 ] 
 Default:  100
Define the page size (number of elements to return).


 
pageStart
integer or null <int32> 
 Default:  0
Index of the page.


 
equipmentId
string or null <uuid> 
The unique ID of the equipment which is given by Willow


 
 Example:  equipmentId=6be53768-811e-4db8-baee-471a01498df7
includeAssets
boolean or null
 Default:  false
Whether the response should include the asset object


 
 Example:  includeAssets=true
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/points
Request samples 
Response samples 
application/json
[
  • {
    • "id": "0fcd55ad-251d-4111-bed9-de32c7addb52",
    • "modelId": "dtmi:com:willowinc:TemperatureSensor;1",
    • "twinId": "WLW-NYC-575_5_AVE-FPB-17.02-ZAT",
    • "trendId": "0fcd55ad-251d-4111-bed9-de32c7addb52",
    • "externalId": "11011AI6",
    • "name": "Zone Temperature Sensor",
    • "description": "FPB 17.02 - Zone Temperature Sensor",
    • "tags": [
      • {
        • "name": "zone"
        },
      • {
        • "name": "air"
        },
      • {
        • "name": "temp",
        • "feature": "3d"
        },
      • {
        • "name": "sensor"
        }
      ],
    • "type": "analog",
    • "currentValue": {
      • "value": 22.5863236278265,
      • "unit": "degC"
      },
    • "displayPriority": 1,
    • "assets": [
      • {
        • "id": "12a81670-1b05-465f-940f-ec5371843e34",
        • "name": "FPB 17.02",
        • "categoryName": "Fan Powered Box"
        },
      • {
        • "id": "09ade39f-a69a-4d95-a8e0-dc28309874e4",
        • "name": "BACnet Controller 17.1",
        • "categoryName": "Controller"
        }
      ],
    • "trenedInterval": 1200,
    • "isEnabled": true,
    • "isDetected": true,
    • "deviceId": "19f770eb-b77f-4c35-b479-63d2c08f35b6",
    • "categoryName": "Temperature Sensor",
    • "properties": {
      • "property1": {
        • "displayName": "phenomenon",
        • "value": "Water",
        • "kind": "string"
        }
      },
    • "metadata": [
      • {
        • "key": "manufacturer",
        • "value": "omega",
        • "dataType": "string"
        }
      ]
    }
]
Retrieve a point
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
id
required
string <uuid> 
The unique ID of the resource


 
 Example:  WLW-NYC-575_5_AVE-FPB-17.02
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Not Found


get/sites/{siteId}/points/{id}
Request samples 
Response samples 
application/json
{
  • "id": "0fcd55ad-251d-4111-bed9-de32c7addb52",
  • "modelId": "dtmi:com:willowinc:TemperatureSensor;1",
  • "twinId": "WLW-NYC-575_5_AVE-FPB-17.02-ZAT",
  • "trendId": "0fcd55ad-251d-4111-bed9-de32c7addb52",
  • "externalId": "11011AI6",
  • "name": "Zone Temperature Sensor",
  • "description": "FPB 17.02 - Zone Temperature Sensor",
  • "tags": [
    • {
      • "name": "zone"
      },
    • {
      • "name": "air"
      },
    • {
      • "name": "temp",
      • "feature": "3d"
      },
    • {
      • "name": "sensor"
      }
    ],
  • "type": "analog",
  • "currentValue": {
    • "value": 22.5863236278265,
    • "unit": "degC"
    },
  • "displayPriority": 1,
  • "assets": [
    • {
      • "id": "12a81670-1b05-465f-940f-ec5371843e34",
      • "name": "FPB 17.02",
      • "categoryName": "Fan Powered Box"
      },
    • {
      • "id": "09ade39f-a69a-4d95-a8e0-dc28309874e4",
      • "name": "BACnet Controller 17.1",
      • "categoryName": "Controller"
      }
    ],
  • "trenedInterval": 1200,
  • "isEnabled": true,
  • "isDetected": true,
  • "deviceId": "19f770eb-b77f-4c35-b479-63d2c08f35b6",
  • "categoryName": "Temperature Sensor",
  • "properties": {
    • "property1": {
      • "displayName": "phenomenon",
      • "value": "Water",
      • "kind": "string"
      }
    },
  • "metadata": [
    • {
      • "key": "manufacturer",
      • "value": "omega",
      • "dataType": "string"
      }
    ]
}
Telemetry
Telemetry data to be ingested by the Willow API.


Add telemetry
This endpoint allows for telemetry to be sent to Willow for ingestion.


SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Request Body schema: 
Array of objects (Telemetry) 
 
skipExceptions
boolean
When posting multiple live data objects, this boolean property defines the WillowTwin response behavior upon encountering an error.


 
Responses 
202
Success


400
Bad request (Invalid payload data)


401
Unauthorized


403
Forbidden


500
Internal server error


post/sites/{siteId}/livedata/telemetry
Request samples 
{
  • "telemetry": [
    • {
      • "entityId": "0fcd55ad-251d-4111-bed9-de32c7addb52",
      • "entityIdentificationType": "trendId",
      • "value": 22.5863236278265,
      • "timestamp": "2022-01-01T16:48:20.773Z",
      • "properties": {
        • "additionalProp1": "test1",
        • "additionalProp2": 123
        },
      • "latitude": 0,
      • "longitude": 0,
      • "altitude": 0
      }
    ],
  • "skipExceptions": true
}
Response samples 
application/json
{
  • "successes": [
    • {
      • "entityId": "0fcd55ad-251d-4111-bed9-de32c7addb52",
      • "entityIdentificationType": "trendId",
      • "value": 22.5863236278265,
      • "timestamp": "2022-01-01T16:48:20.773Z",
      • "properties": {
        • "additionalProp1": "test1",
        • "additionalProp2": 123
        },
      • "latitude": 0,
      • "longitude": 0,
      • "altitude": 0
      }
    ],
  • "failures": [
    • {
      • "telemetry": {
        • "entityId": "0fcd55ad-251d-4111-bed9-de32c7addb52",
        • "entityIdentificationType": "trendId",
        • "value": 22.5863236278265,
        • "timestamp": "2022-01-01T16:48:20.773Z",
        • "properties": {
          • "additionalProp1": "test1",
          • "additionalProp2": 123
          },
        • "latitude": 0,
        • "longitude": 0,
        • "altitude": 0
        },
      • "errorMessage": "Point id not found",
      • "errorCode": 404
      }
    ]
}
Live Data
Live Data generated by Points and stored in the digital twin and always associated with a timestamp value. The Willow API has the ability to read current values as well as a historical trend via the Trend Logs endpoint.


Add live data
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Request Body schema: 
Array of objects or null (PointLiveData) 
 
skipExceptions
boolean or null
When posting multiple live data objects, this boolean property defines the WillowTwin response behavior upon encountering an error.


 
Responses 
200
Success


401
Unauthorized


403
Forbidden


post/sites/{siteId}/livedata
Request samples 
{
  • "points": [
    • {
      • "pointId": "0fcd55ad-251d-4111-bed9-de32c7addb52",
      • "timestamp": "2020-05-27T16:48:20.773Z",
      • "value": 22.5863236278265
      }
    ],
  • "skipExceptions": true
}
Response samples 
application/json
{
  • "failures": [
    • {
      • "pointId": "0fcd55ad-251d-4111-bed9-de32c7addb52",
      • "errorMessage": "Point id not found",
      • "errorCode": 404
      }
    ]
}
List time series
This endpoint returns the time series data for point(s) in an aggregated response according to the defined granularity. The following
table shows the default and recommended granularity parameter for a give date range:






Range of Days
Default
Granularity		
Granularity
Recommendations		
Granularity
Recommendations (ISO 8601)		





<= 1
5 minutes
5 minutes
10 minutes
15 minutes
30 minutes		
PT5M
PT10M
PT15M
PT30M		




<= 3
5 minutes
5 minutes
10 minutes
15 minutes
30 minutes
1 hour		
PT5M
PT10M
PT15M
PT30M
PT1H		




<=7
10 minutes
10 minutes
15 minutes
30 minutes
1 hour
2 hours
4 hours
12 hours
1 day		
PT10M
PT15M
PT30M
PT1H
PT2H
PT4H
PT12H
P1D		




<= 11
15 minutes
15 minutes
30 minutes
1 hour
2 hours
4 hours
12 hours
1 day		
PT15M
PT30M
PT1H
PT2H
PT4H
PT12H
P1D		




<= 35
30 minutes
30 minutes
1 hour
2 hours
4 hours
12 hours
1 day		
PT30M
PT1H
PT2H
PT4H
PT12H
P1D		




<= 49
1 hour
1 hour
2 hours
4 hours
12 hours
1 day
1 week		
PT1H
PT2H
PT4H
PT12H
P1D
P1W		




<= 91
2 hours
2 hours
4 hours
12 hours
1 day
1 week		
PT2H
PT4H
PT12H
P1D
P1W		




<= 182
4 hours
4 hours
12 hours
1 day
1 week
1 month		
PT4H
PT12H
P1D
P1W
P1M		




<= 371
12 hours
12 hours
1 day
1 week
1 month		
PT12H
P1D
P1W
P1M		





While this endpoint will accept additional granularity options, the above are recommended for the best performance.


SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
query Parameters
pointIds
Array of strings or null <uuid> 
Array of unique point IDs given by Willow


 
 Example:  pointIds=pointIds=0fcd55ad-251d-4111-bed9-de32c7addb52&pointIds=7461183c-139f-4e60-95ba-6a6b3d3f9321
startDate
required
string or null <date-time> 
Start date and time of specific results desired in ISO 8601 format


 
 Example:  startDate=2020-05-23T22:12:21.047Z
endDate
required
string or null <date-time> 
End date and time of specific results desired in ISO 8601 format


 
 Example:  endDate=2020-05-30T22:12:21.047Z
granularity
string or null <ISO8601> 
Interval at which the time series values should be aggregated, aligned, and returned in ISO 8601 format


 
 Example:  granularity=P0DT1H
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/timemachine
Request samples 
Response samples 
application/json
[
  • {
    • "pointId": "0fcd55ad-251d-4111-bed9-de32c7addb52",
    • "name": "zone air temp sensor",
    • "type": "analog",
    • "unit": "degC",
    • "data": [
      • {
        • "timestamp": "2020-05-27T16:00:00.000Z",
        • "average": "22.5",
        • "minimum": "18.9",
        • "maximum": "26.8",
        • "sum": "120.8",
        • "onCount": "5",
        • "offCount": "4"
        },
      • {
        • "timestamp": "2020-05-27T17:00:00.000Z",
        • "average": "24.1",
        • "minimum": "20.7",
        • "maximum": "25.9",
        • "sum": "110.4",
        • "onCount": "3",
        • "offCount": "6"
        }
      ]
    }
]
Trend Logs
Trend logs return an array of timestamped Point values. Because Live Data is often captured at intervals on the order of minutes, this endpoint can return a large amount of data with a single API call. Therefore, we recommend leveraging the query parameters to return a specific Point and interval by specifying the desired startDate and endDate.


Retrieve a point trend log
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
pointId
required
string <uuid> 
The unique ID of the point which is given by Willow


 
 Example:  0fcd55ad-251d-4111-bed9-de32c7addb52
query Parameters
startDate
string or null <date-time> 
Start date and time of specific results desired in ISO 8601 format


 
 Example:  startDate=2020-05-23T22:12:21.047Z
endDate
string or null <date-time> 
End date and time of specific results desired in ISO 8601 format


 
 Example:  endDate=2020-05-30T22:12:21.047Z
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Not Found


get/sites/{siteId}/points/{pointId}/trendlog
Request samples 
Response samples 
application/json
{
  • "continuationToken": "string",
  • "point": {
    • "id": "0fcd55ad-251d-4111-bed9-de32c7addb52",
    • "modelId": "dtmi:com:willowinc:TemperatureSensor;1",
    • "twinId": "WLW-NYC-575_5_AVE-FPB-17.02-ZAT",
    • "trendId": "0fcd55ad-251d-4111-bed9-de32c7addb52",
    • "externalId": "11011AI6",
    • "name": "Zone Temperature Sensor",
    • "description": "FPB 17.02 - Zone Temperature Sensor",
    • "tags": [
      • {
        • "name": "zone"
        },
      • {
        • "name": "air"
        },
      • {
        • "name": "temp",
        • "feature": "3d"
        },
      • {
        • "name": "sensor"
        }
      ],
    • "type": "analog",
    • "currentValue": {
      • "value": 22.5863236278265,
      • "unit": "degC"
      },
    • "displayPriority": 1,
    • "assets": [
      • {
        • "id": "12a81670-1b05-465f-940f-ec5371843e34",
        • "name": "FPB 17.02",
        • "categoryName": "Fan Powered Box"
        },
      • {
        • "id": "09ade39f-a69a-4d95-a8e0-dc28309874e4",
        • "name": "BACnet Controller 17.1",
        • "categoryName": "Controller"
        }
      ],
    • "trenedInterval": 1200,
    • "isEnabled": true,
    • "isDetected": true,
    • "deviceId": "19f770eb-b77f-4c35-b479-63d2c08f35b6",
    • "categoryName": "Temperature Sensor",
    • "properties": {
      • "property1": {
        • "displayName": "phenomenon",
        • "value": "Water",
        • "kind": "string"
        }
      },
    • "metadata": [
      • {
        • "key": "manufacturer",
        • "value": "omega",
        • "dataType": "string"
        }
      ]
    },
  • "data": [
    • {
      • "timestamp": "2019-08-24T14:15:22Z",
      • "value": "string"
      }
    ]
}
Create point trend logsDeprecated
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
query Parameters
startDate
string or null <date-time> 
Start date and time of specific results desired in ISO 8601 format


 
 Example:  startDate=2020-05-23T22:12:21.047Z
endDate
string or null <date-time> 
End date and time of specific results desired in ISO 8601 format


 
 Example:  endDate=2020-05-30T22:12:21.047Z
Request Body schema: 
 Array 
string <uuid> 
 
Responses 
200
Success


401
Unauthorized


403
Forbidden


post/sites/{siteId}/trendlogs
Request samples 
[
  • "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
Response samples 
application/json
[
  • {
    • "continuationToken": "string",
    • "point": {
      • "id": "0fcd55ad-251d-4111-bed9-de32c7addb52",
      • "modelId": "dtmi:com:willowinc:TemperatureSensor;1",
      • "twinId": "WLW-NYC-575_5_AVE-FPB-17.02-ZAT",
      • "trendId": "0fcd55ad-251d-4111-bed9-de32c7addb52",
      • "externalId": "11011AI6",
      • "name": "Zone Temperature Sensor",
      • "description": "FPB 17.02 - Zone Temperature Sensor",
      • "tags": [
        • {
          • "name": "zone"
          },
        • {
          • "name": "air"
          },
        • {
          • "name": "temp",
          • "feature": "3d"
          },
        • {
          • "name": "sensor"
          }
        ],
      • "type": "analog",
      • "currentValue": {
        • "value": 22.5863236278265,
        • "unit": "degC"
        },
      • "displayPriority": 1,
      • "assets": [
        • {
          • "id": "12a81670-1b05-465f-940f-ec5371843e34",
          • "name": "FPB 17.02",
          • "categoryName": "Fan Powered Box"
          },
        • {
          • "id": "09ade39f-a69a-4d95-a8e0-dc28309874e4",
          • "name": "BACnet Controller 17.1",
          • "categoryName": "Controller"
          }
        ],
      • "trenedInterval": 1200,
      • "isEnabled": true,
      • "isDetected": true,
      • "deviceId": "19f770eb-b77f-4c35-b479-63d2c08f35b6",
      • "categoryName": "Temperature Sensor",
      • "properties": {
        • "property1": {
          • "displayName": "phenomenon",
          • "value": "Water",
          • "kind": "string"
          }
        },
      • "metadata": [
        • {
          • "key": "manufacturer",
          • "value": "omega",
          • "dataType": "string"
          }
        ]
      },
    • "data": [
      • {
        • "timestamp": "2019-08-24T14:15:22Z",
        • "value": "string"
        }
      ]
    }
]
List point trend logs
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
query Parameters
pointIds
Array of strings or null <uuid> 
Array of unique point IDs given by Willow


 
 Example:  pointIds=pointIds=0fcd55ad-251d-4111-bed9-de32c7addb52&pointIds=7461183c-139f-4e60-95ba-6a6b3d3f9321
startDate
string or null <date-time> 
Start date and time of specific results desired in ISO 8601 format


 
 Example:  startDate=2020-05-23T22:12:21.047Z
endDate
string or null <date-time> 
End date and time of specific results desired in ISO 8601 format


 
 Example:  endDate=2020-05-30T22:12:21.047Z
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/trendlogs
Request samples 
Response samples 
application/json
[
  • {
    • "continuationToken": "string",
    • "point": {
      • "id": "0fcd55ad-251d-4111-bed9-de32c7addb52",
      • "modelId": "dtmi:com:willowinc:TemperatureSensor;1",
      • "twinId": "WLW-NYC-575_5_AVE-FPB-17.02-ZAT",
      • "trendId": "0fcd55ad-251d-4111-bed9-de32c7addb52",
      • "externalId": "11011AI6",
      • "name": "Zone Temperature Sensor",
      • "description": "FPB 17.02 - Zone Temperature Sensor",
      • "tags": [
        • {
          • "name": "zone"
          },
        • {
          • "name": "air"
          },
        • {
          • "name": "temp",
          • "feature": "3d"
          },
        • {
          • "name": "sensor"
          }
        ],
      • "type": "analog",
      • "currentValue": {
        • "value": 22.5863236278265,
        • "unit": "degC"
        },
      • "displayPriority": 1,
      • "assets": [
        • {
          • "id": "12a81670-1b05-465f-940f-ec5371843e34",
          • "name": "FPB 17.02",
          • "categoryName": "Fan Powered Box"
          },
        • {
          • "id": "09ade39f-a69a-4d95-a8e0-dc28309874e4",
          • "name": "BACnet Controller 17.1",
          • "categoryName": "Controller"
          }
        ],
      • "trenedInterval": 1200,
      • "isEnabled": true,
      • "isDetected": true,
      • "deviceId": "19f770eb-b77f-4c35-b479-63d2c08f35b6",
      • "categoryName": "Temperature Sensor",
      • "properties": {
        • "property1": {
          • "displayName": "phenomenon",
          • "value": "Water",
          • "kind": "string"
          }
        },
      • "metadata": [
        • {
          • "key": "manufacturer",
          • "value": "omega",
          • "dataType": "string"
          }
        ]
      },
    • "data": [
      • {
        • "timestamp": "2019-08-24T14:15:22Z",
        • "value": "string"
        }
      ]
    }
]
Insights
Insights are often referred to as faults or notifications and are generated within the digital twin based on rules and analytics that trigger from Live and Trended data. Likewise, Insights that are generated outside the Willow platform can be created using this endpoint.


List insights
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/insights
Request samples 
Response samples 
application/json
[
  • {
    • "id": "8cf1743b-fcb7-44c8-9b6d-0038323ba9e5",
    • "sequenceNumber": "av-I-465",
    • "floorCode": "L010",
    • "equipmentId": "6be53768-811e-4db8-baee-471a01498df7",
    • "type": "faultDetection",
    • "name": "258adba7",
    • "priority": 3,
    • "status": "inProgress",
    • "state": "active",
    • "occurredDate": "2020-05-28T00:33:02.836Z",
    • "updatedDate": "2020-08-28T13:46:01.919Z",
    • "externalId": "20200428_d4b43edf",
    • "externalStatus": "active",
    • "externalMetadata": "string"
    }
]
Create an insight
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Request Body schema: 
floorCode
string or null
The floor code for the location where the insight is referencing


 
equipmentId
string or null <uuid> 
The ID of the equipment the insight is referencing


 
type
string (InsightType) 
The insight type


 Enum: "faultDetection" "energy" "alert" "note" "goldenStandard" "infrastructure" "integrityKpi" "energyKpi" "edgeDevice"  
name
string or null
The name of the insight


 
description
string or null
 
priority
integer <int32> 
The code for the priority level. Urgent=1, High=2, Medium=3, Low=4


 
state
string (InsightState) 
The state of the insight


 Enum: "inactive" "active" "archived"  
occurredDate
string <date-time> 
 
detectedDate
string <date-time> 
 
externalId
string or null
 
externalStatus
string or null
 
externalMetadata
string or null
 
Responses 
201
Created


401
Unauthorized


403
Forbidden


post/sites/{siteId}/insights
Request samples 
{
  • "floorCode": "L010",
  • "equipmentId": "6be53768-811e-4db8-baee-471a01498df7",
  • "type": "faultDetection",
  • "name": "258adba7",
  • "description": "Chilled Water Pump CWP-01.1 is running when Chiller CH-01 is off.",
  • "priority": 3,
  • "state": "active",
  • "occurredDate": "2020-05-28T00:33:02.836Z",
  • "detectedDate": "2020-05-28T01:02:02.836Z",
  • "externalId": "20200428_d4b43edf",
  • "externalStatus": "active",
  • "externalMetadata": "string"
}
Response samples 
application/json
{
  • "id": "8cf1743b-fcb7-44c8-9b6d-0038323ba9e5",
  • "sequenceNumber": "av-I-465",
  • "floorCode": "L010",
  • "equipmentId": "6be53768-811e-4db8-baee-471a01498df7",
  • "type": "faultDetection",
  • "name": "258adba7",
  • "priority": 3,
  • "status": "inProgress",
  • "state": "active",
  • "occurredDate": "2020-05-28T00:33:02.836Z",
  • "updatedDate": "2020-08-28T13:46:01.919Z",
  • "externalId": "20200428_d4b43edf",
  • "externalStatus": "active",
  • "externalMetadata": "string",
  • "customerId": "3fc260f3-3e91-470b-8285-15a11c799491",
  • "siteId": "1218614a-9822-43c5-94ca-1ecc29ab80b0",
  • "description": "Chilled Water Pump CWP-01.1 is running when Chiller CH-01 is off.",
  • "createdDate": "2020-05-28T01:25:02.881Z",
  • "detectedDate": "2020-05-28T01:02:02.836Z"
}
Retrieve an insight
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
insightId
required
string <uuid> 
The unique ID of the insight which is given by Willow


 
 Example:  8cf1743b-fcb7-44c8-9b6d-0038323ba9e5
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Not Found


get/sites/{siteId}/insights/{insightId}
Request samples 
Response samples 
application/json
{
  • "id": "8cf1743b-fcb7-44c8-9b6d-0038323ba9e5",
  • "sequenceNumber": "av-I-465",
  • "floorCode": "L010",
  • "equipmentId": "6be53768-811e-4db8-baee-471a01498df7",
  • "type": "faultDetection",
  • "name": "258adba7",
  • "priority": 3,
  • "status": "inProgress",
  • "state": "active",
  • "occurredDate": "2020-05-28T00:33:02.836Z",
  • "updatedDate": "2020-08-28T13:46:01.919Z",
  • "externalId": "20200428_d4b43edf",
  • "externalStatus": "active",
  • "externalMetadata": "string",
  • "customerId": "3fc260f3-3e91-470b-8285-15a11c799491",
  • "siteId": "1218614a-9822-43c5-94ca-1ecc29ab80b0",
  • "description": "Chilled Water Pump CWP-01.1 is running when Chiller CH-01 is off.",
  • "createdDate": "2020-05-28T01:25:02.881Z",
  • "detectedDate": "2020-05-28T01:02:02.836Z"
}
Update an insight
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
insightId
required
string <uuid> 
The unique ID of the insight which is given by Willow


 
 Example:  8cf1743b-fcb7-44c8-9b6d-0038323ba9e5
Request Body schema: 
name
string or null
 
description
string or null
 
priority
integer or null <int32> 
 
state
string (InsightState) 
The state of the insight


 Enum: "inactive" "active" "archived"  
occurredDate
string or null <date-time> 
 
detectedDate
string or null <date-time> 
 
externalId
string or null
 
externalStatus
string or null
 
externalMetadata
string or null
 
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Not Found


put/sites/{siteId}/insights/{insightId}
Request samples 
{
  • "name": "string",
  • "description": "string",
  • "priority": 0,
  • "state": "active",
  • "occurredDate": "2019-08-24T14:15:22Z",
  • "detectedDate": "2019-08-24T14:15:22Z",
  • "externalId": "string",
  • "externalStatus": "string",
  • "externalMetadata": "string"
}
Response samples 
application/json
{
  • "id": "8cf1743b-fcb7-44c8-9b6d-0038323ba9e5",
  • "sequenceNumber": "av-I-465",
  • "floorCode": "L010",
  • "equipmentId": "6be53768-811e-4db8-baee-471a01498df7",
  • "type": "faultDetection",
  • "name": "258adba7",
  • "priority": 3,
  • "status": "inProgress",
  • "state": "active",
  • "occurredDate": "2020-05-28T00:33:02.836Z",
  • "updatedDate": "2020-08-28T13:46:01.919Z",
  • "externalId": "20200428_d4b43edf",
  • "externalStatus": "active",
  • "externalMetadata": "string",
  • "customerId": "3fc260f3-3e91-470b-8285-15a11c799491",
  • "siteId": "1218614a-9822-43c5-94ca-1ecc29ab80b0",
  • "description": "Chilled Water Pump CWP-01.1 is running when Chiller CH-01 is off.",
  • "createdDate": "2020-05-28T01:25:02.881Z",
  • "detectedDate": "2020-05-28T01:02:02.836Z"
}
Delete an insight
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
insightId
required
string <uuid> 
The unique ID of the insight which is given by Willow


 
 Example:  8cf1743b-fcb7-44c8-9b6d-0038323ba9e5
Responses 
204
Success


401
Unauthorized


403
Forbidden


404
Not Found


delete/sites/{siteId}/insights/{insightId}
Request samples 
Update an insight state
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
insightId
required
string <uuid> 
The unique ID of the insight which is given by Willow


 
 Example:  8cf1743b-fcb7-44c8-9b6d-0038323ba9e5
Request Body schema: 
state
string (InsightState) 
The state of the insight


 Enum: "inactive" "active" "archived"  
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Not Found


put/sites/{siteId}/insights/{insightId}/state
Request samples 
{
  • "state": "active"
}
Response samples 
application/json
{
  • "id": "8cf1743b-fcb7-44c8-9b6d-0038323ba9e5",
  • "sequenceNumber": "av-I-465",
  • "floorCode": "L010",
  • "equipmentId": "6be53768-811e-4db8-baee-471a01498df7",
  • "type": "faultDetection",
  • "name": "258adba7",
  • "priority": 3,
  • "status": "inProgress",
  • "state": "active",
  • "occurredDate": "2020-05-28T00:33:02.836Z",
  • "updatedDate": "2020-08-28T13:46:01.919Z",
  • "externalId": "20200428_d4b43edf",
  • "externalStatus": "active",
  • "externalMetadata": "string",
  • "customerId": "3fc260f3-3e91-470b-8285-15a11c799491",
  • "siteId": "1218614a-9822-43c5-94ca-1ecc29ab80b0",
  • "description": "Chilled Water Pump CWP-01.1 is running when Chiller CH-01 is off.",
  • "createdDate": "2020-05-28T01:25:02.881Z",
  • "detectedDate": "2020-05-28T01:02:02.836Z"
}
Tickets
Tickets are used to describe both service requests and incidents that can be generated and tracked within the Willow platform. When a ticket is generated, a pre-defined workflow will determine how the problem is responded to and remedied. The Willow platform can automate the creation of tickets when an Insight is generated. Tickets that are generated outside the Willow platform can be created and updated using this endpoint.


List tickets
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
query Parameters
createdAfter
string or null <date-time> 
Date created by which to filter specific results desired in ISO 8601 format


 
 Example:  createdAfter=2021-05-30T22:12:21.047Z
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/tickets
Request samples 
Response samples 
application/json
[
  • {
    • "id": "9740da10-9f90-4623-9d48-51d14c093526",
    • "sequenceNumber": "av-T-4",
    • "floorCode": "L010",
    • "priority": 2,
    • "status": "inProgress",
    • "issueType": "equipment",
    • "issueId": "6be53768-811e-4db8-baee-471a01498df7",
    • "issueName": "VAV-10.1",
    • "description": "The area around my workstation is too hot today.",
    • "reporterId": "c5260fe8-520d-4513-af62-28439855c48a",
    • "reporterName": "Michael Bennett",
    • "reporterPhone": "(555) 555-5555",
    • "reporterEmail": "mbennett@acmecorp.com",
    • "reporterCompany": "Acme Corp",
    • "externalId": "WHQ-BLDG1-00000789",
    • "assigneeType": "customerUser",
    • "assigneeId": "2a4d6a10-72e5-414f-94a3-389967df4a00",
    • "sourceType": "platform",
    • "sourceId": "92913814g-9822-43c5-94gc-1ecf27ac80b2",
    • "dueDate": "2020-05-27T07:00:00.000Z",
    • "createdDate": "2020-05-28T05:17:47.142Z",
    • "updatedDate": "2020-05-28T05:19:00.181Z",
    • "resolvedDate": "2020-05-28T09:14:02.713Z",
    • "closedDate": "2020-05-28T09:14:22.479Z",
    • "categoryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
]
Create a ticket
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Request Body schema: 
floorId
string or null
The unique ID of the floor which is given by Willow


 
priority
integer <int32> 
The code for the priority level. Urgent=1, High=2, Medium=3, Low=4


 
summary
string or null
 
description
string or null
 
status
string (TicketStatus) 
The status of the ticket


 Enum: "open" "reassign" "inProgress" "limitedAvailability" "resolved" "closed"  
externalId
string or null
 
externalStatus
string or null
 
externalMetadata
string or null
 
object (ReporterDto) 
 
dueDate
string or null <date-time> 
Date and time when the ticket is due to be complete


 
categoryId
string <uuid> 
The category ID of the ticket which is given by Willow


 
Responses 
201
Created


401
Unauthorized


403
Forbidden


post/sites/{siteId}/tickets
Request samples 
{
  • "floorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "priority": 2,
  • "summary": "string",
  • "description": "The area around my workstation is too hot today.",
  • "status": "inProgress",
  • "externalId": "string",
  • "externalStatus": "string",
  • "externalMetadata": "string",
  • "reporter": {
    • "id": "c5260fe8-520d-4513-af62-28439855c48a",
    • "siteId": "1218614a-9822-43c5-94ca-1ecc29ab80b0",
    • "name": "Michael Bennett",
    • "phone": "(555) 555-5555",
    • "email": "mbennett@acmecorp.com",
    • "company": "Acme Corp"
    },
  • "dueDate": "2020-05-27T07:00:00.000Z",
  • "categoryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
Response samples 
application/json
{
  • "id": "9740da10-9f90-4623-9d48-51d14c093526",
  • "sequenceNumber": "av-T-4",
  • "floorCode": "L010",
  • "priority": 2,
  • "status": "inProgress",
  • "issueType": "equipment",
  • "issueId": "6be53768-811e-4db8-baee-471a01498df7",
  • "issueName": "VAV-10.1",
  • "description": "The area around my workstation is too hot today.",
  • "reporterId": "c5260fe8-520d-4513-af62-28439855c48a",
  • "reporterName": "Michael Bennett",
  • "reporterPhone": "(555) 555-5555",
  • "reporterEmail": "mbennett@acmecorp.com",
  • "reporterCompany": "Acme Corp",
  • "externalId": "WHQ-BLDG1-00000789",
  • "assigneeType": "customerUser",
  • "assigneeId": "2a4d6a10-72e5-414f-94a3-389967df4a00",
  • "sourceType": "platform",
  • "sourceId": "92913814g-9822-43c5-94gc-1ecf27ac80b2",
  • "dueDate": "2020-05-27T07:00:00.000Z",
  • "createdDate": "2020-05-28T05:17:47.142Z",
  • "updatedDate": "2020-05-28T05:19:00.181Z",
  • "resolvedDate": "2020-05-28T09:14:02.713Z",
  • "closedDate": "2020-05-28T09:14:22.479Z",
  • "categoryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "customerId": "3fc260f3-3e91-470b-8285-15a11c799491",
  • "siteId": "1218614a-9822-43c5-94ca-1ecc29ab80b0",
  • "cause": "VAV Box fan stuck",
  • "solution": "Replaced fan motor",
  • "externalStatus": "In Progress",
  • "externalMetadata": "string",
  • "attachments": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "type": "image",
      • "fileName": "string",
      • "createdDate": "2019-08-24T14:15:22Z"
      }
    ]
}
Retrieve a ticket
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
ticketId
required
string <uuid> 
The unique ID of the ticket which is given by Willow


 
 Example:  9740da10-9f90-4623-9d48-51d14c093526
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Not Found


get/sites/{siteId}/tickets/{ticketId}
Request samples 
Response samples 
application/json
{
  • "id": "9740da10-9f90-4623-9d48-51d14c093526",
  • "sequenceNumber": "av-T-4",
  • "floorCode": "L010",
  • "priority": 2,
  • "status": "inProgress",
  • "issueType": "equipment",
  • "issueId": "6be53768-811e-4db8-baee-471a01498df7",
  • "issueName": "VAV-10.1",
  • "description": "The area around my workstation is too hot today.",
  • "reporterId": "c5260fe8-520d-4513-af62-28439855c48a",
  • "reporterName": "Michael Bennett",
  • "reporterPhone": "(555) 555-5555",
  • "reporterEmail": "mbennett@acmecorp.com",
  • "reporterCompany": "Acme Corp",
  • "externalId": "WHQ-BLDG1-00000789",
  • "assigneeType": "customerUser",
  • "assigneeId": "2a4d6a10-72e5-414f-94a3-389967df4a00",
  • "sourceType": "platform",
  • "sourceId": "92913814g-9822-43c5-94gc-1ecf27ac80b2",
  • "dueDate": "2020-05-27T07:00:00.000Z",
  • "createdDate": "2020-05-28T05:17:47.142Z",
  • "updatedDate": "2020-05-28T05:19:00.181Z",
  • "resolvedDate": "2020-05-28T09:14:02.713Z",
  • "closedDate": "2020-05-28T09:14:22.479Z",
  • "categoryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "customerId": "3fc260f3-3e91-470b-8285-15a11c799491",
  • "siteId": "1218614a-9822-43c5-94ca-1ecc29ab80b0",
  • "cause": "VAV Box fan stuck",
  • "solution": "Replaced fan motor",
  • "externalStatus": "In Progress",
  • "externalMetadata": "string",
  • "attachments": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "type": "image",
      • "fileName": "string",
      • "createdDate": "2019-08-24T14:15:22Z"
      }
    ]
}
Update a ticket
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
ticketId
required
string <uuid> 
The unique ID of the ticket which is given by Willow


 
 Example:  9740da10-9f90-4623-9d48-51d14c093526
Request Body schema: 
priority
integer or null <int32> 
 
status
string (TicketStatus) 
The status of the ticket


 Enum: "open" "reassign" "inProgress" "limitedAvailability" "resolved" "closed"  
floorCode
string or null
 
summary
string or null
 
description
string or null
 
cause
string or null
 
solution
string or null
 
assigneeType
string (TicketAssigneeType) 
The user type of who is assigned to work on the ticket


 Enum: "noAssignee" "contractor" "customerUser"  
assigneeId
string or null <uuid> 
 
dueDate
string or null <date-time> 
 
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Not Found


put/sites/{siteId}/tickets/{ticketId}
Request samples 
{
  • "priority": 0,
  • "status": "inProgress",
  • "floorCode": "string",
  • "summary": "string",
  • "description": "string",
  • "cause": "string",
  • "solution": "string",
  • "assigneeType": "customerUser",
  • "assigneeId": "665a9750-71bd-4b96-bacd-9efa4ae022dd",
  • "dueDate": "2019-08-24T14:15:22Z"
}
Response samples 
application/json
{
  • "id": "9740da10-9f90-4623-9d48-51d14c093526",
  • "sequenceNumber": "av-T-4",
  • "floorCode": "L010",
  • "priority": 2,
  • "status": "inProgress",
  • "issueType": "equipment",
  • "issueId": "6be53768-811e-4db8-baee-471a01498df7",
  • "issueName": "VAV-10.1",
  • "description": "The area around my workstation is too hot today.",
  • "reporterId": "c5260fe8-520d-4513-af62-28439855c48a",
  • "reporterName": "Michael Bennett",
  • "reporterPhone": "(555) 555-5555",
  • "reporterEmail": "mbennett@acmecorp.com",
  • "reporterCompany": "Acme Corp",
  • "externalId": "WHQ-BLDG1-00000789",
  • "assigneeType": "customerUser",
  • "assigneeId": "2a4d6a10-72e5-414f-94a3-389967df4a00",
  • "sourceType": "platform",
  • "sourceId": "92913814g-9822-43c5-94gc-1ecf27ac80b2",
  • "dueDate": "2020-05-27T07:00:00.000Z",
  • "createdDate": "2020-05-28T05:17:47.142Z",
  • "updatedDate": "2020-05-28T05:19:00.181Z",
  • "resolvedDate": "2020-05-28T09:14:02.713Z",
  • "closedDate": "2020-05-28T09:14:22.479Z",
  • "categoryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "customerId": "3fc260f3-3e91-470b-8285-15a11c799491",
  • "siteId": "1218614a-9822-43c5-94ca-1ecc29ab80b0",
  • "cause": "VAV Box fan stuck",
  • "solution": "Replaced fan motor",
  • "externalStatus": "In Progress",
  • "externalMetadata": "string",
  • "attachments": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "type": "image",
      • "fileName": "string",
      • "createdDate": "2019-08-24T14:15:22Z"
      }
    ]
}
Create Multiple Tickets
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Request Body schema: 
 Array 
floorId
string or null
The unique ID of the floor which is given by Willow


 
priority
integer <int32> 
The code for the priority level. Urgent=1, High=2, Medium=3, Low=4


 
summary
string or null
 
description
string or null
 
status
string (TicketStatus) 
The status of the ticket


 Enum: "open" "reassign" "inProgress" "limitedAvailability" "resolved" "closed"  
externalId
string or null
 
externalStatus
string or null
 
externalMetadata
string or null
 
object (ReporterDto) 
 
dueDate
string or null <date-time> 
Date and time when the ticket is due to be complete


 
categoryId
string <uuid> 
The category ID of the ticket which is given by Willow


 
Responses 
200
Success


401
Unauthorized


403
Forbidden


post/sites/{siteId}/tickets/batch
Request samples 
[
  • {
    • "floorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    • "priority": 2,
    • "summary": "string",
    • "description": "The area around my workstation is too hot today.",
    • "status": "inProgress",
    • "externalId": "string",
    • "externalStatus": "string",
    • "externalMetadata": "string",
    • "reporter": {
      • "id": "c5260fe8-520d-4513-af62-28439855c48a",
      • "siteId": "1218614a-9822-43c5-94ca-1ecc29ab80b0",
      • "name": "Michael Bennett",
      • "phone": "(555) 555-5555",
      • "email": "mbennett@acmecorp.com",
      • "company": "Acme Corp"
      },
    • "dueDate": "2020-05-27T07:00:00.000Z",
    • "categoryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
]
List Reporters
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/reporters
Request samples 
Response samples 
application/json
[
  • {
    • "id": "c5260fe8-520d-4513-af62-28439855c48a",
    • "siteId": "1218614a-9822-43c5-94ca-1ecc29ab80b0",
    • "name": "Michael Bennett",
    • "phone": "(555) 555-5555",
    • "email": "mbennett@acmecorp.com",
    • "company": "Acme Corp"
    }
]
Create a reporter
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Request Body schema: 
customerId
string <uuid> 
 
name
string or null
The name of the ticket reporter (requestor)


 
phone
string or null
 
email
string or null
 
company
string or null
 
Responses 
200
Success


401
Unauthorized


403
Forbidden


post/sites/{siteId}/reporters
Request samples 
{
  • "customerId": "3fc260f3-3e91-470b-8285-15a11c799491",
  • "name": "Michael Bennett",
  • "phone": "(555) 555-5555",
  • "email": "mbennett@acmecorp.com",
  • "company": "Acme Corp"
}
Response samples 
application/json
{
  • "id": "c5260fe8-520d-4513-af62-28439855c48a",
  • "siteId": "1218614a-9822-43c5-94ca-1ecc29ab80b0",
  • "name": "Michael Bennett",
  • "phone": "(555) 555-5555",
  • "email": "mbennett@acmecorp.com",
  • "company": "Acme Corp"
}
Update a reporter
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
reporterId
required
string <uuid> 
The unique ID of the ticket reporter which is given by Willow


 
 Example:  c5260fe8-520d-4513-af62-28439855c48a
Request Body schema: 
customerId
string <uuid> 
 
name
string or null
The name of the ticket reporter (requestor)


 
phone
string or null
 
email
string or null
 
company
string or null
 
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Not Found


put/sites/{siteId}/reporters/{reporterId}
Request samples 
{
  • "customerId": "3fc260f3-3e91-470b-8285-15a11c799491",
  • "name": "Michael Bennett",
  • "phone": "(555) 555-5555",
  • "email": "mbennett@acmecorp.com",
  • "company": "Acme Corp"
}
Response samples 
application/json
{
  • "id": "c5260fe8-520d-4513-af62-28439855c48a",
  • "siteId": "1218614a-9822-43c5-94ca-1ecc29ab80b0",
  • "name": "Michael Bennett",
  • "phone": "(555) 555-5555",
  • "email": "mbennett@acmecorp.com",
  • "company": "Acme Corp"
}
Delete a reporter
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
reporterId
required
string <uuid> 
The unique ID of the ticket reporter which is given by Willow


 
 Example:  c5260fe8-520d-4513-af62-28439855c48a
Responses 
204
Success


401
Unauthorized


403
Forbidden


404
Not Found


delete/sites/{siteId}/reporters/{reporterId}
Request samples 
List ticket categories
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/tickets/categories
Request samples 
Response samples 
application/json
[
  • {
    • "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    • "siteId": "1218614a-9822-43c5-94ca-1ecc29ab80b0",
    • "name": "Too Hot"
    }
]
Create a ticket category
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Request Body schema: 
name
string
The name of the ticket category


 
Responses 
200
Success


401
Unauthorized


403
Forbidden


post/sites/{siteId}/tickets/categories
Request samples 
{
  • "name": "Too Hot"
}
Response samples 
application/json
{
  • "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "siteId": "1218614a-9822-43c5-94ca-1ecc29ab80b0",
  • "name": "Too Hot"
}
Retrieve a ticket category
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
ticketCategoryId
required
string <uuid> 
The unique ID of the ticket category which is given by Willow


 
 Example:  3fa85f64-5717-4562-b3fc-2c963f66afa6
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Not Found


get/sites/{siteId}/tickets/categories/{ticketCategoryId}
Request samples 
Response samples 
application/json
{
  • "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "siteId": "1218614a-9822-43c5-94ca-1ecc29ab80b0",
  • "name": "Too Hot"
}
Update a ticket category
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
ticketCategoryId
required
string <uuid> 
The unique ID of the ticket category which is given by Willow


 
 Example:  3fa85f64-5717-4562-b3fc-2c963f66afa6
Request Body schema: 
name
string
The name of the ticket category


 
Responses 
204
Success


401
Unauthorized


403
Forbidden


404
Not Found


put/sites/{siteId}/tickets/categories/{ticketCategoryId}
Request samples 
{
  • "name": "Too Hot"
}
Delete a ticket category
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
ticketCategoryId
required
string <uuid> 
The unique ID of the ticket category which is given by Willow


 
 Example:  3fa85f64-5717-4562-b3fc-2c963f66afa6
Responses 
204
Success


401
Unauthorized


403
Forbidden


404
Not Found


delete/sites/{siteId}/tickets/categories/{ticketCategoryId}
Request samples 
Users
Users are provisioned for each customer and given access to individual Sites.


List users
SecurityOAuth2 
Request 
path Parameters
customerId
required
string <uuid> 
The unique ID of the customer which is given by Willow


 
 Example:  b69d2f21-0c13-47e2-82bc-5a1b144b81c9
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
query Parameters
email
string or null
E-mail address by which to filter specific results


 
 Example:  email=mbennett@acmecorp.com
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/customers/{customerId}/sites/{siteId}/users
Request samples 
Response samples 
application/json
[
  • {
    • "id": "c5260fe8-520d-4513-af62-28439855c48a",
    • "name": "Michael Bennett",
    • "phone": "(555) 555-5555",
    • "email": "mbennett@acmecorp.com",
    • "company": "Acme Corp",
    • "createdDate": "2021-05-30T22:12:21.047Z"
    }
]
Models
Models refer to the Digital Twin Definition Language (DTDL) interfaces in the WillowTwin. The collection of models loaded into the WillowTwin are referred to as the ontology from which twins can be created.


List models
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/models
Request samples 
Response samples 
application/json
[
  • {
    • "isDecommissioned": false,
    • "id": "dtmi:com:willowinc:FanPoweredBox;1",
    • "displayName": {
      • "en": "Fan Powered Box"
      },
    • "description": {
      • "en": "Fan Powered Box is an HVAC terminal unit used to supply conditioned air to a space. The amount of air is regulated with a fan."
      },
    • "uploadTime": "2020-05-27T16:48:20.773Z",
    • "isShared": true
    }
]
Retrieve a model
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
id
required
string <uuid> 
The unique ID of the resource


 
 Example:  WLW-NYC-575_5_AVE-FPB-17.02
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Not Found


get/sites/{siteId}/models/{id}
Request samples 
Response samples 
application/json
{
  • "isDecommissioned": false,
  • "id": "dtmi:com:willowinc:FanPoweredBox;1",
  • "displayName": {
    • "en": "Fan Powered Box"
    },
  • "description": {
    • "en": "Fan Powered Box is an HVAC terminal unit used to supply conditioned air to a space. The amount of air is regulated with a fan."
    },
  • "uploadTime": "2020-05-27T16:48:20.773Z",
  • "isShared": true
}
Search models
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
query Parameters
query
string
String to search within DTDL model ids


 
 Example:  query=Occupancy
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/models/search
Request samples 
Response samples 
application/json
[
  • "dtmi:com:willowinc:OccupancySensor;1",
  • "dtmi:com:willowinc:OccupancySetpoint;1",
  • "dtmi:com:willowinc:OccupancyZone;1",
  • "dtmi:com:willowinc:OccupancySensorEquipment;1"
]
Twins
Twins refer to any node in the WillowTwin. This endpoint can be used to maintain twins of any Model, provision twin relationships, and query for twins to find a subset of twins and their relationships.


List twins
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Responses 
200
Success


401
Unauthorized


403
Forbidden


get/sites/{siteId}/twins
Request samples 
Response samples 
application/json
[
  • {
    • "id": "WLW-NYC-575_5_AVE-FPB-17.02",
    • "metadata": {
      • "modelId": "dtmi:com:willowinc:FanPoweredBox;1"
      },
    • "customProperties": {
      • "name": "string",
      • "modelNumber": "string",
      • "maxAirflowRating": 0
      }
    }
]
Create a Twin
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Request Body schema: 
id
string <uuid> 
The twin ID of the asset stored in ADT as $dtId


 
object (TwinMetadata) 
 
object (TwinProperties) 
 
Responses 
201
Created


401
Unauthorized


403
Forbidden


post/sites/{siteId}/twins
Request samples 
{
  • "id": "WLW-NYC-575_5_AVE-FPB-17.02",
  • "metadata": {
    • "modelId": "dtmi:com:willowinc:FanPoweredBox;1"
    },
  • "customProperties": {
    • "name": "string",
    • "modelNumber": "string",
    • "maxAirflowRating": 0
    }
}
Response samples 
application/json
{
  • "id": "WLW-NYC-575_5_AVE-FPB-17.02",
  • "metadata": {
    • "modelId": "dtmi:com:willowinc:FanPoweredBox;1"
    },
  • "customProperties": {
    • "name": "string",
    • "modelNumber": "string",
    • "maxAirflowRating": 0
    }
}
Retrieve a twin
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
id
required
string <uuid> 
The unique ID of the resource


 
 Example:  WLW-NYC-575_5_AVE-FPB-17.02
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Not Found


get/sites/{siteId}/twins/{id}
Request samples 
Response samples 
application/json
{
  • "id": "WLW-NYC-575_5_AVE-FPB-17.02",
  • "metadata": {
    • "modelId": "dtmi:com:willowinc:FanPoweredBox;1"
    },
  • "customProperties": {
    • "name": "string",
    • "modelNumber": "string",
    • "maxAirflowRating": 0
    }
}
List twins with relationships
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Not Found


get/sites/{siteId}/twins/withrelationships
Request samples 
Response samples 
application/json
[
  • {
    • "twin": {
      • "id": "WLW-NYC-575_5_AVE-FPB-17.02",
      • "metadata": {
        • "modelId": "dtmi:com:willowinc:FanPoweredBox;1"
        },
      • "customProperties": {
        • "name": "string",
        • "modelNumber": "string",
        • "maxAirflowRating": 0
        }
      },
    • "relationships": {
      • "id": "isFedBy_WLW-NYC-575_5_AVE-AHU.LR.03_d9e36596-bf36-4870-ba82-fffe78adce4d",
      • "name": "isFedBy",
      • "displayName": "Is Fed By",
      • "sourceId": "WLW-NYC-575_5_AVE-FPB-17.02",
      • "targetId": "WLW-NYC-575_5_AVE-AHU.LR.03",
      • "customProperties": {
        • "substance": "string"
        }
      }
    }
]
Create a twin relationship
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Request Body schema: 
id
string
 
name
string
 
displayName
string
 
sourceId
string
 
targetId
string
 
object (TwinRelationshipProperties) 
 
Responses 
200
Success


401
Unauthorized


403
Forbidden


post/sites/{siteId}/twins/relationships
Request samples 
{
  • "id": "isFedBy_WLW-NYC-575_5_AVE-AHU.LR.03_d9e36596-bf36-4870-ba82-fffe78adce4d",
  • "name": "isFedBy",
  • "displayName": "Is Fed By",
  • "sourceId": "WLW-NYC-575_5_AVE-FPB-17.02",
  • "targetId": "WLW-NYC-575_5_AVE-AHU.LR.03",
  • "customProperties": {
    • "substance": "string"
    }
}
Response samples 
application/json
{
  • "id": "isFedBy_WLW-NYC-575_5_AVE-AHU.LR.03_d9e36596-bf36-4870-ba82-fffe78adce4d",
  • "name": "isFedBy",
  • "displayName": "Is Fed By",
  • "sourceId": "WLW-NYC-575_5_AVE-FPB-17.02",
  • "targetId": "WLW-NYC-575_5_AVE-AHU.LR.03",
  • "customProperties": {
    • "substance": "string"
    }
}
List relationships for a twin
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
id
required
string <uuid> 
The unique ID of the resource


 
 Example:  WLW-NYC-575_5_AVE-FPB-17.02
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Not Found


get/sites/{siteId}/twins/{id}/relationships
Request samples 
Response samples 
application/json
[
  • {
    • "id": "isFedBy_WLW-NYC-575_5_AVE-AHU.LR.03_d9e36596-bf36-4870-ba82-fffe78adce4d",
    • "name": "isFedBy",
    • "displayName": "Is Fed By",
    • "sourceId": "WLW-NYC-575_5_AVE-FPB-17.02",
    • "targetId": "WLW-NYC-575_5_AVE-AHU.LR.03",
    • "customProperties": {
      • "substance": "string"
      }
    }
]
Retrieve a twin relationship
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
twinId
required
string <uuid> 
The unique ID of the twin


 
 Example:  WLW-NYC-575_5_AVE-FPB-17.02
relationshipId
required
string <uuid> 
The unique ID of the twin relationship


 
 Example:  isFedBy_WLW-NYC-575_5_AVE-AHU.LR.03_d9e36596-bf36-4870-ba82-fffe78adce4d
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Not Found


get/sites/{siteId}/twins/{twinId}/relationships/{relationshipId}
Request samples 
Response samples 
application/json
{
  • "id": "isFedBy_WLW-NYC-575_5_AVE-AHU.LR.03_d9e36596-bf36-4870-ba82-fffe78adce4d",
  • "name": "isFedBy",
  • "displayName": "Is Fed By",
  • "sourceId": "WLW-NYC-575_5_AVE-FPB-17.02",
  • "targetId": "WLW-NYC-575_5_AVE-AHU.LR.03",
  • "customProperties": {
    • "substance": "string"
    }
}
Delete a twin relationship
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
twinId
required
string <uuid> 
The unique ID of the twin


 
 Example:  WLW-NYC-575_5_AVE-FPB-17.02
relationshipId
required
string <uuid> 
The unique ID of the twin relationship


 
 Example:  isFedBy_WLW-NYC-575_5_AVE-AHU.LR.03_d9e36596-bf36-4870-ba82-fffe78adce4d
Responses 
204
Success


401
Unauthorized


403
Forbidden


404
Not Found


delete/sites/{siteId}/twins/{twinId}/relationships/{relationshipId}
Request samples 
Query twins
SecurityOAuth2 
Request 
path Parameters
siteId
required
string <uuid> 
The unique ID of the site which is given by Willow


 
 Example:  1218614a-9822-43c5-94ca-1ecc29ab80b0
Request Body schema: 
fromCache
boolean
Determines whether to execute the query from the cache or ADT


 
restrictToSite
boolean
Determines whether to execute the query for only the site specified in the path or the entire customer instance


 
restrictWithChildren
boolean
Determines whether the twins defined in rootModels should only be included in the results if they have children relationships.


 
rootModels
Array of strings
Array of DTDL model ids from which to start the twin query graph traversal


 
object
Defines which relationship names (followAny) to traverse from the twins found in the rootModel and which model ids (toModel) to stop the traversal. To traverse a relationship in the opposite direction in which twins are related, add a - prefix to the relationship name such as rootModel Zone followAny -isCapabilityOf toModel Sensor. Relationships directions can be mixed in the same query such as rootModel Zone followAny ["isPartOf", "-isPartOf"] toModel Room.


 
floors
Array of strings
Array of floor ids to restrict the query to


 
Responses 
200
Success


401
Unauthorized


403
Forbidden


post/sites/{siteId}/twins/query
Request samples 
{
  • "fromCache": true,
  • "restrictToSite": true,
  • "restrictWithChildren": true,
  • "rootModels": [
    • "dtmi:com:willowinc:Sensor;1"
    ],
  • "relationships": {
    • "followAny": [
      • "isCapabilityOf"
      ],
    • "toModel": "dtmi:com:willowinc:Zone;1"
    },
  • "floors": [
    • "b7d170fd-48fd-4392-a4e9-1ad5880edc62"
    ]
}
Response samples 
application/json
[
  • {
    • "id": "WLW-NYC-575_5_AVE-FPB-17.02",
    • "metadata": {
      • "modelId": "dtmi:com:willowinc:FanPoweredBox;1"
      },
    • "customProperties": {
      • "name": "string",
      • "modelNumber": "string",
      • "maxAirflowRating": 0
      }
    }
]
Copyright © 2022 Willow. All rights reserved.