NAV
shell

Introduction

Welcome to the SIERA API. You can use the SIERA API to access and modify Assets, Meter and Consumption data.

This page helps you to understand the requirements of the API, common errors, the format of data sent and received and other details related to security and operation of the API.

We provide an OpenAPI specification description which can be imported into programs such as Postman to help you get started with the API.

Requirements

To use the latest version of the REST API you will need a valid account with SIERA. This can be obtained by contacting SIERA Support.

Request format

Request parameters should be provided using the application/json Content-Type. The only exception is the IDs of entities or assets which are part of the URLs.

Unless otherwise documented all responses are JSON-encoded Content-Type: application/json.

All endpoints require either a bearer token or basic token which must be specified in the header of the request. How to obtain a token is explained in authentication.

Date format

All date formats should be sent as dd/mm/yy

Response types

Most endpoints will return a standard HTTP status code to reflect the result of the API call. Where an endpoint produces a different response code, or has additional information about a response code it will be written against the endpoint's information.

Code Text Description
200 Ok Success, assets returned in the response body
201 Created Success, the uploaded entity has been successfully created
400 Bad request Failed, the request failed validation
404 Not found Failed, the item was not found
429 Too many requests Failed, the request was refused due excessive use
5xx Server error Failed, an error has occurred on our servers. Wait a few minutes and try again or notify us if the errors continue

Rate limiting

The SIERA API enforces a rate limit on the number of requests allowed within certain time frames. The limits are:

Time frame Number of requests allowed
1 second 100
15 minutes 1000
12 hours 10,000
7 days 100,000

For every request that is made the number of further requests allowed in the largest available time frame will be returned in the headers of the response along with the datetime the limit will be reset, for example:

x-rate-limit-limit: 7d
x-rate-limit-remaining: 9991
x-rate-limit-reset: 2021-12-29T15:21:09.3213831Z

If the limit is exceeded the caller will receive a HTTP status code of 429 Too Many Requests along with a response body indicating the limit exceeded such as API calls quota exceeded! maximum admitted 2 per 1s.

Authentication

There are 2 options for authentication when using the SIERA API:

  1. Use Basic Authentication and insert encoded credentials in the header of the request.
  2. Use the login endpoint to obtain a Bearer token which is then inserted into the header of the request.

Basic Authentication

To use Basic Authentication simply take the username and password and form a string joined by a single colon (:). This string is then encoded into Base64, and inserted into the Authorization header with the word Basic before it.

As an example, if the user testuser@companyabc.com with password SekaiFleur@PalomaSchnee combines these credentials (testuser@companyabc.com:SekaiFleur@PalomaSchnee), and then encodes that into Base64 we get the string dGVzdHVzZXJAY29tcGFueWFiYy5jb206U2VrYWlGbGV1ckBQYWxvbWFTY2huZWU=. This can then be inserted into the header to authenticate each request as

Authorization: Basic dGVzdHVzZXJAY29tcGFueWFiYy5jb206U2VrYWlGbGV1ckBQYWxvbWFTY2huZWU=

Basic Authentication is required for access to the API via Excel and Power BI, and secured primarily using TLS. Owasp Security guidelines recognise it discloses secrets in plain text (base64 encoded) and recommends against its use where possible, but accepts that where necessary TLS must be used.

Get bearer token

POST /api/v1/authentication/login

curl POST https://api.sieraglobal.com/api/v1/authentication/login \
  -H 'accept: */*' \
  -V "Content-Type: application/json" \
  -d @- <<JSON  
  {
    "email": "testuser@companyabc.com",
    "password": "SekaiFleur@PalomaSchnee"
  }

Response (200)

{
  "token": "eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0J1LUhTMjU2IiwidHlwIjoiSldUIn0.Fb5jEJb9zokguyPFyha4YFwguTMe8zChZ9isrCgI5r8o1Lfk0q_few.c02C5x7NTPEzerSoc8Rghw.lRWHsUJSm5W-NR8sfg8756MVDyA66dy_Ymet78bmNarFXEbvUYmOjCg1maDrUDmUWvWvi7_OYjAz7CgiHs7btIStaBklGX1nxIh60c_8DpA3ustSTYjmnrdSlPDJ9gENeewDIHWCjTgz1MjKhE42mdeZ6xFrxu7JFcc23m4J31kcbR8wL92MZChb_issdqhXc8CnZzYwP-PZ3wCWgsn63gc_-yQ5Y5cz9a1Sqtcbx7P2fw7PDkQi1SvVRcL7XQXhGvNbuyB21sxYYTjdcatoY6wAAGGF_UcTMmhoDV6dziELEq7pGKkwmFXZP38rZs_CBM7vtBKtWY_ESX1_C7SmrucQJRa4sdrsbHA98-q1lQkoK-ZJnl3wZRoJ6xslEicxj9bpuRL20ZRd-kmXwPBSY0ldTcvkLHhKGrN7vMBmbmQDcnps2iH64BOWi-O-YKupGK70eO-YmYLZ3T85nlbttg.Mo9LyvjYVYzN6cl258MXrQ",
  "expiration": "2021-11-27T15:20:47Z",
  "lockoutTimeRemaining": null,
  "maxRetriesExceeded": 0,
  "previousAccessFailedCount": 0
}

Response (401)

{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "traceId": "00-67cb3e28086d1b4198cf96e8d37b495a-e76f80e2f9c51f4b-00"
}

Response (403) - Locked

{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Locked",
  "detail": 45,
  "status": 403,
  "traceId": "00-67cb3e28086d1b4198cf96e8d37b495a-e76f80e2f9c51f4b-00"
}

Response (403) - Password Expiry

{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Expired",
  "detail": "eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0J1LUhTMjU2IiwidHlwIjoiSldUIn0.Fb5jEJb9zokguyPFyha4YFwguTMe8zChZ9isrCgI5r8o1Lfk0q_few.c02C5x7NTPEzerSoc8Rghw.lRWHsUJSm5W-NR8sfg8756MVDyA66dy_Ymet78bmNarFXEbvUYmOjCg1maDrUDmUWvWvi7_OYjAz7CgiHs7btIStaBklGX1nxIh60c_8DpA3ustSTYjmnrdSlPDJ9gENeewDIHWCjTgz1MjKhE42mdeZ6xFrxu7JFcc23m4J31kcbR8wL92MZChb_issdqhXc8CnZzYwP-PZ3wCWgsn63gc_-yQ5Y5cz9a1Sqtcbx7P2fw7PDkQi1SvVRcL7XQXhGvNbuyB21sxYYTjdcatoY6wAAGGF_UcTMmhoDV6dziELEq7pGKkwmFXZP38rZs_CBM7vtBKtWY_ESX1_C7SmrucQJRa4sdrsbHA98-q1lQkoK-ZJnl3wZRoJ6xslEicxj9bpuRL20ZRd-kmXwPBSY0ldTcvkLHhKGrN7vMBmbmQDcnps2iH64BOWi-O-YKupGK70eO-YmYLZ3T85nlbttg.Mo9LyvjYVYzN6cl258MXrQ",
  "status": 403,
  "traceId": "00-67cb3e28086d1b4198cf96e8d37b495a-e76f80e2f9c51f4b-00"
}

Summary: Obtain a bearer token via password grant type login

HTTP Request

POST /api/v1/authentication/login

Request body

Attribute Type and description
email string
The username associated with a valid user account in SIERA
password string
The valid password associated with the username of the SIERA user account

Response Body

The response body will be either a token with expiration and lockout information, or error details of the failed attempt.

Attribute Type and description
token integer
A valid generated token which can be used in place of $ACCESS_TOKEN$ and passed as a bearer token
expiration datetime
The datetime which the token will expire
lockoutTimeRemaining integer
The amount of time in seconds before which a locked account can attempt a further login
maxRetriesExceeded integer
The number of times which have been attempted which caused the account to be temporarily locked
previousAccessFailedCount integer
On successful login, this will contain the number of previous failed attempts
type integer
The type of validation failure which occured
title string
The title of the failure
status integer
The error code associated with the failure
detail string
A description of the failure or further associated information

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
401 Unauthorized
403 User account has been locked or the password has expired
500 Server error

Assets

The Assets endpoints allow you to download asset data from SIERA. You can also upload new assets, update assets or delete them from a given instance in SIERA.

Get all assets

GET /api/v1/assets

curl https://api.sieraglobal.com/api/v1/assets \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

[
  {
    "assetId": 2,
    "assetName": "Chelsea House, London",
    "assetReference": "CHL-2",
    "country": "UnitedKingdom",
    "controlledBy": "Landlord",
    "sector": "Retail",
    "organisationId": 2,
    "fundId": 3,
    "gia": 1234,
    "nla": 1100,
    "cpa": 15,
    "ext": 100,
    "measurementType": "M2",
    "address": "1, The Way",
    "city": "Townington",
    "postcode": "AB12 3DC",
    "status": "MajorRefurbishment",
    "dateOfPurchase": "1999-01-01T00:00:00.000Z",
    "dateOfSale": "2021-03-14T00:00:00.000Z",
    "yearOfConstruction": 1985,
    "yearOfRefurbishment": 2006,
    "currentAssetValue": 1200000,
    "longitude": 51.507351,
    "latitude": -0.127758,
    "targetCarbon": 5,
    "targetEnergy": 1,
    "targetElectricity": 3,
    "targetFuelsAndThermals": 4,
    "targetWater": 6,
    "gresbSector": "Office",
    "carParkingSpaces": 14,
    "fri": true,
    "assetImageUri": "https://api.sieraglobal.com/api/v1/assets/2/assetimage"
  },
  {
    "assetId": 3,
    "assetName": "2-4 Sharwalk Building, Birmingham",
    "assetReference": "CHL-3",
    "country": "UnitedKingdom",
    "controlledBy": "Landlord",
    "sector": "Retail",
    "organisationId": 2,
    "fundId": 3,
    "gia": 1640,
    "nla": 1530,
    "cpa": 14,
    "ext": 121,
    "measurementType": "M2",
    "address": "2, The Way",
    "city": "Townington",
    "postcode": "AB12 3DC",
    "status": "MajorRefurbishment",
    "dateOfPurchase": "2000-01-01T00:00:00.000Z",
    "dateOfSale": "2021-03-19T00:00:00.000Z",
    "yearOfConstruction": 1985,
    "yearOfRefurbishment": 2007,
    "currentAssetValue": 1250000,
    "longitude": 51.507351,
    "latitude": -0.127758,
    "targetCarbon": 4,
    "targetEnergy": 3,
    "targetElectricity": 5,
    "targetFuelsAndThermals": 1,
    "targetWater": 6,
    "gresbSector": "Office",
    "carParkingSpaces": 18,
    "fri": false,
    "assetImageUri": "https://api.sieraglobal.com/api/v1/assets/3/assetimage"
  }
]

Summary: Provides a list of all assets in SIERA

HTTP Request

GET /api/v1/assets

Response Body

The response body will include a list of all assets in SIERA.

Attribute Type and description
assetId integer
The SIERA-generated id of the asset
assetName string
The name of the asset
assetReference string
The user-specified asset reference, unique within the API caller's SIERA instance
country enumeration
A valid country from the country enumeration
controlledBy enumeration
A valid item from the asset control enumeration showing who primarily is responsible for the asset, the landlord or the tenant
sector enumeration
A valid item from the sector enumeration indicating the property sector this asset belongs to
organisationId integer
The id value of an organisation which exists in the API-caller's SIERA instance
fundId integer
The id value of a fund which exists in the authorised user or API-caller's SIERA instance
gia integer
The Gross Internal Area (GIA) of the asset, measured in units indicated by the measurement type
nla integer
The Net Lettable Area (NLA) of the asset, measured in units indicated by the measurement type
cpa integer
The Common Part Areas (CPA) of the asset, measured in units indicated by the measurement type. For example, entrance lobbies, hallways and toilets
ext integer
The external areas of the asset, measured in units indicated by the measurement type. For example, car parks, outside eating areas and greenspace
measurementType enumeration
The unit of measurement used to indicate floor area of this asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
address string
The address of the asset
city string
The city of the asset
postcode string
The postcode of the asset
status enumeration
A valid item from the asset status enumeration indicates the current state of the asset in relation to its ability to be commercially occupied.
dateOfPurchase datetime
The date which the asset was purchased
dateOfSale datetime
The date which the asset was sold
yearOfConstruction integer
The year that the asset was built
yearOfRefurbishment integer
The year that the asset was refurbished
currentAssetValue integer
The current value of the asset in Great British Pounds (GBP)
longitude decimal
The decimal longitude coordinates of the asset location (to 6 decimal places)
latitude decimal
The decimal latitude coordinates of the asset location (to 6 decimal places)
targetCarbon float
The target percentage for the annual reduction of carbon usage for all meters on the asset
targetEnergy float
The target percentage for the annual reduction of energy usage for all meters on the asset
targetElectricity float
The target percentage for the annual reduction of electricity usage for all meters on the asset
targetFuelsAndThermals float
The target percentage for the annual reduction of fuels & thermals usage for all meters on the asset
targetWater float
The target percentage for the annual reduction of water usage for all meters on the asset
gresbSector enumeration
A valid item from the GRESB sector enumeration indicating how the asset is classified for GRESB certification
carParkingSpaces integer
The number of car parking spaces available at the asset
fri boolean
A boolean flag indicating if the current lease is Full Repairing and Insuring (FRI) or not
assetImageUri string
A URI of a downloadable image for the asset

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
500 Server error

Get an asset

GET /api/v1/assets/{assetId}

curl https://api.sieraglobal.com/api/v1/assets/2 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

{
  "assetId": 2,
  "assetName": "Chelsea House, London",
  "assetReference": "CHL-2",
  "country": "UnitedKingdom",
  "controlledBy": "Landlord",
  "sector": "Retail",
  "organisationId": 2,
  "fundId": 3,
  "gia": 1234,
  "nla": 1100,
  "cpa": 15,
  "ext": 100,
  "measurementType": "M2",
  "address": "1, The Way",
  "city": "Townington",
  "postcode": "AB12 3DC",
  "status": "MajorRefurbishment",
  "dateOfPurchase": "1999-01-01T00:00:00.000Z",
  "dateOfSale": "2021-03-14T00:00:00.000Z",
  "yearOfConstruction": 1985,
  "yearOfRefurbishment": 2006,
  "currentAssetValue": 1200000,
  "longitude": 51.507351,
  "latitude": -0.127758,
  "targetCarbon": 5,
  "targetEnergy": 1,
  "targetElectricity": 3,
  "targetFuelsAndThermals": 4,
  "targetWater": 6,
  "gresbSector": "Office",
  "carParkingSpaces": 14,
  "fri": true,
  "assetImageUri": "https://myapi.com/api/v1/Assets/2/AssetImage"
}

Response (201)

Summary: Provides a single asset given an ID

HTTP Request

GET /api/v1/assets/{assetId}

Parameters

Name Located in Description Required Type
assetId path A valid id of an asset stored in SIERA Yes integer

Response Body

The response body will the specified asset which matches the assetId given as a parameter.

Attribute Type and description
assetId integer
The SIERA-generated id of the asset
assetName string
The name of the asset
assetReference string
The user-specified asset reference, unique within the API caller's SIERA instance
country enumeration
A valid country from the country enumeration
controlledBy enumeration
A valid item from the asset control enumeration showing who primarily is responsible for the asset, the landlord or the tenant
sector enumeration
A valid item from the sector enumeration indicating the property sector this asset belongs to
organisationId integer
The id value of an organisation which exists in the API-caller's SIERA instance
fundId integer
The id value of a fund which exists in the authorised user or API-caller's SIERA instance
gia integer
The Gross Internal Area (GIA) of the asset, measured in units indicated by the measurement type
nla integer
The Net Lettable Area (NLA) of the asset, measured in units indicated by the measurement type
cpa integer
The Common Part Areas (CPA) of the asset, measured in units indicated by the measurement type. For example, entrance lobbies, hallways and toilets
ext integer
The external areas of the asset, measured in units indicated by the measurement type. For example, car parks, outside eating areas and greenspace
measurementType enumeration
The unit of measurement used to indicate floor area of this asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
address string
The address of the asset
city string
The city of the asset
postcode string
The postcode of the asset
status enumeration
A valid item from the asset status enumeration indicates the current state of the asset in relation to its ability to be commercially occupied.
dateOfPurchase datetime
The date which the asset was purchased
dateOfSale datetime
The date which the asset was sold
yearOfConstruction integer
The year that the asset was built
yearOfRefurbishment integer
The year that the asset was refurbished
currentAssetValue integer
The current value of the asset in Great British Pounds (GBP)
longitude integer
The decimal longitude coordinates of the asset location (to 6 decimal places)
latitude integer
The decimal latitude coordinates of the asset location (to 6 decimal places)
targetCarbon float
The target percentage for the annual reduction of carbon usage for all meters on the asset
targetEnergy float
The target percentage for the annual reduction of energy usage for all meters on the asset
targetElectricity float
The target percentage for the annual reduction of electricity usage for all meters on the asset
targetFuelsAndThermals float
The target percentage for the annual reduction of fuels & thermals usage for all meters on the asset
targetWater float
The target percentage for the annual reduction of water usage for all meters on the asset
gresbSector enumeration
A valid item from the GRESB sector enumeration indicating how the asset is classified for GRESB certification
carParkingSpaces integer
The number of car parking spaces available at the asset
fri boolean
A boolean flag indicating if the current lease is Full Repairing and Insuring (FRI) or not
assetImageUri string
A URI of a downloadable image for the asset

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the specified asset id was not found
500 Server error

Upload a new asset

POST /api/v1/assets

curl POST https://api.sieraglobal.com/api/v1/assets \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON
  { 
    "assetName": "Chelsea House, London",
    "assetReference": "CHL-2",
    "country": "UnitedKingdom",
    "controlledBy": "Landlord",
    "sector": "Retail",
    "organisationId": 2,
    "fundId": 3,
    "gia": 1234,
    "nla": 1100,
    "cpa": 15,
    "ext": 100,
    "measurementType": "M2",
    "address": "1, The Way",
    "city": "Townington",
    "postcode": "AB12 3DC",
    "status": "MajorRefurbishment",
    "dateOfPurchase": "1999-01-01T00:00:00.000Z",
    "dateOfSale": "2021-03-14T00:00:00.000Z",
    "yearOfConstruction": 1985,
    "yearOfRefurbishment": 2006,
    "currentAssetValue": 1200000,
    "longitude": 51.507351,
    "latitude": -0.127758,
    "targetCarbon": 5,
    "targetEnergy": 1,
    "targetElectricity": 3,
    "targetFuelsAndThermals": 4,
    "targetWater": 6,
    "gresbSector": "Office",
    "carParkingSpaces": 14,
    "fri": true
  }

Response (201)

{
  "assetId": 3
}

Summary: Uploads a new asset

HTTP Request

POST /api/v1/assets

Request body

Attribute Type and description
assetName string
The name of the asset
assetReference string
The user-specified asset reference, unique within the API caller's SIERA instance
country enumeration
A valid country from the country enumeration
controlledBy enumeration
A valid item from the asset control enumeration showing who primarily is responsible for the asset, the landlord or the tenant
sector enumeration
A valid item from the sector enumeration indicating the property sector this asset belongs to
organisationId integer
The id value of an organisation which exists in the API-caller's SIERA instance
fundId integer
The id value of a fund which exists in the authorised user or API-caller's SIERA instance
gia float
The Gross Internal Area (GIA) of the asset, measured in units indicated by the measurement type. This may be null
nla float
The Net Lettable Area (NLA) of the asset, measured in units indicated by the measurement type. This may be null
cpa integer
The Common Part Areas (CPA) of the asset, measured in units indicated by the measurement type. For example, entrance lobbies, hallways and toilets
ext integer
The external areas of the asset, measured in units indicated by the measurement type. For example, car parks, outside eating areas and greenspace
measurementType enumeration
The unit of measurement used to indicate floor area of this asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
address string
The address of the asset
city string
The city of the asset
postcode string
The postcode of the asset
status enumeration
A valid item from the asset status indicates the current state of the asset in relation to its ability to be commercially occupied.
dateOfPurchase datetime
The date which the asset was purchased
dateOfSale datetime
The date which the asset was sold
yearOfConstruction integer
The year that the asset was built
yearOfRefurbishment integer
The year that the asset was refurbished
currentAssetValue integer
The current value of the asset in Great British Pounds (GBP)
longitude decimal
The decimal longitude coordinates of the asset location (to 6 decimal places)
latitude decimal
The decimal latitude coordinates of the asset location (to 6 decimal places)
targetCarbon float
The target percentage for the annual reduction of carbon usage for all meters on the asset
targetEnergy float
The target percentage for the annual reduction of energy usage for all meters on the asset
targetElectricity float
The target percentage for the annual reduction of electricity usage for all meters on the asset
targetFuelsAndThermals float
The target percentage for the annual reduction of fuels & thermals usage for all meters on the asset
targetWater float
The target percentage for the annual reduction of water usage for all meters on the asset
gresbSector enumeration
A valid item from the GRESB sector enumeration indicating how the asset is classified for GRESB certification
carParkingSpaces integer
The number of car parking spaces available at the asset
fri boolean
A boolean flag indicating if the current lease is Full Repairing and Insuring (FRI) or not

Response Body

The response body will a new asset ID relating to the uploaded asset

Attribute Type and description
assetId integer
The SIERA-generated id of the new asset

Responses

Code Description
201 Created
400 Validation failure
401 Unauthorised, the header token expired or is missing
500 Server error

Update an asset

PUT /api/v1/assets/{assetId}

curl PUT https://api.sieraglobal.com/api/v1/assets/2 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON
  { 
    "assetName": "Birmingham House, London",
    "assetReference": "CHL-3",
    "country": "UnitedKingdom",
    "controlledBy": "Landlord",
    "sector": "Retail",
    "organisationId": 2,
    "fundId": 3,
    "gia": 1234,
    "nla": 1100,
    "cpa": 14,
    "ext": 121,
    "measurementType": "M2",
    "address": "2, The Way",
    "city": "Townington",
    "postcode": "AB12 3DC",
    "status": "MajorRefurbishment",
    "dateOfPurchase": "2000-01-01T00:00:00.000Z",
    "dateOfSale": "2021-03-19T00:00:00.000Z",
    "yearOfConstruction": 1985,
    "yearOfRefurbishment": 2007,
    "currentAssetValue": 1250000,
    "longitude": 51.507351,
    "latitude": -0.127758,
    "targetCarbon": 4,
    "targetEnergy": 3,
    "targetElectricity": 5,
    "targetFuelsAndThermals": 1,
    "targetWater": 6,
    "gresbSector": "Office",
    "carParkingSpaces": 18,
    "fri": false
  }

Response (200)

Summary: Updates an existing asset by ID

HTTP Request

PUT /api/v1/assets/{assetId}

Parameters

Name Located in Description Required Type
assetId path The id of the asset to be updated in SIERA Yes integer

Request body

Attribute Type and description
assetName string
The name of the asset
assetReference string
The user-specified asset reference, unique within the API caller's SIERA instance
country enumeration
A valid country from the country enumeration
controlledBy enumeration
A valid item from the asset control enumeration showing who primarily is responsible for the asset, the landlord or the tenant
sector enumeration
A valid item from the sector enumeration indicating the property sector this asset belongs to
organisationId integer
The id value of an organisation which exists in the API-caller's SIERA instance
fundId integer
The id value of a fund which exists in the authorised user or API-caller's SIERA instance
gia integer
The Gross Internal Area (GIA) of the asset, measured in units indicated by the measurement type
nla integer
The Net Lettable Area (NLA) of the asset, measured in units indicated by the measurement type
cpa integer
The Common Part Areas (CPA) of the asset, measured in units indicated by the measurement type. For example, entrance lobbies, hallways and toilets
ext integer
The external areas of the asset, measured in units indicated by the measurement type. For example, car parks, outside eating areas and greenspace
measurementType enumeration
The unit of measurement used to indicate floor area of this asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
address string
The address of the asset
city string
The city of the asset
postcode string
The postcode of the asset
status enumeration
A valid item from the asset status enumeration indicates the current state of the asset in relation to its ability to be commercially occupied.
dateOfPurchase datetime
The date which the asset was purchased
dateOfSale datetime
The date which the asset was sold
yearOfConstruction integer
The year that the asset was built
yearOfRefurbishment integer
The year that the asset was refurbished
currentAssetValue integer
The current value of the asset in Great British Pounds (GBP)
longitude decimal
The decimal longitude coordinates of the asset location (to 6 decimal places)
latitude decimal
The decimal latitude coordinates of the asset location (to 6 decimal places)
targetCarbon float
The target percentage for the annual reduction of carbon usage for all meters on the asset
targetEnergy float
The target percentage for the annual reduction of energy usage for all meters on the asset
targetElectricity float
The target percentage for the annual reduction of electricity usage for all meters on the asset
targetFuelsAndThermals float
The target percentage for the annual reduction of fuels & thermals usage for all meters on the asset
targetWater float
The target percentage for the annual reduction of water usage for all meters on the asset
gresbSector enumeration
A valid item from the GRESB sector enumeration indicating how the asset is classified for GRESB certification
carParkingSpaces integer
The number of car parking spaces available at the asset
fri boolean
A boolean flag indicating if the current lease is Full Repairing and Insuring (FRI) or not
assetImageUri string
This URI is for the endpoint where the asset image can be downloaded

Responses

Code Description
200 OK
400 Validation failure
401 Unauthorised, the header token expired or is missing
404 Not found, the specified asset id was not found
500 Server error

Delete an asset

DELETE /api/v1/assets/{assetId}

curl -X DELETE https://api.sieraglobal.com/api/v1/assets/2 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

Summary: Deletes an existing asset by ID

HTTP Request

DELETE /api/v1/assets/{assetId}

Parameters

Name Located in Description Required Type
assetId path The id of the asset to be deleted in SIERA Yes integer

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the specified asset id was not found
500 Server error

Get all meters for an asset

GET /api/v1/assets/{assetId}/meters

curl https://api.sieraglobal.com/api/v1/assets/2/meters \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

[
  {
    "meterId": 11,
    "assetId": 2,
    "unitId": 1,
    "mpan": "S018011012261305588165",
    "serialNumber": "1875258102",
    "comment": "",
    "supplier": "EON",
    "areaCovered": "SharedServices",
    "controlledBy": "Landlord",
    "floorAreaServed": 730,
    "meterType": "Electricity",
    "generationType": "NationalGrid",
    "measurementType": "M2",
    "locationCarbonFactorId": 0,
    "marketCarbonFactorId": 0,
    "unitRateId": 1,
    "isActive": true,
    "isAMR": false,
    "isSubmeter": false,
    "isValidated": true,
    "isROC": false,
    "isFIT": false,
    "isCCA": false,
    "isEUETS": false,
    "hasHalfHourData": false
  },
  {
    "meterId": 12,
    "assetId": 2,
    "unitId": 2,
    "mpan": "S018005012341305549165",
    "serialNumber": "1815248121",
    "comment": "",
    "supplier": "EON",
    "areaCovered": "WholeBuilding",
    "controlledBy": "Landlord",
    "floorAreaServed": 1100,
    "meterType": "Gas",
    "generationType": "NationalGrid",
    "measurementType": "M2",
    "locationCarbonFactorId": 0,
    "marketCarbonFactorId": 0,
    "unitRateId": 2,
    "isActive": true,
    "isAMR": false,
    "isSubmeter": false,
    "isValidated": false,
    "isROC": false,
    "isFIT": false,
    "isCCA": false,
    "isEUETS": false,
    "hasHalfHourData": false
  }
]

Summary Provides all meters given an asset ID

HTTP Request

GET /api/v1/assets/{assetId}/meters

Parameters

Name Located in Description Required Type
assetId path A valid id of an asset stored in SIERA Yes integer

Response Body

The response body will be a list of meters which are associated with the asset specified by the assetId parameter.

Attribute Type and description
meterId integer
The SIERA-generated id of the meter
assetId integer
The SIERA-generated id of the associated asset
unitId integer
The SIERA-generated id of any associated unit
mpan string
The meter point administration number (MPAN) of the meter
serialNumber string
The serial number of the meter
comment string
A free-text description relating to the meter
supplier string
Any utilities supplier related to the meter
areaCovered enumeration
A valid area of the property which this meter covers, from the area covered enumeration
controlledBy enumeration
A valid item from the asset control enumeration showing who primarily pays for the energy from this meter, the landlord or the tenant
floorAreaServed integer
The floor area covered by this meter
meterType enumeration
A valid utility of the meter from the meter type enumeration
generationType enumeration
A valid generation type of the meter from the generation type enumeration
measurementType enumeration
The unit of measurement used to indicate floor area of this asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
locationCarbonFactorId integer
The id value of an location-based carbon factor Id which exists in the API-caller's SIERA instance, or one of the default carbon factors provided by Evora
marketCarbonFactorId integer
The id value of an market-based carbon factor Id which exists in the API-caller's SIERA instance, or one of the default carbon factors provided by Evora
unitRateId integer
The id value of a cost unit rate Id which exists in the API-caller's SIERA instance, or one of the default unit rates provided by Evora
isActive boolean
A boolean flag indicating if this meter is considered active and currently in use or not.
isAMR boolean
A boolean flag indicating if this meter's readings are being retrieved by automatic meter reading or not.
isSubmeter boolean
A boolean flag indicating if this meter isa sub-meter or not
isValidated boolean
A boolean flag indicating if this meter has been validated or not.
isROC boolean
A boolean flag indicating if this meter has an Renewables Obligation Certificate generation meter which measures total electricity produced by solar panel or not.
isFIT boolean
A boolean flag indicating if this meter is a Feed-In-Time tariff (relating to solar panels) or not.
isCCA boolean
A boolean flag indicating if this meter is part of a Community Choice Aggregation or not.
isEUETS boolean
A boolean flag indicating if this meter is part of the EU Energy Trading System or not.
hasHalfHourData boolean
A boolean flag indicating if this meter has received half-hourly data or not.

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the specified asset was not found
500 Server error

Get all waste destinations for an asset

GET /api/v1/assets/{assetId}/wastedestinations

curl https://api.sieraglobal.com/api/v1/assets/2/wastedestinations \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)


[
    {
      "assetId": 2,
      "wasteDestinationId": 2,
      "wasteDestinationDescription": "Mixed Recycleables",
      "comments": "Recycling for Chelsea House, London",
      "contractor": "Veolia",
      "reference": "Reference 1000022",
      "wasteDestination": "Recycled"
    },
    {
      "assetId": 2,
      "wasteDestinationId": 3,
      "wasteDestinationDescription": "General Waste",
      "comments": "General Waste for Chelsea House, London",
      "contractor": "Veolia",
      "reference": "Reference 1000023",
      "wasteDestination": "Landfill"
    }
]

Summary: Provides all waste destinations given an asset ID

HTTP Request

GET /api/v1/assets/{assetId}/wastedestinations

Response Body

The response body will be a list of waste destinations which are associated with the asset specified by the assetId parameter.

Attribute Type and description
assetId integer
The id of the asset
wasteDestinationId integer
The SIERA-generated id of the waste destination
wasteDestinationDescription string
A description of the waste destination
comments string
Comments relating to the waste destination
contractor string
The name of the contractor providing the waste service
reference string
A reference for the waste destination on the asset
wasteDestination enumeration
A valid destination type from the waste destination enumeration

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the specified asset was not found
500 Server error

Get all action plans for an asset

GET /api/v1/assets/{assetId}/actionplans

curl https://api.sieraglobal.com/api/v1/assets/2/actionplans \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)


[
    {
        "actionId": 2,
        "assetId": 2,
        "actionDescription": "Upgrade lighting to LED",
        "impact": "Energy",
        "approved": true,
        "status": "AgreedActions",
        "current": 350,
        "target": 200,
        "cost": "Low",
        "costType": "RevenueServiceCharge",
        "scope": "WholeBuilding",
        "manager": "Jeff Parsons",
        "completion": "",
        "dueDate": "9/1/2022",
        "currency": "GBP",
        "utilityType": "NotApplicable",
        "performanceMeasure": "InstallationOfHighEfficiencyEquipment",
        "targetUsagePercentage": 42.86
    },
    {
        "actionId": 3,
        "assetId": 2,
        "actionDescription": "Replace southfacing windows with high-efficiency glazing",
        "impact": "Energy",
        "approved": true,
        "status": "AgreedActions",
        "current": 600,
        "target": 300,
        "cost": "12000",
        "costType": "RevenueServiceCharge",
        "scope": "WholeBuilding",
        "manager": "Jeff Parsons",
        "completion": "",
        "dueDate": "9/1/2022",
        "currency": "GBP",
        "utilityType": "NotApplicable",
        "performanceMeasure": "WindowReplacements",
        "targetUsagePercentage": 50
    },
]

Summary: Provides all action plans given an asset ID

HTTP Request

GET /api/v1/assets/{assetId}/actionplans

Parameters

Name Located in Description Required Type
assetId path A valid id of an asset stored in SIERA Yes integer

Response Body

The response body will be a list of action plans which are associated with the asset specified by the assetId parameter.

Attribute Type and description
actionId integer
The id of the action plan
assetId integer
The id of the asset
actionDescription string
A description of the action plan
impact string
The utility or utility group affected by the action
approved boolean
A boolean flag to indicate if the action plan has been approved or not
status enumeration
A valid action status from the action status enumeration
current float
The current usage amount related to this action
target float
A target usage the action is hoped to achieve
cost string
A text description of the costs of the action. This can be a number amount or relative description such as high or low.
costType enumeration
A valid cost type from the action cost type enumeration
scope enumeration
A valid floor area scope from the action scope enumeration
manager string
The name of a person who is considered the manager of this action
completion datetime
The actual completion date of the action, in the format m/d/yyyy
dueDate datetime
The expected completion date of the action, in the format m/d/yyyy
currency string
The currency of the costs related to the action, of GBP, USD or EUR.
utilityType enumeration
A valid utility from the action utility enumeration
performanceMeasure enumeration
A valid measure description from the action measure description enumeration
targetUsagePercentage float
A read-only percentage change between the current and target values of the action

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the specified asset was not found
500 Server error

Get all asset units for an asset

GET /api/v1/assets/{assetId}/assetunits

curl https://api.sieraglobal.com/api/v1/assets/2/assetsunits \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

[
  {
    "unitId": 12,
    "unitName": "Unit A",
    "unitReference": "TAC-234",
    "occupier": "Pets At Home",
    "actionNotes": "",
    "gia": 1100,
    "nla": 900,
    "measurementUnit": "M2",
    "vacant": false,
    "leaseStart": "2020-12-17T12:00:00.000Z",
    "leaseLength": 24,
    "leaseExpiry": "2022-12-17T12:00:00.000Z",
    "leaseBreak": "",
    "erv": 1200,
    "fri": false,
    "epcExempt": false
  },
  {
    "unitId": 13,
    "unitName": "Unit B",
    "unitReference": "TAC-235",
    "occupier": "Asda Home",
    "actionNotes": "",
    "gia": 1050,
    "nla": 800,
    "measurementUnit": "M2",
    "vacant": false,
    "leaseStart": "2021-11-21T12:00:00.000Z",
    "leaseLength": 24,
    "leaseExpiry": "2023-12-21T12:00:00.000Z",
    "leaseBreak": "2022-12-17T12:00:00.000Z",
    "erv": 900,
    "fri": false,
    "epcExempt": false
  }
]

Summary: Provides all asset units given an asset ID

HTTP Request

GET /api/v1/assets/{assetId}/assetunits

Parameters

Name Located in Description Required Type
assetId path The id of the asset associated with the unit Yes integer

Response Body

The response body will include a list of all assets in SIERA which are associated with the asset specified by the assetId parameter.

Attribute Type and description
unitId integer
The SIERA-generated id of the asset unit
unitName string
The name of the asset unit
unitReference string
The asset unit reference
occupier string
The name of the current occupier of the unit
gia float
The Gross Internal Area (GIA) of the asset, measured in units indicated by the measurement unit. This may be null
nla float
The Net Lettable Area (NLA) of the asset, measured in units indicated by the measurement unit. This may be null
measurementUnit enumeration
The unit of measurement used to indicate floor area of this asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
leaseStart datetime
The start date of the tenant of this unit's lease
leaseLength integer
The length in months of the tenant of this unit's lease
leaseExpiry datetime
The expiry date of the tenant of this unit's lease
leaseBreak datetime
The start date of a break in the tenant of this unit's lease
erv float
The estimated rental value (ERV) of this unit
fri boolean
A boolean flag indicating if the current lease is Full Repairing and Insuring (FRI) or not
epcExempt boolean
A boolean flag indicating if this unit has an EPC exemption or not

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the specified asset was not found
500 Server error

Get an asset image

Summary The response will return a file, if one is found for the given asset ID.

HTTP Request

GET /api/v1/assets/{assetId}/assetimage

Parameters

Name Located in Description Required Type
assetId path A valid id of an asset stored in SIERA Yes integer

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the specified asset was not found
500 Server error

Validation rules

When uploading new assets or updating existing, SIERA will apply the following rules and if they are not met, a response of 400 will be returned with an error message and the field causing the validation failure.

The validation requirements for assets are:

  1. When uploading a new asset, the assetId must be 0 or null.
  2. When updating an asset, the assetId must be of an existing asset in SIERA.
  3. The assetReference must be unique. Validation will fail if any other asset has the same reference.
  4. The organisationId must already exist in SIERA.
  5. The fundId must already exist in SIERA.
  6. The dateOfPurchase (if present) must be before the dateOfSale (if present).

Asset Units

In SIERA asset units represent sub-units of assets, properties or sites, for example shops in a shopping centre. The assets units endpoints allow you to download asset unit data from SIERA. You can also upload new asset unit, update asset units or delete them from a given instance in SIERA.

An asset unit must be associated with a valid asset in the API-caller's SIERA instance.

Get all asset units

GET /api/v1/assetunits

curl https://api.sieraglobal.com/api/v1/assetsunits \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

[
  {
    "unitId": 12,
    "assetId": 2, 
    "unitName": "Unit A",
    "unitReference": "TAC-234",
    "occupier": "Pets At Home",
    "actionNotes": "",
    "gia": 1100,
    "nla": 900,
    "measurementUnit": "M2",
    "vacant": false,
    "leaseStart": "2020-12-17T12:00:00.000Z",
    "leaseLength": 24,
    "leaseExpiry": "2022-12-17T12:00:00.000Z",
    "leaseBreak": "",
    "erv": 1200,
    "fri": false,
    "epcExempt": false
  },
  {
    "unitId": 13,
    "assetId": 2, 
    "unitName": "Unit B",
    "unitReference": "TAC-235",
    "occupier": "Asda Home",
    "actionNotes": "",
    "gia": 1050,
    "nla": 800,
    "measurementUnit": "M2",
    "vacant": false,
    "leaseStart": "2021-11-21T12:00:00.000Z",
    "leaseLength": 24,
    "leaseExpiry": "2023-12-21T12:00:00.000Z",
    "leaseBreak": "2022-12-17T12:00:00.000Z",
    "erv": 900,
    "fri": false,
    "epcExempt": false
  }
]

Summary: Provides a list of all asset units

HTTP Request

GET /api/v1/assetunits

Response Body

The response body will include a list of all assets in SIERA.

Attribute Type and description
unitId integer
The SIERA-generated id of the asset unit
assetId integer
The id of the asset associated with the unit
unitName string
The name of the asset unit
unitReference string
The asset unit reference
occupier string
The name of the current occupier of the unit
gia float
The Gross Internal Area (GIA) of the asset, measured in units indicated by the measurement unit. This may be null
nla float
The Net Lettable Area (NLA) of the asset, measured in units indicated by the measurement unit. This may be null
measurementUnit enumeration
The unit of measurement used to indicate floor area of this asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
leaseStart datetime
The start date of the tenant of this unit's lease
leaseLength integer
The length in months of the tenant of this unit's lease
leaseExpiry datetime
The expiry date of the tenant of this unit's lease
leaseBreak datetime
The start date of a break in the tenant of this unit's lease
erv float
The estimated rental value (ERV) of this unit
fri boolean
A boolean flag indicating if the current lease is Full Repairing and Insuring (FRI) or not
epcExempt boolean
A boolean flag indicating if this unit has an EPC exemption or not

Get an asset unit

GET /api/v1/assetunits/{unitId}

curl https://api.sieraglobal.com/api/v1/assetunits/13 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

{
  "unitId": 13,
  "assetId": 2, 
  "unitName": "Unit B",
  "unitReference": "TAC-235",
  "occupier": "Asda Home",
  "actionNotes": "",
  "gia": 1050,
  "nla": 800,
  "measurementUnit": "M2",
  "vacant": false,
  "leaseStart": "2021-11-21T12:00:00.000Z",
  "leaseLength": 24,
  "leaseExpiry": "2023-12-21T12:00:00.000Z",
  "leaseBreak": "2022-12-17T12:00:00.000Z",
  "erv": 900,
  "fri": false,
  "epcExempt": false
}

Summary: Provides a single asset unit given a unitId

HTTP Request

GET /api/v1/assetunits/{unitId}

Parameters

Name Located in Description Required Type
unitId path A valid id of an asset unit stored in SIERA Yes integer

Response Body

The response body will the specified asset unit which matches the unitId given as a parameter.

Attribute Type and description
unitId integer
The SIERA-generated id of the asset unit
assetId integer
The id of the asset associated with the unit
unitName string
The name of the asset unit
unitReference string
The asset unit reference
occupier string
The name of the current occupier of the unit
gia float
The Gross Internal Area (GIA) of the asset, measured in units indicated by the measurement unit. This may be null
nla float
The Net Lettable Area (NLA) of the asset, measured in units indicated by the measurement unit. This may be null
measurementUnit enumeration
The unit of measurement used to indicate floor area of this asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
leaseStart datetime
The start date of the tenant of this unit's lease
leaseLength integer
The length in months of the tenant of this unit's lease
leaseExpiry datetime
The expiry date of the tenant of this unit's lease
leaseBreak datetime
The start date of a break in the tenant of this unit's lease
erv float
The estimated rental value (ERV) of this unit
fri boolean
A boolean flag indicating if the current lease is Full Repairing and Insuring (FRI) or not
epcExempt boolean
A boolean flag indicating if this unit has an EPC exemption or not

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the specified asset id or unit id was not found
500 Server error

Upload a new asset unit

POST /api/v1/assetunits

curl POST https://api.sieraglobal.com/api/v1/assetunits \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON
  {
    "unitId": 14,
    "assetId": 2,
    "unitName": "Unit C",
    "unitReference": "TAC-236",
    "occupier": "Next",
    "actionNotes": "",
    "gia": 2000,
    "nla": 1900,
    "measurementUnit": "M2",
    "vacant": false,
    "leaseStart": "2020-11-21T12:00:00.000Z",
    "leaseLength": 36,
    "leaseExpiry": "2023-12-21T12:00:00.000Z",
    "leaseBreak": "",
    "erv": 1600,
    "fri": false,
    "epcExempt": false
  }

Response (201)

  {
    "unitId": 2,
    "unitName": "Unit C",
    "unitReference": "TAC-236"
  }

Summary: Uploads a new asset unit

HTTP Request

POST /api/v1/assetunits

Request body

Attribute Type and description
unitId integer
The SIERA-generated id of the asset unit
assetId integer
The id of the asset associated with the unit
unitName string
The name of the asset unit
unitReference string
The asset unit reference
occupier string
The name of the current occupier of the unit
gia float
The Gross Internal Area (GIA) of the asset, measured in units indicated by the measurement unit. This may be null
nla float
The Net Lettable Area (NLA) of the asset, measured in units indicated by the measurement unit. This may be null
measurementUnit enumeration
The unit of measurement used to indicate floor area of this asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
leaseStart datetime
The start date of the tenant of this unit's lease
leaseLength integer
The length in months of the tenant of this unit's lease
leaseExpiry datetime
The expiry date of the tenant of this unit's lease
leaseBreak datetime
The start date of a break in the tenant of this unit's lease
erv float
The estimated rental value (ERV) of this unit
fri boolean
A boolean flag indicating if the current lease is Full Repairing and Insuring (FRI) or not
epcExempt boolean
A boolean flag indicating if this unit has an EPC exemption or not

Response Body

The response body will a new unit ID relating to the uploaded asset unit, along with its name and reference

Attribute Type and description
unitId integer
The SIERA-generated id of the new asset unit
unitName string
The name of the asset unit
unitReference string
The asset unit reference

Responses

Code Description
201 Created
400 Validation failure
401 Unauthorised, the header token expired or is missing
500 Server error

Update an asset unit

PUT /api/v1/assetunits/{unitId}

curl PUT https://api.sieraglobal.com/api/v1/assetunits/14 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON
  [
    {
      "unitId": 14
      "unitName": "Unit C",
      "unitReference": "TAC-236",
      "occupier": "Next",
      "actionNotes": "",
      "gia": 2000,
      "nla": 1900,
      "measurementUnit": "M2",
      "vacant": false,
      "leaseStart": "2020-11-21T12:00:00.000Z",
      "leaseLength": 36,
      "leaseExpiry": "2023-12-21T12:00:00.000Z",
      "leaseBreak": "",
      "erv": 1900,
      "fri": false,
      "epcExempt": false
    }
  ]

Response (200)

Summary: Updates an existing asset unit by ID

HTTP Request

PUT /api/v1/assetunits/{unitId}

Parameters

Name Located in Description Required Type
unitId path A valid id of an asset unit stored in SIERA Yes integer

Request body

The body is a unit to be updated.

Attribute Type and description
unitId integer
The SIERA-generated id of the asset unit
assetId integer
The id of the asset associated with the unit
unitName string
The name of the asset unit
unitName string
The name of the asset unit
unitReference string
The asset unit reference
occupier string
The name of the current occupier of the unit
gia float
The Gross Internal Area (GIA) of the asset, measured in units indicated by the measurement unit. This may be null
nla float
The Net Lettable Area (NLA) of the asset, measured in units indicated by the measurement unit. This may be null
measurementUnit enumeration
The unit of measurement used to indicate floor area of this asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
leaseStart datetime
The start date of the tenant of this unit's lease
leaseLength integer
The length in months of the tenant of this unit's lease
leaseExpiry datetime
The expiry date of the tenant of this unit's lease
leaseBreak datetime
The start date of a break in the tenant of this unit's lease
erv float
The estimated rental value (ERV) of this unit
fri boolean
A boolean flag indicating if the current lease is Full Repairing and Insuring (FRI) or not
epcExempt boolean
A boolean flag indicating if this unit has an EPC exemption or not

Responses

Code Description
200 OK
400 Validation failure
401 Unauthorised, the header token expired or is missing
500 Server error

Update multiple asset units

PUT /api/v1/assetunits

curl PUT https://api.sieraglobal.com/api/v1/assetunits \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON
  [
    {
      "unitId": 14
      "unitName": "Unit C",
      "unitReference": "TAC-236",
      "occupier": "Next",
      "actionNotes": "",
      "gia": 2000,
      "nla": 1900,
      "measurementUnit": "M2",
      "vacant": false,
      "leaseStart": "2020-11-21T12:00:00.000Z",
      "leaseLength": 36,
      "leaseExpiry": "2023-12-21T12:00:00.000Z",
      "leaseBreak": "",
      "erv": 1900,
      "fri": false,
      "epcExempt": false
    }
  ]

Response (200)

Summary: Updates an existing asset unit by ID

HTTP Request

PUT /api/v1/assetunits

Request body

The body is a list of one or more units to be updated.

Attribute Type and description
unitId integer
The SIERA-generated id of the asset unit
assetId integer
The id of the asset associated with the unit
unitName string
The name of the asset unit
unitName string
The name of the asset unit
unitReference string
The asset unit reference
occupier string
The name of the current occupier of the unit
gia float
The Gross Internal Area (GIA) of the asset, measured in units indicated by the measurement unit. This may be null
nla float
The Net Lettable Area (NLA) of the asset, measured in units indicated by the measurement unit. This may be null
measurementUnit enumeration
The unit of measurement used to indicate floor area of this asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
leaseStart datetime
The start date of the tenant of this unit's lease
leaseLength integer
The length in months of the tenant of this unit's lease
leaseExpiry datetime
The expiry date of the tenant of this unit's lease
leaseBreak datetime
The start date of a break in the tenant of this unit's lease
erv float
The estimated rental value (ERV) of this unit
fri boolean
A boolean flag indicating if the current lease is Full Repairing and Insuring (FRI) or not
epcExempt boolean
A boolean flag indicating if this unit has an EPC exemption or not

Responses

Code Description
200 OK
400 Validation failure
401 Unauthorised, the header token expired or is missing
500 Server error

Delete an asset unit

DELETE /api/v1/assetunits/{assetId}/units/{unitId}

curl -X DELETE https://api.sieraglobal.com/api/v1/assetunits/2/units/13 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

Summary: Deletes an existing asset unit by ID

HTTP Request

DELETE /api/v1/assetsunits/{unitId}

Parameters

Name Located in Description Required Type
unitId path A valid id of an asset unit stored in SIERA Yes integer

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the specified asset unit id was not found
500 Server error

Validation rules

When uploading new asset units or updating existing, SIERA will apply the following rules and if they are not met, a response of 400 will be returned with an error message and the field causing the validation failure.

The validation requirements for assets units are:

  1. When uploading a new asset unit, the unitId must be 0 or null.
  2. When updating an asset unit, the unitId must be of an existing asset unit in SIERA.
  3. The unitReference must be unique. Validation will fail if any other asset unit has the same reference.
  4. The leaseStart must be before leaseExpiry.
  5. The leaseBreak date must be after the leaseStart date (if present).
  6. The leaseBreak date must be before the leaseExpiry date (if present).

Meters

The Meters endpoints allow you to manage utility meters associated with assets in SIERA. You can upload new meters, update meters or delete them from a given instance in SIERA. Note that a meter must be associated with an asset and can't exist on its own.

Get all meters

GET /api/v1/meters

curl https://api.sieraglobal.com/api/v1/meters \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)


[
  {
    "meterId": 11,
    "assetId": 2,
    "unitId": 1,
    "mpan": "S018011012261305588165",
    "serialNumber": "1875258102",
    "comment": "",
    "supplier": "EON",
    "areaCovered": "SharedServices",
    "controlledBy": "Landlord",
    "floorAreaServed": 730,
    "meterType": "Electricity",
    "generationType": "NationalGrid",
    "measurementType": "M2",
    "locationCarbonFactorId": 0,
    "marketCarbonFactorId": 0,
    "unitRateId": 1,
    "isActive": true,
    "isAMR": false,
    "isSubmeter": false,
    "isValidated": true,
    "isROC": false,
    "isFIT": false,
    "isCCA": false,
    "isEUETS": false,
    "hasHalfHourData": false
  },
  {
    "meterId": 12,
    "assetId": 2,
    "unitId": 2,
    "mpan": "S018005012341305549165",
    "serialNumber": "1815248121",
    "comment": "",
    "supplier": "EON",
    "areaCovered": "WholeBuilding",
    "controlledBy": "Gas",
    "floorAreaServed": 1100,
    "meterType": "Gas",
    "generationType": "NationalGrid",
    "measurementType": "M2",
    "locationCarbonFactorId": 0,
    "marketCarbonFactorId": 0,
    "unitRateId": 2,
    "isActive": true,
    "isAMR": false,
    "isSubmeter": false,
    "isValidated": false,
    "isROC": false,
    "isFIT": false,
    "isCCA": false,
    "isEUETS": false,
    "hasHalfHourData": false
  },

  {
    "meterId": 13,
    "assetId": 3,
    "unitId": 0,
    "mpan": "S018012018913308149293",
    "serialNumber": "1913513513",
    "comment": "First Floor Electricity",
    "supplier": "EDF",
    "areaCovered": "TenantSpace",
    "controlledBy": "Electricity",
    "floorAreaServed": 130,
    "meterType": "Electricity",
    "generationType": "NationalGrid",
    "measurementType": "M2",
    "locationCarbonFactorId": 0,
    "marketCarbonFactorId": 0,
    "unitRateId": 0,
    "isActive": true,
    "isAMR": false,
    "isSubmeter": false,
    "isValidated": false,
    "isROC": false,
    "isFIT": false,
    "isCCA": false,
    "isEUETS": false,
    "hasHalfHourData": false
  }
]

Summary: Provides a list of all the meters

HTTP Request

GET /api/v1/meters

Response Body

The response body will be a list of meters.

Attribute Type and description
meterId integer
The SIERA-generated id of the meter
assetId integer
The SIERA-generated id of the associated asset
unitId integer
The SIERA-generated id of any associated unit
mpan string
The meter point administration number (MPAN) of the meter
serialNumber string
The serial number of the meter
comment string
A free-text description relating to the meter
supplier string
Any utilities supplier related to the meter
areaCovered enumeration
A valid area of the property which this meter covers, from the area covered enumeration
controlledBy enumeration
A valid item from the meter control enumeration showing who primarily pays for the energy from this meter, the landlord or the tenant
floorAreaServed integer
The floor area covered by this meter
meterType enumeration
A valid utility of the meter from the meter type enumeration
generationType enumeration
A valid generation type of the meter from the generation type enumeration
measurementType enumeration
The unit of measurement used to indicate floor area of this asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
locationCarbonFactorId integer
The id value of an location-based carbon factor Id which exists in the API-caller's SIERA instance, or one of the default carbon factors provided by Evora
marketCarbonFactorId integer
The id value of an market-based carbon factor Id which exists in the API-caller's SIERA instance, or one of the default carbon factors provided by Evora
unitRateId integer
The id value of a cost unit rate Id which exists in the API-caller's SIERA instance, or one of the default unit rates provided by Evora
isActive boolean
A boolean flag indicating if this meter is considered active and currently in use or not.
isAMR boolean
A boolean flag indicating if this meter's readings are being retrieved by automatic meter reading or not.
isSubmeter boolean
A boolean flag indicating if this meter isa sub-meter or not
isValidated boolean
A boolean flag indicating if this meter has been validated or not.
isROC boolean
A boolean flag indicating if this meter has an Renewables Obligation Certificate generation meter which measures total electricity produced by solar panel or not
isFIT boolean
A boolean flag indicating if this meter is a Feed-In-Time tariff (relating to solar panels) or not.
isCCA boolean
A boolean flag indicating if this meter is part of a Community Choice Aggregation or not.
isEUETS boolean
A boolean flag indicating if this meter is part of the EU Energy Trading System or not.
hasHalfHourData boolean
A boolean flag indicating if this meter has received half-hourly data or not.

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
500 Server error

Get a meter

GET /api/v1/meters/{meterId}

curl https://api.sieraglobal.com/api/v1/meters/11 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)


{
  "meterId": 11,
  "assetId": 2,
  "unitId": 1,
  "mpan": "S018011012261305588165",
  "serialNumber": "1875258102",
  "comment": "",
  "supplier": "EON",
  "areaCovered": "SharedServices",
  "controlledBy": "Landlord",
  "floorAreaServed": 730,
  "meterType": "Electricity",
  "generationType": "NationalGrid",
  "measurementType": "M2",
  "locationCarbonFactorId": 0,
  "marketCarbonFactorId": 0,
  "unitRateId": 1,
  "isActive": true,
  "isAMR": false,
  "isSubmeter": false,
  "isValidated": true,
  "isROC": false,
  "isFIT": false,
  "isCCA": false,
  "isEUETS": false,
  "hasHalfHourData": false
}

Summary: Provides a single meter given an ID

HTTP Request

GET /api/v1/meters/{meterId}

Parameters

Name Located in Description Required Type
meterId path A valid id of a meter stored in SIERA Yes integer

Response Body

The response body will the specified meter which matches the meterId given as a parameter.

Attribute Type and description
meterId integer
The SIERA-generated id of the meter
assetId integer
The SIERA-generated id of the associated asset
unitId integer
The SIERA-generated id of any associated unit
mpan string
The meter point administration number (MPAN) of the meter
serialNumber string
The serial number of the meter
comment string
A free-text description relating to the meter
supplier string
Any utilities supplier related to the meter
areaCovered enumeration
A valid area of the property which this meter covers, from the area covered enumeration
controlledBy enumeration
A valid item from the meter control enumeration showing who primarily pays for the energy from this meter, the landlord or the tenant
floorAreaServed integer
The floor area covered by this meter
meterType enumeration
A valid utility of the meter from the meter type enumeration
generationType enumeration
A valid generation type of the meter from the generation type enumeration
measurementType enumeration
The unit of measurement used to indicate floor area of this asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
locationCarbonFactorId integer
The id value of an location-based carbon factor Id which exists in the API-caller's SIERA instance, or one of the default carbon factors provided by Evora
marketCarbonFactorId integer
The id value of an market-based carbon factor Id which exists in the API-caller's SIERA instance, or one of the default carbon factors provided by Evora
unitRateId integer
The id value of a cost unit rate Id which exists in the API-caller's SIERA instance, or one of the default unit rates provided by Evora
isActive boolean
A boolean flag indicating if this meter is considered active and currently in use or not.
isAMR boolean
A boolean flag indicating if this meter's readings are being retrieved by automatic meter reading or not.
isSubmeter boolean
A boolean flag indicating if this meter isa sub-meter or not
isValidated boolean
A boolean flag indicating if this meter has been validated or not.
isROC boolean
A boolean flag indicating if this meter has an Renewables Obligation Certificate generation meter which measures total electricity produced by solar panel or not
isFIT boolean
A boolean flag indicating if this meter is a Feed-In-Time tariff (relating to solar panels) or not.
isCCA boolean
A boolean flag indicating if this meter is part of a Community Choice Aggregation or not.
isEUETS boolean
A boolean flag indicating if this meter is part of the EU Energy Trading System or not.
hasHalfHourData boolean
A boolean flag indicating if this meter has received half-hourly data or not.

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
401 Not found, the specified meter was not found
500 Server error

Upload a new meter

POST /api/v1/meters

curl POST https://api.sieraglobal.com/api/v1/meters \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON  
  {    
    "assetId": 2,
    "unitId": 1,
    "mpan": "S018011012261305588165",
    "serialNumber": "1875258102",
    "comment": "",
    "supplier": "EON",
    "areaCovered": "SharedServices",
    "controlledBy": "Landlord",
    "floorAreaServed": 730,
    "meterType": "Electricity",
    "generationType": "NationalGrid",
    "measurementType": "M2",
    "locationCarbonFactorId": 0,
    "marketCarbonFactorId": 0,
    "unitRateId": 1,
    "isActive": true,
    "isAMR": false,
    "isSubmeter": false,
    "isValidated": true,
    "isROC": false,
    "isFIT": false,
    "isCCA": false,
    "isEUETS": false,
    "hasHalfHourData": false
  }

Response (201)

{
  "meterId": 12
}

Summary: Upload a new meter

HTTP Request

POST /api/v1/meters

Request body

Attribute Type and description
assetId integer
A valid id of the associated asset
unitId integer
A valid id of an associated unit
mpan string
The meter point administration number (MPAN) of the meter
serialNumber string
The serial number of the meter
comment string
A free-text description relating to the meter
supplier string
Any utilities supplier related to the meter
areaCovered enumeration
A valid area of the property which this meter covers, from the area covered enumeration
controlledBy enumeration
A valid item from the meter control enumeration showing who primarily pays for the energy from this meter, the landlord or the tenant
floorAreaServed integer
The floor area covered by this meter
meterType enumeration
A valid utility of the meter from the meter type enumeration
generationType enumeration
A valid generation type of the meter from the generation type enumeration
measurementType enumeration
The unit of measurement used to indicate floor area of this asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
locationCarbonFactorId integer
The id value of an location-based carbon factor Id which exists in the API-caller's SIERA instance, or one of the default carbon factors provided by Evora
marketCarbonFactorId integer
The id value of an market-based carbon factor Id which exists in the API-caller's SIERA instance, or one of the default carbon factors provided by Evora
unitRateId integer
The id value of a cost unit rate Id which exists in the API-caller's SIERA instance, or one of the default unit rates provided by Evora
isActive boolean
A boolean flag indicating if this meter is considered active and currently in use or not.
isAMR boolean
A boolean flag indicating if this meter's readings are being retrieved by automatic meter reading or not.
isSubmeter boolean
A boolean flag indicating if this meter isa sub-meter or not
isValidated boolean
A boolean flag indicating if this meter has been validated or not.
isROC boolean
A boolean flag indicating if this meter has an Renewables Obligation Certificate generation meter which measures total electricity produced by solar panel or not
isFIT boolean
A boolean flag indicating if this meter is a Feed-In-Time tariff (relating to solar panels) or not.
isCCA boolean
A boolean flag indicating if this meter is part of a Community Choice Aggregation or not.
isEUETS boolean
A boolean flag indicating if this meter is part of the EU Energy Trading System or not.
hasHalfHourData boolean
A boolean flag indicating if this meter has received half-hourly data or not.

Response Body

The response body will a new meter ID relating to the uploaded meter

Attribute Type and description
meterId integer
The SIERA-generated id of the new meter

Responses

Code Description
201 Created
400 Validation failure
401 Unauthorised, the header token expired or is missing
500 Server error

Update a meter

PUT /api/v1/meters/{meterId}

curl PUT https://api.sieraglobal.com/api/v1/meters/11 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON
  {
    "assetId": 2,
    "unitId": 1,
    "mpan": "S018011012261305588165",
    "serialNumber": "1875258102",
    "comment": "",
    "supplier": "EDF",
    "areaCovered": "WholeBuilding",
    "controlledBy": "Landlord",
    "floorAreaServed": 730,
    "meterType": "Electricity",
    "generationType": "NationalGrid",
    "measurementType": "M2",
    "locationCarbonFactorId": 0,
    "marketCarbonFactorId": 0,
    "unitRateId": 1,
    "isActive": true,
    "isAMR": false,
    "isSubmeter": false,
    "isValidated": true,
    "isROC": false,
    "isFIT": false,
    "isCCA": false,
    "isEUETS": false,
    "hasHalfHourData": false
  }

Response (200)

Summary: Updates an existing meter by ID

HTTP Request

PUT /api/v1/meters/{meterId}

Parameters

Name Located in Description Required Type
meterId path The id of the meter to be updated in SIERA Yes integer

Request body

Attribute Type and description
meterId integer
The SIERA-generated id of the meter
assetId integer
The SIERA-generated id of the associated asset
unitId integer
The SIERA-generated id of any associated unit
mpan string
The meter point administration number (MPAN) of the meter
serialNumber string
The serial number of the meter
comment string
A free-text description relating to the meter
supplier string
Any utilities supplier related to the meter
areaCovered enumeration
A valid area of the property which this meter covers, from the area covered enumeration
controlledBy enumeration
A valid item from the meter control enumeration showing who primarily pays for the energy from this meter, the landlord or the tenant
floorAreaServed integer
The floor area covered by this meter
meterType enumeration
A valid utility of the meter from the meter type enumeration
generationType enumeration
A valid generation type of the meter from the generation type enumeration
measurementType enumeration
The unit of measurement used to indicate floor area of this asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
locationCarbonFactorId integer
The id value of an location-based carbon factor Id which exists in the API-caller's SIERA instance, or one of the default carbon factors provided by Evora
marketCarbonFactorId integer
The id value of an market-based carbon factor Id which exists in the API-caller's SIERA instance, or one of the default carbon factors provided by Evora
unitRateId integer
The id value of a cost unit rate Id which exists in the API-caller's SIERA instance, or one of the default unit rates provided by Evora
isActive boolean
A boolean flag indicating if this meter is considered active and currently in use or not.
isAMR boolean
A boolean flag indicating if this meter's readings are being retrieved by automatic meter reading or not.
isSubmeter boolean
A boolean flag indicating if this meter isa sub-meter or not
isValidated boolean
A boolean flag indicating if this meter has been validated or not.
isROC boolean
A boolean flag indicating if this meter has an Renewables Obligation Certificate generation meter which measures total electricity produced by solar panel or not
isFIT boolean
A boolean flag indicating if this meter is a Feed-In-Time tariff (relating to solar panels) or not.
isCCA boolean
A boolean flag indicating if this meter is part of a Community Choice Aggregation or not.
isEUETS boolean
A boolean flag indicating if this meter is part of the EU Energy Trading System or not.
hasHalfHourData boolean
A boolean flag indicating if this meter has received half-hourly data or not.

Responses

Code Description
200 OK
400 Validation failure
401 Unauthorised, the header token expired or is missing
404 Not found, the specified meter id was not found
500 Server error

Delete a meter

DELETE /api/v1/meters/{meterId}

curl -X DELETE https://api.sieraglobal.com/api/v1/meters/11 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

Summary: Deletes an existing meter by ID

HTTP Request

DELETE /api/v1/meters/{meterId}

Parameters

Name Located in Description Required Type
meterId path The id of the meter to be deleted in SIERA Yes integer

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the specified meter id was not found
500 Server error

Validation rules

When uploading new meters or updating existing, SIERA will apply the following rules and if they are not met, a response of 400 will be returned with an error message and the field causing the validation failure.

The validation requirements for meters are:

  1. When uploading a new meter, the meterId must be 0 or null.
  2. When updating an meter, the meterId must be of an existing meter in SIERA.
  3. The assetId must be provided and be for a valid asset in SIERA.
  4. The locationCarbonFactorId must be provided and be for a valid carbon factor in SIERA.
  5. The marketCarbonFactorId must be provided and be for a valid carbon factor in SIERA.
  6. The unitRateId must be provided and be for a valid unit rate in SIERA.
  7. The carbon factors chosen for locationCarbonFactorId and marketCarbonFactorId must match on utility type. For example, an electricity meter must choose an electricity carbon factor.

Consumption

Consumption in SIERA is available in two forms. The first is a monthly summary of consumption for each meter. The second is a a list of consumption records with a start and end date which capture utility invoices. The monthly summary is read-only and automatically generated and updated as consumption records for a meter are changed.

Get consumption summary of a meter

GET /api/v1/consumption/consumptionsummary/{assetId}/{meterId}

curl https://api.sieraglobal.com/api/v1/consumption/consumptionsummary/2/2 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

[  
  {
    "consumptionId": 10523180,
    "meterId": 2,
    "consumptionDate": "1/1/2020",
    "consumption": null,
    "cost": null,
    "co2": null,
    "daysActual": null,
    "daysEstimate": null
  },
  {
    "consumptionId": 10523181,
    "meterId": 2,
    "consumptionDate": "2/1/2020",
    "consumption": 356626,
    "cost": 35662.6,
    "co2": 83.12952,
    "daysActual": 29,
    "daysEstimate": 0
  },
  {
    "consumptionId": 10523182,
    "meterId": 2,
    "consumptionDate": "3/1/2020",
    "consumption": 310568,
    "cost": 31056.8,
    "co2": 72.3934,
    "daysActual": 0,
    "daysEstimate": 31
  },

  ...

  {
    "consumptionId": 10523183,
    "meterId": 2,
    "consumptionDate": "12/1/2020",
    "consumption": 365502,
    "cost": 36550.2,
    "co2": 85.19852,
    "daysActual": 0,
    "daysEstimate": 31
  }
]

Summary: Provides a list of monthly summaries of consumption for the specified meter

The monthly consumption total is calculated by calculating a daily amount from any consumption records with days in a given month. The monthly total is the daily amount times the number of days in the month. Where consumption records don't cover part of the month, the daily amount is multipled by the number of days covered by any consumption records available for a meter.

As an example, given an uploaded consumption record of 10,000 kWh from 1st September to the 15th October, the monthly consumption values would be calculated as such:

daily rate = 10,0000 / (30 + 15) = 222.22
September = daily rate * 30 = 6666.6
October = daily rate * 15 = 3333.3

As the consumption record only includes 15 days of October, there are 16 days without consumption which leave a gap in the month. The 16 day gap in consumption for October would be represented in the fields daysActual or daysEstimated which would show 15. The choice of which field would contain the 15 would be based on the consumptionType of the associated consumption records.

HTTP Request

GET /api/v1/consumption/consumptionsummary/{assetId}/{meterId}

Parameters

Name Located in Description Required Type
assetId path A valid id of an asset stored in SIERA Yes integer
meterId path A valid id of a meter stored in SIERA No integer

Response Body

The response body will include a summary of consumption for the asset (and meter if specified), in the format of aggregated months of consumption

Attribute Type and description
consumptionId integer
The SIERA-generated id of the consumption month of the meter
meterId integer
The id of the associated meter
consumptionDate string
The date of the consumption month, in the format m/d/yyyy. The day value will always be the first of the month
consumption float
The amount of consumption for the month
cost float
The amount of consumption represented as a financial cost. The factor used to convert energy units to money is indicated by setting a unit rate on the meter associated with this consumption
co2 float
The amount of consumption represented kgCO2 of carbon. The factor used to convert energy units to carbon is indicated by setting a carbon factor on the meter associated with this consumption
daysActual integer
The number of days consumption in the month with a consumptionType of actual
daysEstimate integer
The number of days consumption in the month with a consumptionType of estimated

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
500 Server error

Get consumption records for a meter

GET /api/v1/consumption/record/{assetId}/{meterId}

curl https://api.sieraglobal.com/api/v1/consumption/record/2/2 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

[   
  {
    "recordId": 3053526,
    "meterId": 2,
    "fromDate": "9/1/2022",
    "toDate": "9/30/2022",
    "consumption": 356573,
    "consumptionType": "Actual",
    "energySource": "NationalGridStandard",
    "useOfArea": "OccupiedTenantSpace",
    "sustainableProcurement": "RenewableEnergyContract"
  },
  {
    "recordId": 3053584,
    "meterId": 2,
    "fromDate": "6/1/2022",
    "toDate": "6/30/2022",
    "consumption": 296150,
    "consumptionType": "Actual",
    "energySource": "NationalGridStandard",
    "useOfArea": "OccupiedTenantSpace",
    "sustainableProcurement": "RenewableEnergyContract"
  },
  {
    "recordId": 3053666,
    "meterId": 2,
    "fromDate": "10/1/2022",
    "toDate": "10/31/2022",
    "consumption": 353664,
    "consumptionType": "Estimate",
    "energySource": "NationalGridStandard",
    "useOfArea": "OccupiedTenantSpace",
    "sustainableProcurement": "RenewableEnergyContract"
  },
  {
    "recordId": 3053680,
    "meterId": 2,
    "fromDate": "4/1/2022",
    "toDate": "4/30/2022",
    "consumption": 321949,
    "consumptionType": "Actual",
    "energySource": "NationalGridStandard",
    "useOfArea": "OccupiedTenantSpace",
    "sustainableProcurement": "RenewableEnergyContract"
  }
]

Summary: Provides a list of consumption records for the specified meter

HTTP Request

GET /api/v1/consumption/record/{assetId}/{meterId}

Parameters

Name Located in Description Required Type
assetId path A valid id of an asset stored in SIERA Yes integer
meterId path A valid id of a meter stored in SIERA No integer

Response Body

The response body will include a list of consumption records for the asset (and meter if specified)

Attribute Type and description
recordId integer
The SIERA-generated id of the consumption record
meterId integer
The id of the associated meter
fromDate string
The start date of the consumption being recorded, in the format m/d/yyyy
toDate float
The end date of the consumption being recorded, in the format m/d/yyyy
consumption float
The amount of consumption
consumptionType enumeration
The type of consumption, actual or estimated. This must be a valid item from the enumeration consumption type
energySource enumeration
The source of the energy, for example from renewables or the national energy grid. This must be a valid item from the enumeration consumption energy source
useOfArea enumeration
The use of area from a tenancy point of view, occupied or void. This must be a valid item from the enumeration use of area
sustainableProcurement enumeration
The sustainable procurement method (if any) related to this consumption. This must be a valid item from the enumeration sustainable procurement

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
500 Server error

Upload consumption records

Consumption uploads represent utility invoices and so they all have start and end dates. The endpoint returns a collection of results indicating which records were successfully uploaded and which failed to upload and the reason.

The results are organised into the following lists:

Successful Uploads
Consumption records which were successfully uploaded into SIERA

Exact Matches
Consumption records which were rejected as an existing consumption record had the same start and end date. If the parameter forceExactMatchUpload is set to true, then these records will overwrite the existing records and appear in the Successful Uploads list.

Overlap Matches
Consumption records which were rejected as existing records overlap the start and end dates of existing consumption records.

Instance Errors
Consumption records which failed to upload because the associated meter or asset does not exist in the API-caller's SIERA instance

Other Errors
Consumption records which were rejected along with the reason for the rejection.

POST /api/v1/consumption/record/{forceExactMatchUpload}

curl POST https://api.sieraglobal.com/api/v1/consumption/record/false \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON    
  [
      {
        "meterId": 2,
        "fromDate": "4/1/2022",
        "toDate": "4/30/2022",
        "consumption": 321949,
        "consumptionType": "Actual",
        "energySource": "NationalGridStandard",
        "useOfArea": "OccupiedTenantSpace",
        "sustainableProcurement": "RenewableEnergyContract"
      },
      {
        "meterId": 2,
        "fromDate": "5/1/2022",
        "toDate": "4/31/2022",
        "consumption": 301231,
        "consumptionType": "Actual",
        "energySource": "NationalGridStandard",            
        "useOfArea": "OccupiedTenantSpace",
        "sustainableProcurement": "RenewableEnergyContract"
      }
  ]

Response (201)

{
  "success": [
    {
      "recordId": 0,
      "meterId": 2,
      "fromDate": "4/1/2022",
      "toDate": "4/30/2022",
      "consumption": 321949,
      "consumptionType": "Actual",
      "energySource": "NationalGridStandard",
      "useOfArea": "OccupiedTenantSpace",
      "sustainableProcurement": "RenewableEnergyContract"
    }
  ],
  "exactMatch": [],
  "overlapErrors": [
    {
      "recordId": 0,
      "meterId": 2,
      "fromDate": "5/1/2022",
      "toDate": "5/31/2022",
      "consumption": 301231,
      "consumptionType": "Actual",
      "energySource": "NationalGridStandard",
      "useOfArea": "OccupiedTenantSpace",
      "sustainableProcurement": "RenewableEnergyContract"
    }
  ],
  "instanceErrors": [],
  "errors": []
}

Summary: Upload consumption records

HTTP Request

POST /api/v1/consumption/record/{forceExactMatchUpload}

Parameters

Name Located in Description Required Type
forceExactMatchUpload path A boolean flag instructing the API to overwrite existing consumption records with a matching start and end date Yes boolean

Request body

Attribute Type and description
meterId integer
The id of the associated meter
fromDate string
The start date of the consumption being recorded, in the format m/d/yyyy
toDate float
The end date of the consumption being recorded, in the format m/d/yyyy
consumption float
The amount of consumption
consumptionType enumeration
The type of consumption, actual or estimated. This must be a valid item from the enumeration consumption type
energySource enumeration
The source of the energy, for example from renewables or the national energy grid. This must be a valid item from the enumeration consumption energy source
useOfArea enumeration
The use of area from a tenancy point of view, occupied or void. This must be a valid item from the enumeration use of area
sustainableProcurement enumeration
The sustainable procurement method (if any) related to this consumption. This must be a valid item from the enumeration sustainable procurement

Response Body

The response body will include a collection of results indicating which records were successfully uploaded and which failed to upload and the reason.

Attribute Type and description
recordId integer
The SIERA-generated id of the consumption record
meterId integer
The id of the associated meter
fromDate string
The start date of the consumption uploaded, in the format m/d/yyyy
toDate float
The end date of the consumption uploaded, in the format m/d/yyyy
consumption float
The amount of consumption uploaded
consumptionType enumeration
The type of consumption, actual or estimated from the enumeration consumption type
energySource enumeration
The source of the energy, for example from renewables or the national energy grid from the enumeration consumption energy source
useOfArea enumeration
The use of area from a tenancy point of view, occupied or void. This must be a valid item from the enumeration use of area
sustainableProcurement enumeration
The sustainable procurement method (if any) related to this consumption. This must be a valid item from the enumeration sustainable procurement
errors string
A description of any other error which has occured when the upload was attempted

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
500 Server error

Update consumption records

Consumption updates represent utility invoices and so they all have start and end dates. The endpoint returns a collection of results indicating which records were successfully updated and which failed to update and the reason.

The result are organised into the following lists:

Successful Updates
Consumption records which were successfully updated into SIERA

Exact Matches
Consumption records which were rejected as an existing consumption record had the same start and end date. If the parameter forceExactMatchUpload is set to true, then these records will overwrite the existing records and appear in the Successful Updates list.

Overlap Matches
Consumption records which were rejected as existing records overlap the start and end dates of existing consumption records.

Instance Errors
The consumption record which failed to update because the associated meter or asset does not exist in the API-caller's SIERA instance

Other Errors
Consumption records which were rejected along with the reason for the rejection.

PUT /api/v1/consumption/record

curl POST https://api.sieraglobal.com/api/v1/consumption/record \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON    
  [
      {
        "recordId": 13,
        "meterId": 2,
        "fromDate": "4/1/2022",
        "toDate": "4/30/2022",
        "consumption": 321949,
        "consumptionType": "Actual",
        "energySource": "NationalGridStandard",
        "useOfArea": "OccupiedTenantSpace",
        "sustainableProcurement": "RenewableEnergyContract"
      },
      {
        "recordId": 14,
        "meterId": 2,
        "fromDate": "5/1/2022",
        "toDate": "4/31/2022",
        "consumption": 301231,
        "consumptionType": "Actual",
        "energySource": "NationalGridStandard",
        "useOfArea": "OccupiedTenantSpace",
        "sustainableProcurement": "RenewableEnergyContract"
      }
  ]

Response (201)

{
  "success": [
    {
      "recordId": 13,
      "meterId": 2,
      "fromDate": "4/1/2022",
      "toDate": "4/30/2022",
      "consumption": 321949,
      "consumptionType": "Actual",
      "energySource": "NationalGridStandard",
      "useOfArea": "OccupiedTenantSpace",
      "sustainableProcurement": "RenewableEnergyContract"
    }
  ],
  "exactMatch": [],
  "overlapErrors": [
    {
      "recordId": 14,
      "meterId": 2,
      "fromDate": "5/1/2022",
      "toDate": "5/31/2022",
      "consumption": 301231,
      "consumptionType": "Actual",
      "energySource": "NationalGridStandard",
      "useOfArea": "OccupiedTenantSpace",
      "sustainableProcurement": "RenewableEnergyContract"
    }
  ],
  "instanceErrors": [],
  "errors": []
}

Summary: Update consumption records

HTTP Request

PUT /api/v1/consumption/record/

Request body

Attribute Type and description
recordId integer
The SIERA-generated id of the consumption record
meterId integer
The id of the associated meter
fromDate string
The start date of the consumption being recorded, in the format m/d/yyyy
toDate float
The end date of the consumption being recorded, in the format m/d/yyyy
consumption float
The amount of consumption
consumptionType enumeration
The type of consumption, actual or estimated. This must be a valid item from the enumeration consumption type
energySource enumeration
The source of the energy, for example from renewables or the national energy grid. This must be a valid item from the enumeration consumption energy source
useOfArea enumeration
The use of area from a tenancy point of view, occupied or void. This must be a valid item from the enumeration use of area
sustainableProcurement enumeration
The sustainable procurement method (if any) related to this consumption. This must be a valid item from the enumeration sustainable procurement

Response Body

The response body will include a collection of results indicating which records were successfully updated and which failed to update and the reason.

Attribute Type and description
recordId integer
The SIERA-generated id of the consumption record
meterId integer
The id of the associated meter
fromDate string
The start date of the consumption uploaded, in the format m/d/yyyy
toDate float
The end date of the consumption uploaded, in the format m/d/yyyy
consumption float
The amount of consumption uploaded
consumptionType enumeration
The type of consumption, actual or estimated from the enumeration consumption type
energySource enumeration
The source of the energy, for example from renewables or the national energy grid from the enumeration consumption energy source
useOfArea enumeration
The use of area from a tenancy point of view, occupied or void. This must be a valid item from the enumeration use of area
sustainableProcurement enumeration
The sustainable procurement method (if any) related to this consumption. This must be a valid item from the enumeration sustainable procurement
errors string
A description of any other error which has occured when the upload was attempted

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
500 Server error

Delete consumption records

DELETE /api/v1/consumption/record

curl -X DELETE https://api.sieraglobal.com/api/v1/consumption/record \
  -H "Authorization: Bearer $ACCESS_TOKEN" 
  -V "Content-Type: application/json" \
  -d @- <<JSON    
  [
      2, 3, 4
  ]

Response (200)

{
  "success": [ 3 ],
  "instanceerror": [ 4 ],
  "error": [
    {
      "recordId": 2,
      "error": "Meter does not exist."
    }
  ]
}

Consumption delete requests return a list of results.

The result are organised into the following lists:

Successful Deletions
Consumption records which were successfully deleted

Instance Errors
Consumption records which failed to delete because the associated meter or asset does not exist in the API-caller's SIERA instance

Errors
Consumption records which failed to delete and an error description explaining the error message

Summary: Deletes consumption records by ID

HTTP Request

DELETE /api/v1/consumption/record

Request body

The request body is a json array of the consumption record IDs to be deleted

Response Body

The response body will include a list of results: successful uploads, instance errors or general errors. Successful uploads and instance errors will only contain the related recordId, whilst the general errors will also contain a description of the error.

Attribute Type and description
recordId integer
The id of the consumption record
error string
A description of the error which has occurred

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
500 Server error

Update a consumption record

Consumption updates represent utility invoices and so they all have start and end dates. The endpoint returns a collection of results indicating if the record was successfully updated or if it failed to update and the reason.

The result is organised into the following lists:

Successful Updates
The consumption record was successfully updated into SIERA

Exact Matches
The consumption record was rejected as an existing consumption record had the same start and end date. If the parameter forceExactMatchUpload is set to true, then these records will overwrite the existing records and appear in the Successful Updates list.

Overlap Matches
The consumption record was rejected as existing records overlap the start and end dates of existing consumption records.

Instance Errors
The consumption record failed to update because the associated meter or asset does not exist in the API-caller's SIERA instance

Other Errors
The consumption record was rejected along with the reason for the rejection.

PUT /api/v1/consumption/record/{recordId}

curl POST https://api.sieraglobal.com/api/v1/consumption/record/13 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON    
  {
    "recordId": 13,
    "meterId": 2,
    "fromDate": "4/1/2022",
    "toDate": "4/30/2022",
    "consumption": 321949,
    "consumptionType": "Estimate",
    "energySource": "NationalGridStandard",
    "useOfArea": "OccupiedTenantSpace",
    "sustainableProcurement": "RenewableEnergyContract"
  }

Response (201)

{
  "success": [
    {
      "recordId": 13,
      "meterId": 2,
      "fromDate": "4/1/2022",
      "toDate": "4/30/2022",
      "consumption": 321949,
      "consumptionType": "Estimate",
      "energySource": "NationalGridStandard",
      "useOfArea": "OccupiedTenantSpace",
      "sustainableProcurement": "RenewableEnergyContract"
    }
  ],
  "exactMatch": [],
  "overlapErrors": [],
  "instanceErrors": [],
  "errors": []
}

Summary: Update a consumption record

HTTP Request

PUT /api/v1/consumption/record/{recordId}

Parameters

Name Located in Description Required Type
recordId path A valid id of a consumption record stored in SIERA Yes integer

Request body

Attribute Type and description
recordId integer
The SIERA-generated id of the consumption record
meterId integer
The id of the associated meter
fromDate string
The start date of the consumption being recorded, in the format m/d/yyyy
toDate float
The end date of the consumption being recorded, in the format m/d/yyyy
consumption float
The amount of consumption
consumptionType enumeration
The type of consumption, actual or estimated. This must be a valid item from the enumeration consumption type
energySource enumeration
The source of the energy, for example from renewables or the national energy grid. This must be a valid item from the enumeration consumption energy source
useOfArea enumeration
The use of area from a tenancy point of view, occupied or void. This must be a valid item from the enumeration use of area
sustainableProcurement enumeration
The sustainable procurement method (if any) related to this consumption. This must be a valid item from the enumeration sustainable procurement

Response Body

The response body will include a collection of results indicating if the record was successfully updated or failed to update and the reason.

Attribute Type and description
recordId integer
The SIERA-generated id of the consumption record
meterId integer
The id of the associated meter
fromDate string
The start date of the consumption uploaded, in the format m/d/yyyy
toDate float
The end date of the consumption uploaded, in the format m/d/yyyy
consumption float
The amount of consumption uploaded
consumptionType enumeration
The type of consumption, actual or estimated from the enumeration consumption type
energySource enumeration
The source of the energy, for example from renewables or the national energy grid from the enumeration consumption energy source
useOfArea enumeration
The use of area from a tenancy point of view, occupied or void. This must be a valid item from the enumeration use of area
sustainableProcurement enumeration
The sustainable procurement method (if any) related to this consumption. This must be a valid item from the enumeration sustainable procurement
errors string
A description of any other error which has occured when the upload was attempted

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
500 Server error

Delete a consumption record

DELETE /api/v1/consumption/record/{recordId}

curl -X DELETE https://api.sieraglobal.com/api/v1/consumption/record/14 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

{
  "success": [ 14 ],
  "instanceerror": [ ],
  "error": [ ]
}

Consumption delete requests return a list of results.

The result are organised into the following lists:

Successful Deletions
The consumption record was successfully deleted

Instance Errors
The consumption record failed to delete because the associated meter or asset does not exist in the API-caller's SIERA instance

Errors
The consumption record failed to delete and an error description explaining the error message

Summary: Deletes a consumption record by ID

HTTP Request

DELETE /api/v1/consumption/record/{recordId}

Parameters

Name Located in Description Required Type
recordId path A valid id of an asset unit stored in SIERA Yes integer

Response Body

The response body will include a list of results: successful uploads, instance errors or general errors. Successful uploads and instance errors will only contain the related recordId, whilst the general errors will also contain a description of the error.

Attribute Type and description
recordId integer
The id of the consumption record
error string
A description of the error which has occurred

Legacy consumption import

POST /api/v1/consumptionbulkimport/{forceExactMatchUpload}

curl -X POST https://api.sieraglobal.com/api/v1/consumptionbulkimport/false \
  -H "Authorization: Bearer $ACCESS_TOKEN" 
  -V "Content-Type: application/json" \
  -d @- <<JSON    
  {
    "mpan": 2,
    "organisationId": 1
    "fromDate": "4/1/2022",
    "toDate": "4/30/2022",
    "consumption": 321949,
    "consumptionType": "Actual",
    "energySource": "NationalGridStandard"
  }

Response (201)

{
  "success": [
    {
      "recordId": 3103512,
      "meterId": 2,
      "organisationId": 1,
      "fromDate": "4/1/2022",
      "toDate": "4/30/2022",
      "consumption": 321949,
      "consumptionType": "Actual",
      "energySource": "NationalGridStandard",
      "useOfArea": "OccupiedTenantSpace",
      "sustainableProcurement": "RenewableEnergyContract"
    }
  ],
  "exactMatch": [],
  "overlapErrors": [
    {
      "recordId": 0,
      "meterId": 2,
      "fromDate": "5/1/2022",
      "toDate": "5/31/2022",
      "consumption": 301231,
      "consumptionType": "Actual",
      "energySource": "NationalGridStandard",
      "useOfArea": "OccupiedTenantSpace",
      "sustainableProcurement": "RenewableEnergyContract"
    }
  ],
  "instanceErrors": [],
  "errors": []
}

Legacy consumption import is a consumption uploading method which does not require an API caller to belong to the SIERA instance where the target assets and meters are located. This provides a method for 3rd party companies to upload consumption on behalf of assets which they may not directly own or manage in SIERA.

The only requirements for a valid consumption upload is a matching meter point administration number (MPAN) and the correct organisationId of the owner of the target asset. Similar to using standard endpoints above, the endpoint will return a list of results which show successful uploads and any errors.

The results are organised into the following lists:

Successful Uploads
Consumption records which were successfully uploaded into SIERA

Exact Matches
Consumption records which were rejected as an existing consumption record had the same start and end date. If the parameter forceExactMatchUpload is set to true, then these records will overwrite the existing records and appear in the Successful Uploads list.

Overlap Matches
Consumption records which were rejected as existing records overlap the start and end dates of existing consumption records.

Instance Errors
Consumption records which failed to delete because the associated meter or asset does not exist in the API-caller's SIERA instance

Other Errors
Consumption records which were rejected along with the reason for the rejection.

Summary: Uploads consumption to meters without limiting to SIERA instances

HTTP Request

POST /api/v1/consumptionbulkimport/{forceExactMatchUpload}

Parameters

Name Located in Description Required Type
forceExactMatchUpload path A boolean flag instructing the API to overwrite existing consumption records with a matching start and end date Yes boolean

Request body

Attribute Type and description
mpan string
The meter point administration number (MPAN) of the associated meter
organisationId integer
The id of the associated organisation which manages the asset in SIERA
fromDate string
The start date of the consumption being recorded, in the format m/d/yyyy
toDate float
The end date of the consumption being recorded, in the format m/d/yyyy
consumption float
The amount of consumption
consumptionType enumeration
The type of consumption, actual or estimated. This must be a valid item from the enumeration consumption type
energySource enumeration
The source of the energy, for example from renewables or the national energy grid. This must be a valid item from the enumeration consumption energy source
useOfArea enumeration
The use of area from a tenancy point of view, occupied or void. This must be a valid item from the enumeration use of area
sustainableProcurement enumeration
The sustainable procurement method (if any) related to this consumption. This must be a valid item from the enumeration sustainable procurement

Response Body

The response body will include a collection of results indicating which records were successfully uploaded and which failed to upload and the reason.

Attribute Type and description
recordId integer
The SIERA-generated id of the consumption record
mpan string
The meter point administration number (MPAN) of the associated meter
organisationId integer
The id of the associated organisation which manages the asset in SIERA
meterId integer
The id of the associated meter
fromDate string
The start date of the consumption uploaded, in the format m/d/yyyy
toDate float
The end date of the consumption uploaded, in the format m/d/yyyy
consumption float
The amount of consumption uploaded
consumptionType enumeration
The type of consumption, actual or estimated from the enumeration consumption type
energySource enumeration
The source of the energy, for example from renewables or the national energy grid from the enumeration consumption energy source
useOfArea enumeration
The use of area from a tenancy point of view, occupied or void. This must be a valid item from the enumeration use of area
sustainableProcurement enumeration
The sustainable procurement method (if any) related to this consumption. This must be a valid item from the enumeration sustainable procurement
errors string
A description of any other error which has occured when the upload was attempted

Validation rules

When uploading new consumption or updating existing, SIERA will apply the following rules and if they are not met, a response of 400 will be returned with an error message and the field causing the validation failure. As consumption also handles bulk operations, some endpoints return results in lists. In these cases, some validations may be returned in the result and not cause a 400 response code.

The validation requirements for consumption are:

  1. When uploading new consumption, the meterId must be of an existing meter in SIERA.
  2. When updating consumption, the recordId must be of an existing consumption in SIERA.
  3. The consumption uploaded must be a positive number. SIERA currently only accepts absolute amounts, rather than billing data and negative adjustments.
  4. The fromDate and toDate must be provided, and in the dd/mm/yy format.
  5. For the legacy consumption upload, the mpan provided must exist on the organisation related to specified organisationId.

Waste Destinations

Waste destinations are the waste equivalent of meters. They represent the final destination for waste disposed of at an asset. Destinations can be places like a landfill, a recycling point or a materials recovery facility. Just as meters have consumption records, waste destinations have waste records, which in turn have both a summary and a record version.

Get all waste destinations

GET /api/v1/wastedestinations

curl https://api.sieraglobal.com/api/v1/wastedestinations \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)


[
    {
      "assetId": 2,
      "wasteDestinationId": 2,
      "wasteDestinationDescription": "Mixed Recycleables",
      "comments": "Recycling for Chelsea House, London",
      "contractor": "Veolia",
      "reference": "Reference 1000022",
      "wasteDestination": "Recycled"
    },
    {
      "assetId": 2,
      "wasteDestinationId": 3,
      "wasteDestinationDescription": "General Waste",
      "comments": "General Waste for Chelsea House, London",
      "contractor": "Veolia",
      "reference": "Reference 1000023",
      "wasteDestination": "Landfill"
    }
]

Summary: Provides a list of all the waste destinations

HTTP Request

GET /api/v1/wastedestination

Response Body

The response body will be a list of waste destimations.

Attribute Type and description
assetId integer
The id of the asset
wasteDestinationId integer
The SIERA-generated id of the waste destination
wasteDestinationDescription string
A description of the waste destination
comments string
Comments relating to the waste destination
contractor string
The name of the contractor providing the waste service
reference string
A reference for the waste destination on the asset
wasteDestination enumeration
A valid destination type from the waste destination enumeration

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, no waste destinations were found
500 Server error

Get a waste destination

GET /api/v1/wastedestinations/{wasteDestinationId}

curl https://api.sieraglobal.com/api/v1/wastedestinations/2 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)


{
  "assetId": 2,
  "wasteDestinationId": 2,
  "wasteDestinationDescription": "Mixed Recycleables",
  "comments": "Recycling for Chelsea House, London",
  "contractor": "Veolia",
  "reference": "Reference 1000022",
  "wasteDestination": "Recycled"
}

Summary: Provides a waste destination

HTTP Request

GET /api/v1/wastedestinations/{wasteDestinationId}

Parameters

Name Located in Description Required Type
wasteDestinationId path A valid id of a waste destination stored in SIERA Yes integer

Response Body

The response body will be a waste destimation.

Attribute Type and description
assetId integer
The id of the associated asset
wasteDestinationId integer
The SIERA-generated id of the waste destination
wasteDestinationDescription string
A description of the waste destination
comments string
Comments relating to the waste destination
contractor string
The name of the contractor providing the waste service
reference string
A reference for the waste destination on the asset
wasteDestination enumeration
A valid destination type from the waste destination enumeration

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the waste destination was not found
500 Server error

Upload a new waste destination

POST /api/v1/wastedestinations

curl POST https://api.sieraglobal.com/api/v1/wastedestinations \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON  
  {
    "assetId": 2,    
    "wasteDestinationDescription": "Glass Recycling",
    "comments": "Glass recycling for Chelsea House, London",
    "contractor": "Veolia",
    "reference": "Reference 1000024",
    "wasteDestination": "Recycled"
  }

Response (201)

{
  "wasteDestinationId": 6
}

Summary: Upload a new waste destination

HTTP Request

POST /api/v1/wastedestinations

Request body

Attribute Type and description
assetId integer
The id of a valid asset in the API caller's SIERA instance
wasteDestinationDescription string
A description of the waste destination
comments string
Comments relating to the waste destination
contractor string
The name of the contractor providing the waste service
reference string
A reference for the waste destination on the asset
wasteDestination enumeration
A valid destination type from the waste destination enumeration

Response Body

The response body will a new waste destination ID relating to the uploaded waste destination

Attribute Type and description
wasteDestinationId integer
The SIERA-generated id of the new waste destination

Responses

Code Description
201 Created
400 Validation failure
401 Not found, the specified asset id was not found
500 Server error

Update a waste destination

PUT /api/v1/wastedestinations/{wasteDestinationId}

curl PUT https://api.sieraglobal.com/api/v1/wastedestinations/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON
  {
    "assetId": 2,    
    "wasteDestinationId": 4,  
    "wasteDestinationDescription": "Plastic Recycling",
    "comments": "Plastic recycling for Chelsea House, London",
    "contractor": "Veolia",
    "reference": "Reference 1000025",
    "wasteDestination": "Recycled"
  }

Response (200)

Summary: Updates an existing waste destination by ID

HTTP Request

PUT /api/v1/wastedestinations/{wasteDestinationId}

Parameters

Name Located in Description Required Type
wasteDestinationId path A valid id of a waste destination stored in SIERA Yes integer

Request body

Attribute Type and description
assetId integer
The id of the asset
wasteDestinationId integer
The SIERA-generated id of the waste destination
wasteDestinationDescription string
A description of the waste destination
comments string
Comments relating to the waste destination
contractor string
The name of the contractor providing the waste service
reference string
A reference for the waste destination on the asset
wasteDestination enumeration
A valid destination type from the waste destination enumeration

Responses

Code Description
200 OK
400 Validation failure
401 Not found, the specified waste destination id was not found
500 Server error

Delete a waste destination

DELETE /api/v1/wastedestinations/{wasteDestinationId}

curl -X DELETE https://api.sieraglobal.com/api/v1/wastedestinations/4 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

Summary: Deletes an existing waste destination by ID

HTTP Request

DELETE /api/v1/wastedestinations/{wasteDestinationId}

Parameters

Name Located in Description Required Type
wasteDestinationId path The id of the waste destination to be deleted in SIERA Yes integer

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
401 Not found, the specified waste destination id was not found
500 Server error

Validation rules

When uploading new waste destinations or updating existing, SIERA will apply the following rules and if they are not met, a response of 400 will be returned with an error message and the field causing the validation failure.

The validation requirements for waste destinations are:

  1. When uploading a new waste destination, the wasteDestinationId must be 0 or null.
  2. When updating a waste destination, the wasteDestinationId must be of an existing waste destination in SIERA.
  3. The assetId must exist in SIERA.
  4. The wasteReference must be unique. Validation will fail if any other waste destination has the same reference.

Waste Records

Waste records in SIERA follow a similar pattern to utility consumption of meters. They both have an endpoint for a monthly summary of waste, and an endpoint to manage records with start and end dates. Just like consumption, the monthly summary is read-only and is automatically updated whenever waste records change.

Get the waste summary of a waste destination

GET /api/v1/wasterecords/{wasteDestinationId}/summary

curl https://api.sieraglobal.com/api/v1/wasterecords/4/summary \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

[  
  {
    "wasteId": 4,
    "wasteDestinationId": 4,
    "wasteDate": "1/1/2022",
    "tonnes": 5.34214,
    "landfill": 0,
    "incinerated": 0,
    "recycled": 5.34214,
    "reuse": 0,
    "anaerobic": 0,
    "hazardous": 0,
    "mrFunknown": 0,
    "incineratedWer": 0
  },  
  {
    "wasteId": 5,
    "wasteDestinationId": 4,
    "wasteDate": "2/1/2022",
    "tonnes": 3.4123,
    "landfill": 0,
    "incinerated": 0,
    "recycled": 3.4123,
    "reuse": 0,
    "anaerobic": 0,
    "hazardous": 0,
    "mrFunknown": 0,
    "incineratedWer": 0
  },  

  ...

  {
    "wasteId": 6,
    "wasteDestinationId": 4,
    "wasteDate": "12/1/2022",
    "tonnes": 2.15475,
    "landfill": 0,
    "incinerated": 0,
    "recycled": 2.15475,
    "reuse": 0,
    "anaerobic": 0,
    "hazardous": 0,
    "mrFunknown": 0,
    "incineratedWer": 0
  }
]

Summary: Provides a list of monthly summaries of waste for the specified waste destination

Waste monthly summaries are populated and updated when waste records are added or changed to SIERA. The values in each attribute of the waste summary are updated based upon the type of waste destination. For example, if the waste destination is a recycled then the waste added to that destination will be added to the tonnes attribute and also the to recycled attribute. Likewise if the destination is MRFIncinerator and the mrfOptions.recycled value of the uploaded waste record is set to 0.5 when uploaded, then the waste value will go to tonnes and half will go to recycled and half to incinerated.

The following explains the details of which attribute is updated when waste is uploaded or changed:

tonnes
Any change to waste will result in the total value being updated to reflect the overall total. All other attributes excluding hazardous added together should equal tonnes.

landfill
Any waste on destinations set to Landfill or MRFLandfill will update this attribute. MRFLandfill will take into account the mrfOptions.recycled option on the waste record, and the amount left after the percentage of mrf recycled indicated is sent to Recycled will be added to Landfill.

incinerated
Any waste on destinations set to Incinerated or MRFIncinerated will update this attribute. MRFIncinerated will take into account the mrfOptions.Recycled option on the waste record, and the amount left after the percentage of mrf recycled indicated is sent to Recycled will be added to Incinerated. Additionally, if a waste record is uploaded with Wer set to true, the waste will go to IncineratedWer instead of Incinerated.

recycled
Any waste on destinations set to Recycled will update this attribute. Additionally MRFIncinerated, MRFLandfill or MRFUnknown will update this attribute if the mrfOption.recycled is set to a number over 0. For example, mrfOption.recycled set to 0.5 will mean half the waste uploaded to an MRF destination will go recycled and the other half to the respective main destionation, incinerator, landfill or unknown.

reuse
Any waste on destinations set to Reuse will update this attribute.

anaerobic
Any waste on destinations set to AnaerobicDigestion will update this attribute.

hazardous
Any waste uploaded on a waste record with isHazardous set to true will update this attribute in addition to the target waste destination.

mrFunknown
Any waste on destinations set to MRFUnknown will update this attribute. MRFUnknown will take into account the mrfOptions.recycled option on the waste record, and the amount left after the percentage of mrf recycled indicated is sent to Recycled will be added to mrFunknown.

incineratedWer
Any waste on destinations set to incinerated or MRFIncinerated will update this attribute if the waste record uploaded has wer set to true. MRFIncinerated will take into account the mrfOptions.recycled option on the waste record, and the amount left after the percentage of mrf recycled indicated is sent to recycled will be added to incineratedWer.

HTTP Request

GET /api/v1/wasterecords/{wasteDestinationId}/summary

Parameters

Name Located in Description Required Type
wasteDestinationId path A valid id of a waste destination stored in SIERA Yes integer

Response Body

The response body will be a list of waste records associated with the waste destination specified by the wasteDestinationId parameter.

Attribute Type and description
wasteId integer
The id of the waste summary record
wasteDestinationId string
A description of the waste destination
wasteDate string
Comments relating to the waste destination
tonnes float
The total waste in tonnes sent to the waste destination
landfill float
The amount of landfill waste sent to the waste destination
incinerated float
The amount of incinerated waste sent to the waste destination
recycled float
The amount of recycled waste sent to the waste destination
reuse float
The amount of reuse waste sent to the waste destination
anaerobic float
The amount of anaerobic waste sent to the waste destination
hazardous float
The amount of hazardous waste sent to the waste destination
mrFunknown float
The amount of waste sent to the waste destination
incineratedWer float
The amount of incinerated WER waste sent to the waste destination

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
500 Server error

Get waste records for a waste destination

GET /api/v1/wasterecords/{wasteDestinationId}

curl https://api.sieraglobal.com/api/v1/wasterecords/4 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

[   
  {
    "wasteRecordId": 343,
    "wasteDestinationId": 4,
    "fromDate": "1/1/2022",
    "toDate": "1/31/2022",
    "wasteStream": "Plastics",
    "tonnes": 1.2343,
    "incineratedWer": false,
    "mrfOptions": {
      "recycled": 0
    }
  },
  {
    "wasteRecordId": 344,
    "wasteDestinationId": 4,
    "fromDate": "2/1/2022",
    "toDate": "2/28/2022",
    "wasteStream": "Plastics",
    "tonnes": 1.1013,
    "incineratedWer": false,
    "mrfOptions": {
      "recycled": 0
    }
  },
  ...
  {
    "wasteRecordId": 354,
    "wasteDestinationId": 4,
    "fromDate": "12/1/2022",
    "toDate": "12/31/2022",
    "wasteStream": "Plastics",
    "tonnes": 0.9863,
    "incineratedWer": false,
    "mrfOptions": {
      "recycled": 0
    }
  }
]

Summary: Provides a list of waste records for the specified waste destination

HTTP Request

GET /api/v1/wasterecords/{wasteDestinationId}

Parameters

Name Located in Description Required Type
wasteDestinationId path A valid id of a waste destination Yes integer

Response Body

The response body will be a list of waste records associated with the waste destination specified by the wasteDestinationId parameter.

Attribute Type and description
wasteRecordId integer
The SIERA-generated id of the waste record
wasteDestinationId integer
The specified waste destination id
fromDate string
The start date of the waste record, in the format m/d/yyyy
toDate string
The end date of the waste record, in the format m/d/yyyy
wasteStream enumeration
A valid stream type from the waste stream enumeration
tonnes float
The total amount of waste moved to the waste destination
incineratedWer boolean
A boolean flag indicating if the waste being uploaded passed through a waste energy recycling (WER) facility. This only applies to Incinerator and MRFIncinerator waste destinations. Any waste uploaded with this flag set will appear in the incineratedWer field of the summary.
mrfOptions.recycled float
A decimal percentage reflecting the amount of waste which was recycled at the waste detination. This only applies to MRFIncinerator, MRFLandfill or MRFUnknown waste destinations

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
500 Server error

Upload waste records

Like consumption utility invoices, waste record uploads represent periods in time and so have start and end dates. The endpoint returns a collection of results indicating which records were successfully uploaded and which failed to upload and the reason.

The results are organised into the following lists:

Successful Uploads
Waste records which were successfully uploaded into SIERA

Exact Matches
Waste records which were rejected as an existing waste record had the same start and end date. If the parameter forceExactMatchUpload is set to true, then these records will overwrite the existing records and appear in the Successful Uploads list.

Overlap Matches
Waste records which were rejected as existing records overlap the start and end dates of existing waste records.

Instance Errors
Waste records which failed to upload because the associated waste destination or asset does not exist in the API-caller's SIERA instance

Other Errors
Waste records which were rejected along with the reason for the rejection.

POST /api/v1/wasterecords/{forceExactMatchUpload}

curl POST https://api.sieraglobal.com/api/v1/wasterecords/false \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON    
  [
    {
      "wasteDestinationId": 4,
      "fromDate": "2/1/2022",
      "toDate": "2/28/2022",
      "wasteStream": "Plastics",
      "tonnes": 1.1013,
      "incineratedWer": false,
      "mrfOptions": {
        "recycled": 0
      }
    },
    {
      "wasteDestinationId": 4,
      "fromDate": "1/1/2022",
      "toDate": "12/31/2020",
      "wasteStream": "Plastics",
      "tonnes": 12.2743,
      "incineratedWer": false,
      "mrfOptions": {
        "recycled": 0
      }
    }
  ]

Response (200)

{
  "success": [
    {
      "wasteRecordId": 351,
      "wasteDestinationId": 4,
      "fromDate": "1/1/2022",
      "toDate": "12/31/2020",
      "wasteStream": "Plastics",
      "tonnes": 12.2743,
      "incineratedWer": false,
      "mrfOptions": {
        "recycled": 0
      }
    }
  ],
  "exactMatch": [
    {
      "wasteRecordId": 0,
      "wasteDestinationId": 4,
      "fromDate": "2/1/2022",
      "toDate": "2/28/2022",
      "wasteStream": "Plastics",
      "tonnes": 1.1013,
      "incineratedWer": false,
      "mrfOptions": {
        "recycled": 0
      }
    }
  ],
  "overlapErrors": [],
  "instanceErrors": [],
  "errors": []
}

Summary: Upload waste records

HTTP Request

POST /api/v1/wasterecords/{forceExactMatchUpload}

Parameters

Name Located in Description Required Type
forceExactMatchUpload path A boolean flag instructing the API to overwrite existing waste records with a matching start and end date Yes boolean

Request body

Attribute Type and description
wasteDestinationId integer
The specified waste destination id
fromDate string
The start date of the waste record, in the format m/d/yyyy
toDate string
The end date of the waste record, in the format m/d/yyyy
wasteStream enumeration
A valid stream type from the waste stream enumeration
tonnes float
The total amount of waste moved to the waste destination
incineratedWer boolean
A boolean flag indicating if the waste being uploaded passed through a waste energy recycling (WER) facility. This only applies to Incinerator and MRFIncinerator waste destinations. Any waste uploaded with this flag set will appear in the incineratedWer field of the summary.
mrfOptions.recycled float
A decimal percentage reflecting the amount of waste which was recycled at the waste detination. This only applies to MRFIncinerator, MRFLandfill or MRFUnknown waste destinations

Response Body

The response body will include a collection of results indicating which records were successfully uploaded and which failed to upload and the reason.

Attribute Type and description
wasteRecordId integer
The SIERA-generated id of the waste destination
wasteDestinationId integer
The specified waste destination id
fromDate string
The start date of the waste record, in the format m/d/yyyy
toDate string
The end date of the waste record, in the format m/d/yyyy
wasteStream enumeration
A valid stream type from the waste stream enumeration
tonnes float
The total amount of waste moved to the waste destination
incineratedWer boolean
A boolean flag indicating if the waste being uploaded passed through a waste energy recycling (WER) facility. This only applies to Incinerator and MRFIncinerator waste destinations. Any waste uploaded with this flag set will appear in the incineratedWer field of the summary.
mrfOptions.recycled float
A decimal percentage reflecting the amount of waste which was recycled at the waste detination. This only applies to MRFIncinerator, MRFLandfill or MRFUnknown waste destinations
errors string
A description of any other error which has occured when the upload was attempted

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
500 Server error

Delete waste records

DELETE /api/v1/wasterecords

curl -X DELETE https://api.sieraglobal.com/api/v1/wasterecords \
  -H "Authorization: Bearer $ACCESS_TOKEN" 
  -V "Content-Type: application/json" \
  -d @- <<JSON    
  [
      343, 374, 345
  ]

Response (200)

{
  "success": [ 343 ],
  "instanceerror": [ 374 ],
  "error": [
    {
      "recordId": 345,
      "error": "Waste destination does not exist."
    }
  ]
}

Waste record delete requests return a list of result.

The results are organised into the following lists:

Successful Deletions
Waste records which were successfully deleted

Instance Errors
Waste records which failed to delete because the associated meter or asset does not exist in the API-caller's SIERA instance

Errors
Waste records which failed to delete and an error description explaining the error message

Summary: Deletes waste records by ID

HTTP Request

DELETE /api/v1/wasterecords

Request body

The request body is a json array of the waste record IDs to be deleted

Response Body

The response body will include a list of results: successful uploads, instance errors or general errors. Successful uploads and instance errors will only contain the related recordId, whilst the general errors will also contain a description of the error.

Attribute Type and description
recordId integer
The id of the waste record
error string
A description of the error which has occurred

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the specified waste record id was not found
500 Server error

Validation rules

When uploading new waste records or updating existing, SIERA will apply the following rules and if they are not met, a response of 400 will be returned with an error message and the field causing the validation failure. As waste records also handles bulk operations, some endpoints return results in lists. In these cases, some validations may be returned in the result and not cause a 400 response code.

The validation requirements for consumption are:

  1. When uploading a new waste record, the wasteRecordId must be 0 or null.
  2. When updating a waste record, the wasteDestinationId must be of an existing waste destination in SIERA.
  3. The fromDate and toDate must be provided, and in the dd/mm/yy format.
  4. If mrfOptions are provided, or a mrfOptions.Recycled over 0, the related waste destination must have a wasteDestination type of MrfIncinerator, MRFLandfill, or MRFUnknown.

Action Plans

The action plan endpoints allows uploading of action plan information relating to assets such as ESG-related initiatives and improvement programs. The endpoints provide the ability to download all actions, update individual actions, and delete actions.

Get all action plans

GET /api/v1/actionplans

curl https://api.sieraglobal.com/api/v1/actionplans \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)


[
    {
        "actionId": 2,
        "assetId": 2,
        "actionDescription": "Upgrade lighting to LED",
        "impact": "Energy",
        "approved": true,
        "status": "AgreedActions",
        "current": 350,
        "target": 200,
        "cost": "Low",
        "costType": "RevenueServiceCharge",
        "scope": "WholeBuilding",
        "manager": "Jeff Parsons",
        "completion": "",
        "dueDate": "9/1/2022",
        "currency": "GBP",
        "utilityType": "NotApplicable",
        "performanceMeasure": "InstallationOfHighEfficiencyEquipment",
        "targetUsagePercentage": 42.86
    },
    {
        "actionId": 3,
        "assetId": 2,
        "actionDescription": "Replace southfacing windows with high-efficiency glazing",
        "impact": "Energy",
        "approved": true,
        "status": "AgreedActions",
        "current": 600,
        "target": 300,
        "cost": "12000",
        "costType": "RevenueServiceCharge",
        "scope": "WholeBuilding",
        "manager": "Jeff Parsons",
        "completion": "",
        "dueDate": "9/1/2022",
        "currency": "GBP",
        "utilityType": "NotApplicable",
        "performanceMeasure": "WindowReplacements",
        "targetUsagePercentage": 50
    },
]

Summary: Provides a list of all the action plans

HTTP Request

GET /api/v1/actionplans

Response Body

The response body will be a list of action plans.

Attribute Type and description
actionId integer
The id of the action plan
assetId integer
The id of the asset
actionDescription string
A description of the action plan
impact string
The utility or utility group affected by the action
approved boolean
A boolean flag to indicate if the action plan has been approved or not
status enumeration
A valid action status from the action status enumeration
current float
The current usage amount related to this action
target float
A target usage the action is hoped to achieve
cost string
A text description of the costs of the action. This can be a number amount or relative description such as high or low.
costType enumeration
A valid cost type from the action cost type enumeration
scope enumeration
A valid floor area scope from the action scope enumeration
manager string
The name of a person who is considered the manager of this action
completion datetime
The actual completion date of the action, in the format m/d/yyyy
dueDate datetime
The expected completion date of the action, in the format m/d/yyyy
currency string
The currency of the costs related to the action, of GBP, USD or EUR.
utilityType enumeration
A valid utility from the action utility enumeration
performanceMeasure enumeration
A valid measure description from the action measure description enumeration
targetUsagePercentage float
A read-only percentage change between the current and target values of the action

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the specified waste record id was not found
500 Server error

Get an action plan

GET /api/v1/actionplans/{actionId}

curl https://api.sieraglobal.com/api/v1/actionplans/6 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

{
  "actionId": 6,
  "assetId": 2,
  "actionDescription": "Upgrade lighting to LED",
  "impact": "Energy",
  "approved": true,
  "status": "AgreedActions",
  "current": 350,
  "target": 200,
  "cost": "Low",
  "costType": "RevenueServiceCharge",
  "scope": "WholeBuilding",
  "manager": "Jeff Parsons",
  "completion": "",
  "dueDate": "9/1/2022",
  "currency": "GBP",
  "utilityType": "NotApplicable",
  "performanceMeasure": "InstallationOfHighEfficiencyEquipment",
  "targetUsagePercentage": 42.86
}

Summary: Provides an action plan

HTTP Request

GET /api/v1/actionplans/{actionId}

Parameters

Name Located in Description Required Type
actionId path A valid id of an action plan stored in SIERA Yes integer

Response Body

The response body will be the action plan associated with the specified actionId parameter.

Attribute Type and description
actionId integer
The id of the action plan
assetId integer
The id of the asset
actionDescription string
A description of the action plan
impact string
The utility or utility group affected by the action
approved boolean
A boolean flag to indicate if the action plan has been approved or not
status enumeration
A valid action status from the action status enumeration
current float
The current usage amount related to this action
target float
A target usage the action is hoped to achieve
cost string
A text description of the costs of the action. This can be a number amount or relative description such as high or low.
costType enumeration
A valid cost type from the action cost type enumeration
scope enumeration
A valid floor area scope from the action scope enumeration
manager string
The name of a person who is considered the manager of this action
completion datetime
The actual completion date of the action, in the format m/d/yyyy
dueDate datetime
The expected completion date of the action, in the format m/d/yyyy
currency string
The currency of the costs related to the action, of GBP, USD or EUR.
utilityType enumeration
A valid utility from the action utility enumeration
performanceMeasure enumeration
A valid measure description from the action measure description enumeration
targetUsagePercentage float
A read-only percentage change between the current and target values of the action

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the specified waste record id was not found
500 Server error

Upload a new action plan

POST /api/v1/actionplans

curl POST https://api.sieraglobal.com/api/v1/actionplans \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON  
  {
      "assetId": 2,
      "actionDescription": "Complete reinsulation of external wall",
      "impact": "Energy",
      "approved": true,
      "status": "AgreedActions",
      "current": 7900,
      "target": 5000,
      "cost": "34500",
      "costType": "RevenueServiceCharge",
      "scope": "WholeBuilding",
      "manager": "Sue Brown",
      "completion": "",
      "dueDate": "5/1/2022",
      "currency": "GBP",
      "utilityType": "NotApplicable",
      "performanceMeasure": "WallOrRoofInsulation"
    }

Response (201)

{
  "actionId": 5
}

Summary: Upload a new action plan

HTTP Request

POST /api/v1/actionplans

Request body

Attribute Type and description
assetId integer
The id of the asset
actionDescription string
A description of the action plan
impact string
The utility or utility group affected by the action
approved boolean
A boolean flag to indicate if the action plan has been approved or not
status enumeration
A valid action status from the action status enumeration
current float
The current usage amount related to this action
target float
A target usage the action is hoped to achieve
cost string
A text description of the costs of the action. This can be a number amount or relative description such as high or low.
costType enumeration
A valid cost type from the action cost type enumeration
scope enumeration
A valid floor area scope from the action scope enumeration
manager string
The name of a person who is considered the manager of this action
completion datetime
The actual completion date of the action, in the format m/d/yyyy
dueDate datetime
The expected completion date of the action, in the format m/d/yyyy
currency string
The currency of the costs related to the action, of GBP, USD or EUR.
utilityType enumeration
A valid utility from the action utility enumeration
performanceMeasure enumeration
A valid measure description from the action measure description enumeration

Response Body

The response body will a new action plan ID relating to the uploaded action plan

Attribute Type and description
actionId integer
The SIERA-generated id of the new action plan

Responses

Code Description
201 Created
400 Validation failure
401 Unauthorised, the header token expired or is missing
404 Not found, the specified asset id was not found
500 Server error

Update an action plan

PUT /api/v1/actionplans/{actionId}

curl PUT https://api.sieraglobal.com/api/v1/actionplans/2 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON
  {
      "actionId": 2,
      "assetId": 2,
      "actionDescription": "Complete reinsulation of external wall",
      "impact": "Energy",
      "approved": true,
      "status": "AgreedActions",
      "current": 9100,
      "target": 5000,
      "cost": "29500",
      "costType": "RevenueServiceCharge",
      "scope": "WholeBuilding",
      "manager": "Sue Brown",
      "completion": "",
      "dueDate": "8/1/2022",
      "currency": "GBP",
      "utilityType": "NotApplicable",
      "performanceMeasure": "WallOrRoofInsulation"
    }

Response (200)

Summary: Updates an existing action plan by ID

HTTP Request

PUT /api/v1/actionplan/{actionId}

Parameters

Name Located in Description Required Type
actionId path A valid id of an action plan stored in SIERA Yes integer

Request body

Attribute Type and description
actionId integer
The id of the action plan
assetId integer
The id of the asset
actionDescription string
A description of the action plan
impact string
The utility or utility group affected by the action
approved boolean
A boolean flag to indicate if the action plan has been approved or not
status enumeration
A valid action status from the action status enumeration
current float
The current usage amount related to this action
target float
A target usage the action is hoped to achieve
cost string
A text description of the costs of the action. This can be a number amount or relative description such as high or low.
costType enumeration
A valid cost type from the action cost type enumeration
scope enumeration
A valid floor area scope from the action scope enumeration
manager string
The name of a person who is considered the manager of this action
completion datetime
The actual completion date of the action, in the format m/d/yyyy
dueDate datetime
The expected completion date of the action, in the format m/d/yyyy
currency string
The currency of the costs related to the action, of GBP, USD or EUR.
utilityType enumeration
A valid utility from the action utility enumeration
performanceMeasure enumeration
A valid measure description from the action measure description enumeration

Responses

Code Description
201 Created
400 Validation failure
401 Unauthorised, the header token expired or is missing
404 Not found, the specified action plan id was not found
500 Server error

Delete a action plan

DELETE /api/v1/actionplans/{actionId}

curl -X DELETE https://api.sieraglobal.com/api/v1/actionplans/4 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

Summary: Deletes an existing action plan by ID

HTTP Request

DELETE /api/v1/actionplans/{actionId}

Parameters

Name Located in Description Required Type
actionId path The id of the action plan to be deleted in SIERA Yes integer

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the specified action plan id was not found
500 Server error

Validation rules

When uploading new waste destinations or updating existing, SIERA will apply the following rules and if they are not met, a response of 400 will be returned with an error message and the field causing the validation failure.

The validation requirements for waste detinations are:

  1. When uploading a new action plan, the actionId must be 0 or null.
  2. When updating an action plan, the actionId must be of an existing action plan in SIERA.
  3. The assetId must exist in SIERA.
  4. The action must not be currently part of a survey which has been submitted. If this is encountered contact SIERA Support.
  5. The impact and performanceMeasure must be in a valid combination (as some measures may only apply to certain utilities or impacts). The table below details the valid combinations
Impact Measure
Energy AMR
Energy AutomationSystemUpgradesOrReplacements
Energy InstallationOfHighEfficiencyEquipment
Energy InstallationOfOnSiteRenewableEnergy
Energy ManagementSystemsUpgradesOrReplacements
Energy OccupierEngagementOrInformationalTechnologies
Energy TechnicalAssessmentEnergy
Energy WallOrRoofInsulation
Energy WindowReplacements
Water CoolingTower
Water DripOrSmartIrrigation
Water HighEfficiencyOrDryFixtures
Water LeakDetectionSystem
Water MeteringOfWaterSubsystems
Water OnSiteWasteWaterTreatment
Water ReuseOfStormWaterOrGreyWater
Waste CompostingLandscapeOrFoodWaste
Water DroughtTolerantOrNativeLandscaping
Waste OngoingWastePerformanceMonitoring
Waste OnSiteWasteWaterTreatment
Waste Recycling
Waste WasteStreamAudit
TenantEngagement BuildingSpecificCommunication
TenantEngagement FeedbackSessions
TenantEngagement Other
TenantEngagement SocialMediaOnlinePlatform
TenantEngagement TenantMeetingsIncludingSustainability
TenantEngagement TenantsReceiveFeedbackOnPerformance
TenantEngagement TenantSustainabilityEvents
TenantEngagement TenantSustainabilityGuide
TenantEngagement TenantSustainabilityTraining

EPCs

Energy Performance Certificates (EPCs) exist in SIERA in 2 forms:
1. the list of EPC schemes and their ratings which are defined in a SIERA instance
2. the record of an EPC rating given to an asset or asset unit for a given EPC scheme.

The EPC endpoints allow a user to upload the record of an EPC for an asset and define any EPC scheme along with the rating bands it uses. This way, SIERA can accomodate any kind of EPC.

The EPC endpoints allow a user to upload the record of an EPC for an asset or asset unit whcih can be stored by referencing an EPC scheme which exists in the API caller's SIERA instance. When recording asset or unit EPCs, it's important to record the floor area they relate to. Many areas use the floor area of EPCs on asset units, to calculate an aggregated weighted average for unit EPCs to produce an overall asset rating.

Get all EPC records

GET /api/v1/epcs

curl https://api.sieraglobal.com/api/v1/epcs \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)


[
  {
    "epcId": 12,
    "assetId": 3,
    "rating": "A",
    "certificateReferenceNumber": "EPC1",
    "score": 10,
    "date": "2021-12-22T09:14:12.784Z",
    "expiry": "2021-12-22T09:14:12.784Z",
    "scheme": {
      "epcSchemeId": 1,
      "description": "EVORA standard EPC scheme",
      "invertedScoring": false,
      "ratings": [
        {
            "ratingId": 1,
            "epcSchemeId": 1,
            "rating": "A+",
            "from": 0,
            "to": 29
        },
        {
            "ratingId": 2,
            "epcSchemeId": 1,
            "rating": "A",
            "from": 30,
            "to": 49
        }
        ...
        {
            "ratingId": 8,
            "epcSchemeId": 1,
            "rating": "G",
            "from": 200,
            "to": 999
        }
      ],
      "isDefault": true
    },
    "scope": "Unit",
    "unit": {
      "unitId": 12,
      "unitName": "Unit A",
      "unitReference": "TAC-234",
      "occupier": "Pets At Home",
      "actionNotes": "",
      "gia": 1100,
      "nla": 900,
      "measurementUnit": "M2",
      "vacant": false,
      "leaseStart": "2020-12-17T12:00:00.000Z",
      "leaseLength": 24,
      "leaseExpiry": "2022-12-17T12:00:00.000Z",
      "leaseBreak": "",
      "erv": 1200,
      "fri": false,
      "epcExempt": false
    },
    "comment": "[2021-11-09] I'm a comment!",
    "note" : "A single EPC comment"
  },
  {
    "epcId": 13,
    "assetId": 4,
    "rating": "A",
    "certificateReferenceNumber": "EPC2",
    "score": 15,
    "date": "2021-12-22T09:14:12.784Z",
    "expiry": "2021-12-22T09:14:12.784Z",
    "scheme": {
      "epcSchemeId": 1,
      "description": "EVORA standard EPC scheme",
      "invertedScoring": false,
      "ratings": [
        {
            "ratingId": 1,
            "epcSchemeId": 1,
            "rating": "A+",
            "from": 0,
            "to": 29
        },
        {
            "ratingId": 2,
            "epcSchemeId": 1,
            "rating": "A",
            "from": 30,
            "to": 49
        }
        ...
        {
            "ratingId": 8,
            "epcSchemeId": 1,
            "rating": "G",
            "from": 200,
            "to": 999
        }
      ],
      "isDefault": true
    },
    "scope": "WholeBuilding",
    "unit": null,
    "comment": "[2021-11-09] I'm a comment!",
    "note" : "A single EPC comment"
  }
]

Summary: Provides a list of all the EPC records in SIERA

HTTP Request

GET /api/v1/epcs

Response Body

The response body will be a list of all the EPC records in SIERA.

Attribute Type and description
epcId integer
The SIERA-generated id of the EPC record
assetId integer
The id of the asset this EPC record relates to
rating string
A rating generated from the EPC scheme the EPC record relates to
certificateReferenceNumber string
The certificate reference number of the EPC if one is available
score integer
The score achieved of the EPC record
date datetime
The date of the EPC certificate
expiry datetime
The expiry date of the EPC certificate stored in SIERA
scheme.epcSchemeId integer
The SIERA-generated id of the EPC scheme
scheme.description string
The name of the related EPC scheme
scheme.invertedScoring boolean
A boolean flag indicating if the scoring of the scheme considers 0 the lowest rating or the highest; true if 0 is the lowest, false otherwise
scheme.isDefault enumeration
A boolean flag indicating if a scheme is a SIERA default scheme or not
scheme.ratings.ratingId integer
The SIERA-generated id of an EPC scheme rating
scheme.ratings.epcSchemeId integer
The id of the parent EPC ccheme
scheme.ratings.rating datetime
The letter given to an EPC scheme rating
scheme.ratings.from datetime
The lower bound value of an EPC scheme rating
scheme.ratings.to float
The upper bound value of an EPC scheme rating
scope enumeration
Indicates if the EPC is related to a unit or whole building. Must be a valid item from the EPC scope enumeration
unit.unitId integer
The SIERA-generated id of the asset unit
unit.unitName string
The name of the asset unit
unit.unitReference string
The asset unit reference
unit.occupier string
The name of the current occupier of the unit
unit.gia float
The Gross Internal Area (GIA) of the asset, measured in units indicated by the measurement unit. This may be null
unit.nla float
The Net Lettable Area (NLA) of the asset, measured in units indicated by the measurement unit. This may be null
unit.measurementUnit enumeration
The unit of measurement used to indicate floor area of this asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
unit.leaseStart datetime
The start date of the tenant of this unit's lease
unit.leaseLength integer
The length in months of the tenant of this unit's lease
unit.leaseExpiry datetime
The expiry date of the tenant of this unit's lease
unit.leaseBreak datetime
The start date of a break in the tenant of this unit's lease
unit.erv float
The estimated rental value (ERV) of this unit
unit.fri boolean
A boolean flag indicating if the current lease is Full Repairing and Insuring (FRI) or not
unit.epcExempt boolean
A boolean flag indicating if this unit has an EPC exemption or not
comment string
The latest comment that has been recorded on the EPC record
note string
A single note that can be recorded against an EPC record

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the specified EPC id was not found
500 Server error

Get an EPC record

curl https://api.sieraglobal.com/api/v1/epcs/12 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)


{
    "epcId": 12,
    "assetId": 3,
    "rating": "A",
    "certificateReferenceNumber": "EPC1",
    "score": 10,
    "date": "2021-12-22T09:14:12.784Z",
    "expiry": "2021-12-22T09:14:12.784Z",
    "scheme": {
      "epcSchemeId": 1,
      "description": "EVORA standard EPC scheme",
      "invertedScoring": false,
      "ratings": [
        {
            "ratingId": 1,
            "epcSchemeId": 1,
            "rating": "A+",
            "from": 0,
            "to": 29
        },
        {
            "ratingId": 2,
            "epcSchemeId": 1,
            "rating": "A",
            "from": 30,
            "to": 49
        }
        ...
        {
            "ratingId": 8,
            "epcSchemeId": 1,
            "rating": "G",
            "from": 200,
            "to": 999
        }
      ],
      "isDefault": true
    },
    "scope": "Unit",
    "unit": {
      "unitId": 12,
      "unitName": "Unit A",
      "unitReference": "TAC-234",
      "occupier": "Pets At Home",
      "actionNotes": "",
      "gia": 1100,
      "nla": 900,
      "measurementUnit": "M2",
      "vacant": false,
      "leaseStart": "2020-12-17T12:00:00.000Z",
      "leaseLength": 24,
      "leaseExpiry": "2022-12-17T12:00:00.000Z",
      "leaseBreak": "",
      "erv": 1200,
      "fri": false,
      "epcExempt": false
    },
    "comment": "[2021-11-09] I'm a comment!",
    "note" : "A single note that can be recorded against an EPC record"
  }

HTTP Request

GET /api/v1/epcs/{epcId}

Parameters

Name Located in Description Required Type
epcId path A valid id of an EPC record stored in SIERA Yes integer

Response Body

The response body will the specified EPC record which matches the epcId given as a parameter.

Attribute Type and description
epcId integer
The SIERA-generated id of the EPC record
assetId integer
The id of the asset this EPC record relates to
rating string
A rating generated from the EPC scheme the EPC record relates to
certificateReferenceNumber string
The certificate reference number of the EPC if one is available
score integer
The score achieved of the EPC record
date datetime
The date of the EPC certificate
expiry datetime
The expiry date of the EPC certificate stored in SIERA
scheme.epcSchemeId integer
The SIERA-generated id of the EPC scheme
scheme.description string
The name of the related EPC scheme
scheme.invertedScoring boolean
A boolean flag indicating if the scoring of the scheme considers 0 the lowest rating or the highest; true if 0 is the lowest, false otherwise
scheme.isDefault enumeration
A boolean flag indicating if a scheme is a SIERA default scheme or not
scheme.ratings.ratingId integer
The SIERA-generated id of an EPC scheme rating
scheme.ratings.epcSchemeId integer
The id of the parent EPC ccheme
scheme.ratings.rating datetime
The letter given to an EPC scheme rating
scheme.ratings.from datetime
The lower bound value of an EPC scheme rating
scheme.ratings.to float
The upper bound value of an EPC scheme rating
scope enumeration
Indicates if the EPC is related to a unit or whole building. Must be a valid item from the EPC scope enumeration
unit.unitId integer
The SIERA-generated id of the asset unit
unit.unitName string
The name of the asset unit
unit.unitReference string
The asset unit reference
unit.occupier string
The name of the current occupier of the unit
unit.gia float
The Gross Internal Area (GIA) of the asset, measured in units indicated by the measurement unit. This may be null
unit.nla float
The Net Lettable Area (NLA) of the asset, measured in units indicated by the measurement unit. This may be null
unit.measurementUnit enumeration
The unit of measurement used to indicate floor area of this asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
unit.leaseStart datetime
The start date of the tenant of this unit's lease
unit.leaseLength integer
The length in months of the tenant of this unit's lease
unit.leaseExpiry datetime
The expiry date of the tenant of this unit's lease
unit.leaseBreak datetime
The start date of a break in the tenant of this unit's lease
unit.erv float
The estimated rental value (ERV) of this unit
unit.fri boolean
A boolean flag indicating if the current lease is Full Repairing and Insuring (FRI) or not
unit.epcExempt boolean
A boolean flag indicating if this unit has an EPC exemption or not
comment string
The latest comment that has been recorded on the EPC record
note string
A single note that can be recorded against an EPC record

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the specified EPC id was not found
500 Server error

Upload a new EPC record

POST /api/v1/epcs

curl POST https://api.sieraglobal.com/api/v1/epcs \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON  
  {
    "assetId": 4,   
    "certificateReferenceNumber": "EPC3",
    "score": 17,
    "date": "2021-12-22T09:14:12.784Z",
    "schemeId": 2,
    "scope": "WholeBuilding",
    "unitId": null,
    "note" :null
  }

Response (201)

{
  "epcId": 34
}

Summary: Upload a new EPC record

HTTP Request

POST /api/v1/epcs

Request body

Attribute Type and description
assetId integer
The id of the asset this EPC record relates to
certificateReferenceNumber string
The certificate reference number of the EPC if one is available
score integer
The score achieved of the EPC record
date datetime
The date of the EPC certificate
epcSchemeId integer
The ID of the related scheme
scope enumeration
Indicates if the EPC is related to a unit or whole building. Must be a valid item from the EPC scope enumeration
unitId integer
The ID of the related unit. This is mandatory when scope is set to "Unit"
note string
A single note that can be recorded against an EPC record

Response Body

The response body will a new epc ID relating to the uploaded EPC

Attribute Type and description
epcId integer
The SIERA-generated id of the new EPC

Responses

Code Description
201 Created
400 Validation failure
401 Unauthorised, the header token expired or is missing
500 Server error

Update an EPC record

PUT /api/v1/epcs/{epcId}

curl PUT https://api.sieraglobal.com/api/v1/epcs/13 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON 
  {
    "epcId": 13
    "assetId": 4,   
    "certificateReferenceNumber": "EPC12",
    "score": 20,
    "date": "2021-11-07T08:11:23.813Z",
    "epcSchemeId": 2,
    "scope": "Unit",
    "unitId": 43,
    "note":null
  }

Response (200)

Summary: Updates an existing EPC by ID

HTTP Request

PUT /api/v1/epcs/{epcId}

Parameters

Name Located in Description Required Type
epcId path A valid id of an EPC stored in SIERA Yes integer

Request body

Attribute Type and description
epcId integer
The id of EPC record to be updated
assetId integer
The id of the asset this EPC record relates to
certificateReferenceNumber string
The certificate reference number of the EPC if one is available
score integer
The score achieved of the EPC record
date datetime
The date of the EPC certificate
epcSchemeId integer
The ID of the related scheme
scope enumeration
Indicates if the EPC is related to a unit or whole building. Must be a valid item from the EPC scope enumeration
unitId integer
The ID of the related unit. This is mandatory when scope is set to "Unit"
note string
The latest note that has been recorded on the EPC record

Responses

Code Description
200 OK
400 Validation failures
401 Unauthorised, the header token expired or is missing
500 Server error

Delete an EPC record

DELETE /api/v1/epcs/{epcId}

curl -X DELETE https://api.sieraglobal.com/api/v1/epcs/12 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

Summary: Deletes an existing EPC record by ID

HTTP Request

DELETE /api/v1/epcs/{epcId}

Parameters

Name Located in Description Required Type
epcId path A valid id of an EPC record stored in SIERA Yes integer

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the EPC was not found
500 Server error

Validation rules

When uploading new EPCs or updating existing, SIERA will apply the following rules and if they are not met, a response of 400 will be returned with an error message and the field causing the validation failure.

The validation requirements for EPCs are:

  1. When uploading a new EPC, the epcId must be 0 or null.
  2. When updating an EPC, the epcId must be of an existing EPC in SIERA.
  3. The assetId must exist in SIERA.
  4. The unitId must exist in SIERA if used.
  5. If the scope is unit then a valid unitId must be present

EPC Schemes

Energy Performance Certificates (EPCs) exist in SIERA in 2 forms:
1. the list of EPC schemes and their ratings which are defined in a SIERA instance
2. the record of an EPC rating given to an asset or asset unit for a given EPC scheme.

SIERA provides a standard EPC which is generic in nature and defined by EVORA consultants. The EPC Scheme endpoints allow an API caller to define any EPC scheme along with the rating bands it uses. The scheme may then be referenced and used to upload an EPC record for an asset whose rating will be mapped to an EPC scheme's rating boundaries to produce a letter grading.

The EVORA standard EPC scheme is defined as :

Rating letter Lower bound Upper bound
A+ 0 29
A 30 49
B 50 74
C 75 99
D 100 129
E 130 159
F 160 199
G 200 999

As an example of an EPC record using this scheme, an asset having an whole building EPC with a rating of 36 would be classed as an A.

As EPC Schemes are country-specific, it's recommended to upload appropriate EPC schemes for the assets in an instance.

Get all schemes

GET /api/v1/epcs/schemes

curl https://api.sieraglobal.com/api/v1/epcs/schemes \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)


[
  {
    "epcSchemeId": 1,
    "description": "EVORA standard EPC scheme",
    "invertedScoring": false,
    "ratings": [
      {
        "ratingId": 1,
        "epcSchemeId": 1,
        "rating": "A+",
        "from": 0,
        "to": 29
      },
      {
        "ratingId": 2,
        "epcSchemeId": 1,
        "rating": "A",
        "from": 30,
        "to": 49
      }
      ...
      {
        "ratingId": 8,
        "epcSchemeId": 1,
        "rating": "G",
        "from": 200,
        "to": 999
      }
    ],
    "isDefault": true
  }
]

Summary: Provides a list of all the EPC schemes in SIERA, and the EVORA standard EPC scheme

HTTP Request

GET /api/v1/epcs/schemes

Response Body

The response body will be a list of all the EPC schemes in SIERA, and the EVORA standard EPC scheme.

Attribute Type and description
epcSchemeId integer
The SIERA-generated id of the EPC scheme
description string
The name of the EPC scheme
invertedScoring boolean
A boolean flag indicating if the scoring of the scheme considers 0 the lowest rating or the highest; true if 0 is the lowest, false otherwise
isDefault enumeration
A boolean flag indicating if a scheme is a SIERA default scheme or not
ratings.ratingId integer
The SIERA-generated id of the EPC scheme rating
ratings.epcSchemeId integer
The id of the parent EPC ccheme
ratings.rating datetime
The letter given to an EPC scheme rating
ratings.from datetime
The lower bound value of an EPC scheme rating
ratings.to float
The upper bound value of an EPC scheme rating

Responses

Code Description
200 OK
400 Validation failures
401 Unauthorised, the header token expired or is missing
404 Not found, the EPC was not found
500 Server error

Upload a new scheme

POST /api/v1/epcs/schemes

curl POST https://api.sieraglobal.com/api/v1/epcs/schemes \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON  
  {
    "description": "Custom EPC scheme",
    "invertedScoring": false,
    "ratings": [
      {
        "rating": "A+",
        "from": 0,
        "to": 29
      },
      {
        "rating": "A",
        "from": 30,
        "to": 49
      }
      ...
      {
        "rating": "G",
        "from": 200,
        "to": 999
      }
    ]
  }

Response (201)

{
  "epcSchemeId": 24
}

Summary: Upload a new EPC scheme

HTTP Request

POST /api/v1/epcs/schemes

Request body

Attribute Type and description
description string
The name of the EPC scheme
invertedScoring boolean
A boolean flag indicating if the scoring of the scheme considers 0 the lowest rating or the highest; true if 0 is the lowest, false otherwise
ratings.rating datetime
The letter given to an EPC scheme rating
ratings.from datetime
The lower bound value of an EPC scheme rating
ratings.to float
The upper bound value of an EPC scheme rating

Response Body

The response body will a new EPC scheme ID relating to the uploaded EPC scheme

Attribute Type and description
epcSchemeId integer
The SIERA-generated id of the new EPC scheme

Responses

Code Description
201 Created
400 Validation failures
401 Unauthorised, the header token expired or is missing
500 Server error

Update a scheme

PUT /api/v1/epcs/schemes/{epcSchemeId}

curl PUT https://api.sieraglobal.com/api/v1/epcs/schemes/7 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON 
  {
    "epcSchemeId": 7,
    "description": "Custom EPC scheme",
    "invertedScoring": false
  }

Response (200)

Summary: Updates an existing EPC scheme by ID

HTTP Request

PUT /api/v1/epcs/schemes/{epcSchemeId}

Request body

Attribute Type and description
epcSchemeId integer
The SIERA-generated id of the EPC scheme
description string
The name of the EPC scheme
invertedScoring boolean
A boolean flag indicating if the scoring of the scheme considers 0 the lowest rating or the highest; true if 0 is the lowest, false otherwise

Responses

Code Description
201 Created
400 Validation failures
401 Unauthorised, the header token expired or is missing
404 Not found, the specified EPC scheme id was not found
500 Server error

Delete a scheme

curl -X DELETE https://api.sieraglobal.com/api/v1/epcs/schemes/2 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

Summary: Deletes an existing EPC scheme by ID

HTTP Request

DELETE /api/v1/epcs/schemes/{epcSchemeId}

Parameters

Name Located in Description Required Type
epcSchemeId path The id of the EPC scheme to be deleted in SIERA Yes integer

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the specified EPC ccheme id was not found
500 Server error

Upload a new scheme rating

POST /api/v1/epcs/schemes/{epcSchemeId}/ratings

curl POST https://api.sieraglobal.com/api/v1/epcs/schemes/1/ratings \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON  
  {
    "epcSchemeId": 1,
    "rating": "A+",
    "from": 0,
    "to": 29
  }

Response (201)

{
  "ratingId": 24
}

Summary: Upload a new EPC scheme rating

HTTP Request

POST /api/v1/epcs/schemes/{epcSchemeId}/ratings

Request body

Attribute Type and description
epcSchemeId integer
The id of the parent EPC ccheme
rating datetime
The letter given to an EPC scheme rating
from datetime
The lower bound value of an EPC scheme rating
to float
The upper bound value of an EPC scheme rating

Response Body

The response body will a new EPC scheme rating ID relating to the uploaded EPC scheme rating

Attribute Type and description
ratingId integer
The SIERA-generated id of the new EPC scheme rating

Responses

Code Description
201 Created
400 Validation failures
401 Unauthorised, the header token expired or is missing
404 Not found, the specified unit rate id was not found
500 Server error

Update a scheme rating

PUT /api/v1/epcs/schemes/{epcSchemeId}/ratings/{ratingId}

curl PUT https://api.sieraglobal.com/api/v1/epcs/schemes/1/ratings/1 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON  
  {
    "ratingId": 1,
    "epcSchemeId": 1,
    "rating": "A+",
    "from": 0,
    "to": 10
  }

Response (200)

Summary: Update an EPC scheme rating

HTTP Request

PUT /api/v1/epcs/schemes/{epcSchemeId}/ratings/{ratingId}

Parameters

Name Located in Description Required Type
epcSchemeId path The id of the parent EPC scheme Yes integer
ratingId path The id of the EPC scheme rating Yes integer

Request body

Attribute Type and description
ratingId integer
The id of the EPC scheme rating to be updated
epcSchemeId integer
The id of the parent EPC ccheme
rating datetime
The letter given to an EPC scheme rating
from datetime
The lower bound value of an EPC scheme rating
to float
The upper bound value of an EPC scheme rating

Responses

Code Description
200 OK
400 Validation failures
401 Unauthorised, the header token expired or is missing
404 Not found, the specified EPC scheme rating id was not found
500 Server error

Delete a scheme rating

DELETE /api/v1/epcs/schemes/{schemeId}/ratings/{ratingId}

curl -X DELETE https://api.sieraglobal.com/api/v1/epcs/schemes/1/ratings/1 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

Summary: Deletes an existing EPC scheme rating by ID

HTTP Request

DELETE /api/v1/epcs/schemes/{epcSchemeId}/ratings/{ratingId}

Parameters

Name Located in Description Required Type
epcSchemeId path The id of the parent EPC scheme Yes integer
ratingId path The id of the EPC scheme rating Yes integer

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
401 Not found, the specified EPC scheme rating id was not found
500 Server error

Validation rules

When uploading new EPC schemes or updating existing, SIERA will apply the following rules and if they are not met, a response of 400 will be returned with an error message and the field causing the validation failure.

The validation requirements for EPC schemes are:

  1. When uploading a new EPC scheme, the epcSchemeId must be 0 or null.
  2. When updating an EPC, the epcSchemeId must be of an existing EPC scheme in SIERA.
  3. When uploading or updating an EPC scheme rating, the epcSchemeId must exist in SIERA.

Organisations

The Organisations endpoints allow you to create and manage organisations to associated with assets in SIERA. You can upload new organisations, update organisations or delete them from a given instance in SIERA.

Get all organisations

GET /api/v1/organisations

curl https://api.sieraglobal.com/api/v1/organisations \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)


[
  {
    "organisationId": 1,
    "organisationName": "TPG Financial Services",
    "reportingCurrency": "GBP",
    "reportingMeasurementUnit": "M2",
    "yearStart": 1
  },
  {
    "organisationId": 2,
    "organisationName": "Colias",
    "reportingCurrency": "GBP",
    "reportingMeasurementUnit": "FT2",
    "yearStart": 4
  },
  {
    "organisationId": 3,
    "organisationName": "Sakitai",
    "reportingCurrency": "GBP",
    "reportingMeasurementUnit": "M2",
    "yearStart": 1
  }
]

Summary: Provides a list of all the organisations in SIERA

HTTP Request

GET /api/v1/organisations

Response Body

The response body will be a list of organisations.

Attribute Type and description
organisationId integer
The SIERA-generated id of the organisation
organisationName string
The name of the organisation
reportingCurrency string
The 3-letter code of the currency used for reporting in the organisation
reportingMeasurementUnit enumeration
The unit of measurement used to indicate floor area of the asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
yearStart integer
The month considered the start of the year for the organisation, 1 for a calendar start (January), 4 for financial year start (April)

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the organisation was not found
500 Server error

Get an organisation

GET /api/v1/organisations

curl https://api.sieraglobal.com/api/v1/organisations/2 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

{
  "organisationId": 2,
  "organisationName": "Colias",
  "reportingCurrency": "GBP",
  "reportingMeasurementUnit": "FT2",
  "yearStart": 4
}

Summary: Provides an organisation

HTTP Request

GET /api/v1/organisations

Response Body

The response body will be an organisation.

Attribute Type and description
organisationId integer
The SIERA-generated id of the organisation
organisationName string
The name of the organisation
reportingCurrency string
The 3-letter code of the currency used for reporting in the organisation
reportingMeasurementUnit enumeration
The unit of measurement used to indicate floor area of the asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
yearStart integer
The month considered the start of the year for the organisation, 1 for a calendar start (January), 4 for financial year start (April)

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the organisation was not found
500 Server error

Upload a new organisation

POST /api/v1/organisations

curl POST https://api.sieraglobal.com/api/v1/organisations \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON  
  {
    "organisationName": "PL Green organisation",
    "reportingCurrency": "GBP",
    "reportingMeasurementUnit": "M2",
    "yearStart": 4,
  }

Response (201)

{
  "organisationId": 6
}

Summary: Upload a new organisation

HTTP Request

POST /api/v1/organisations

Request body

Attribute Type and description
organisationName string
The name of the organisation
reportingCurrency string
The 3-letter code of the currency used for reporting in the organisation
reportingMeasurementUnit enumeration
The unit of measurement used to indicate floor area of the asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
yearStart integer
The month considered the start of the year for the organisation, 1 for a calendar start (January), 4 for financial year start (April)

Response Body

The response body will a new organisation ID relating to the uploaded organisation

Attribute Type and description
organisationId integer
The SIERA-generated id of the new organisation

Responses

Code Description
201 Created
401 Unauthorised, the header token expired or is missing
500 Server error

Update an organisation

PUT /api/v1/organisations/{organisationId}

curl PUT https://api.sieraglobal.com/api/v1/organisations/3 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON 
  {
    "organisationName": "PL Green organisation",
    "reportingCurrency": "GBP",
    "reportingMeasurementUnit": "FT2",
    "yearStart": 4
  }

Response (200)

Summary: Updates an existing organisation by ID

HTTP Request

PUT /api/v1/organisations/{organisationId}

Paraorganisations

Name Located in Description Required Type
organisationId path The id of the organisation to be updated in SIERA Yes integer

Request body

Attribute Type and description
organisationId integer
The SIERA-generated id of the organisation
organisationName string
The name of the organisation
reportingCurrency string
The 3-letter code of the currency used for reporting in the organisation
reportingMeasurementUnit enumeration
The unit of measurement used to indicate floor area of the asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
yearStart integer
The month considered the start of the year for the organisation, 1 for a calendar start (January), 4 for financial year start (April)

Responses

Code Description
201 Created
401 Unauthorised, the header token expired or is missing
404 Not found, the specified organisation id was not found
500 Server error

Delete an organisation

DELETE /api/v1/organisations/{organisationId}

curl -X DELETE https://api.sieraglobal.com/api/v1/organisations/2 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

Summary: Deletes an existing organisation by ID

HTTP Request

DELETE /api/v1/organisation/{organisationId}

Paraorganisations

Name Located in Description Required Type
organisationId path The id of the organisation to be deleted in SIERA Yes integer

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the organisation was not found
500 Server error

Validation rules

When uploading new organisations or updating existing, SIERA will apply the following rules and if they are not met, a response of 400 will be returned with an error message and the field causing the validation failure.

The validation requirements for organisations are:

  1. When uploading a new organisation, the organisationId must be 0 or null.
  2. When updating an organisation, the organisationId must be of an existing organisation in SIERA.

Funds

The Funds endpoints allow you to create and manage funds to associated with assets in SIERA. You can upload new funds, update funds or delete them from a given instance in SIERA. Note that a fund must be associated with an organisation and can't exist on its own.

Get all funds

GET /api/v1/funds

curl https://api.sieraglobal.com/api/v1/funds \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)


[
  {
    "fundId": 1,
    "fundName": "TG Pension Fund",
    "reportingCurrency": "GBP",
    "reportingMeasurementUnit": "M2",
    "yearStart": 4,
    "organisationId": 3
  },
  {
    "fundId": 2,
    "fundName": "TF Sustainable Fund",
    "reportingCurrency": "GBP",
    "reportingMeasurementUnit": "M2",
    "yearStart": 4,
    "organisationId": 3
  }
]

Summary: Provides a list of all the funds in SIERA

HTTP Request

GET /api/v1/funds

Response Body

The response body will be a list of funds.

Attribute Type and description
fundId integer
The SIERA-generated id of the fund
fundName string
The name of the fund
reportingCurrency string
The 3-letter code of the currency used for reporting in the fund
reportingMeasurementUnit enumeration
The unit of measurement used to indicate floor area of the asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
yearStart integer
The month considered the start of the year for the fund, 1 for a calendar start (January), 4 for financial year start (April)
organisationId integer
The id of the associated organisation

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the fund was not found
500 Server error

Get a fund

GET /api/v1/funds/{fundId}

curl https://api.sieraglobal.com/api/v1/funds/2 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)


{
  "fundId": 2,
  "fundName": "TF Sustainable Fund",
  "reportingCurrency": "GBP",
  "reportingMeasurementUnit": "M2",
  "yearStart": 1,
  "organisationId": 3
}

Summary: Provides a single fund given an ID

HTTP Request

GET /api/v1/funds/{fundId}

Parameters

Name Located in Description Required Type
fundId path A valid id of a fund stored in SIERA Yes integer

Response Body

The response body will the specified fund which matches the fundId given as a parameter.

Attribute Type and description
fundId integer
The SIERA-generated id of the fund
fundName string
The name of the fund
reportingCurrency string
The 3-letter code of the currency used for reporting in the fund
reportingMeasurementUnit enumeration
The unit of measurement used to indicate floor area of the asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
yearStart integer
The month considered the start of the year for the fund, 1 for a calendar start (January), 4 for financial year start (April)
organisationId integer
The id of the associated organisation

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the fund was not found
500 Server error

Upload a new fund

POST /api/v1/funds

curl POST https://api.sieraglobal.com/api/v1/assets \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON  
  {
    "fundName": "PL Green Fund",
    "reportingCurrency": "GBP",
    "reportingMeasurementUnit": "M2",
    "yearStart": 1,
    "organisationId": 3
  }

Response (201)

{
  "fundId": 6
}

Summary: Upload a new fund

HTTP Request

POST /api/v1/funds

Request body

Attribute Type and description
fundId integer
The SIERA-generated id of the fund
fundName string
The name of the fund
reportingCurrency string
The 3-letter code of the currency used for reporting in the fund
reportingMeasurementUnit enumeration
The unit of measurement used to indicate floor area of the asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
yearStart integer
The month considered the start of the year for the fund, 1 for a calendar start (January), 4 for financial year start (April)
organisationId integer
The id of the associated organisation

Response Body

The response body will a new fund ID relating to the uploaded fund

Attribute Type and description
fundId integer
The SIERA-generated id of the new fund

Responses

Code Description
201 Created
400 Validation failure
401 Not found, the specified organisation id was not found
500 Server error

Update a fund

PUT /api/v1/funds/{fundId}

curl PUT https://api.sieraglobal.com/api/v1/funds/11 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON 
  {
    "fundId": 2
    "fundName": "TF Sustainable Green Fund",
    "reportingCurrency": "GBP",
    "reportingMeasurementUnit": "FT2",
    "yearStart": 1,
    "organisationId": 3
  }

Response (200)

Summary: Updates an existing fund by ID

HTTP Request

PUT /api/v1/funds/{fundId}

Parameters

Name Located in Description Required Type
fundId path The id of the fund to be updated in SIERA Yes integer

Request body

Attribute Type and description
fundId integer
The SIERA-generated id of the fund
fundName string
The name of the fund
reportingCurrency string
The 3-letter code of the currency used for reporting in the fund
reportingMeasurementUnit enumeration
The unit of measurement used to indicate floor area of the asset. Must be a valid item from the measurement unit enumeration (m2 or ft2)
yearStart integer
The month considered the start of the year for the fund, 1 for a calendar start (January), 4 for financial year start (April)
organisationId integer
The id of the associated organisation

Responses

Code Description
201 Created
400 Validation failure, one or more of the enumerations were not correctly identified
401 Unauthorised, the header token expired or is missing
404 Not found, the fund or specified organisationId was not found
500 Server error

Delete a fund

DELETE /api/v1/funds/{fundId}

curl -X DELETE https://api.sieraglobal.com/api/v1/funds/2 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

Summary: Deletes an existing fund by ID

HTTP Request

DELETE /api/v1/funds/{fundId}

Parameters

Name Located in Description Required Type
fundId path The id of the fund to be deleted in SIERA Yes integer

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the fund was not found
500 Server error

Validation rules

When uploading new funds or updating existing, SIERA will apply the following rules and if they are not met, a response of 400 will be returned with an error message and the field causing the validation failure.

The validation requirements for funds are:

  1. When uploading a new fund, the fundId must be 0 or null.
  2. When updating a fund, the fundId must be of an existing fund in SIERA.
  3. The organisationId must be provided and be for a valid organisation in SIERA.

Carbon Factors

Carbon Factors in SIERA indicate how much carbon is emitted per unit of energy. As an example, carbon emission factors for electricity meters allow SIERA to display a kgCO2 for a given kWh of consumption.

SIERA provides default carbon factors which can be used in place of custom carbon factors. These default values were created by EVORA consultants, and can only be selected on meters. They cannot be changed or deleted. The default carbon factors are also purposefully valid from the beginning of 2021 until 2099. SIERA can contain multiple annual rates for each carbon factor. Each rate must have a valid date range over which the factor can be applied. The date ranges of each rate must not overlap, so that given a date a single factor can be chosen.

The default carbon factors are:

Default name Meter Type Valid from Valid to Rate
EVORA default electricity carbon emission factor Electricity 1/1/2021 1/1/2099 0.2123
EVORA default gas carbon emission factor Gas 1/1/2021 1/1/2099 0.184
EVORA default district heating carbon emission factor District Heating 1/1/2021 1/1/2099 0.247
EVORA default district cooling carbon emission factor District Cooling 1/1/2021 1/1/2099 0.247
EVORA default oil carbon emission factor Oil 1/1/2021 1/1/2099 0.268
EVORA default water carbon emission factor Water 1/1/2021 1/1/2099 0

Get all carbon factors

GET /api/v1/carbonfactors

curl https://api.sieraglobal.com/api/v1/carbonfactors \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)


[
  {
      "carbonFactorId": 1,
      "description": "EVORA default electricity carbon emission factor",
      "meterType": "Electricity",
      "factorType": "LocationBased",    
      "isDefault": true,
      "carbonFactorRates": [
        {
          "carbonFactorRateId": 5,          
          "fromDate": "2021-01-01T12:00:00.000Z",
          "toDate": "2099-01-01T12:00:00.000Z",
          "rate": 0.12
        }
      ]
    },
    {
      "carbonFactorId": 2,
      "description": "EVORA default gas carbon emission factor",
      "meterType": "Gas",
      "factorType": "MarketBased",    
      "isDefault": true,
      "carbonFactorRates": [
        {
          "carbonFactorRateId": 6,          
          "fromDate": "2021-01-01T12:00:00.000Z",
          "toDate": "2099-01-01T12:00:00.000Z",
          "rate": 0.12
        }
      ]
    }
]

Summary: Provides a list of all the carbon factors in SIERA, and the SIERA default carbon factors

HTTP Request

GET /api/v1/carbonfactors

Response Body

The response body will be a list of carbon factors in the API caller's instance, and the SIERA default carbon factors.

Attribute Type and description
carbonFactorId integer
The SIERA-generated id of the carbon factor
description string
The name of the carbon factor
meterType enumeration
A valid utility from the meter type enumeration
factorType enumeration
A valid factor type of this factor, either market-based or location-based, from the factor type enumeration
isDefault boolean
A boolean flag indicating if this factor is a SIERA default carbon factor or not
carbonFactorRates.carbonFactorRateId integer
The SIERA-generated id of the rate
carbonFactorRates.fromDate datetime
The start date the carbon factor rate is valid from
carbonFactorRates.toDate datetime
The date the carbon factor rate is valid until
carbonFactorRates.rate float
The carbon factor rate value

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the carbon factor was not found
500 Server error

Get a carbon factor

GET /api/v1/carbonfactors/{carbonFactorId}

curl https://api.sieraglobal.com/api/v1/carbonfactors/2 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)


{
  "carbonFactorId": 2,
  "description": "EVORA default gas carbon emission factor",
  "meterType": "Gas",
  "factorType": "MarketBased",    
  "isDefault": true,
  "carbonFactorRates": [
    {
      "carbonFactorRateId": 6,          
      "fromDate": "2021-01-01T12:00:00.000Z",
      "toDate": "2099-01-01T12:00:00.000Z",
      "rate": 0.12
    }
  ]
}

Summary: Provides a single carbon factor given an ID

HTTP Request

GET /api/v1/carbonfactors/{carbonFactorId}

Parameters

Name Located in Description Required Type
carbonFactorId path A valid id of a carbon factor stored in SIERA Yes integer

Response Body

The response body will the specified carbon factor which matches the carbonFactorId given as a parameter.

Attribute Type and description
carbonFactorId integer
The SIERA-generated id of the carbon factor
description string
The name of the carbon factor
meterType enumeration
A valid utility from the meter type enumeration
factorType enumeration
A valid factor type of this factor, either market-based or location-based, from the factor type enumeration
isDefault boolean
A boolean flag indicating if this factor is a SIERA default carbon factor or not
carbonFactorRates.carbonFactorRateId integer
The SIERA-generated id of the rate
carbonFactorRates.fromDate datetime
The start date the carbon factor rate is valid from
carbonFactorRates.toDate datetime
The date the carbon factor rate is valid until
carbonFactorRates.rate float
The carbon factor rate value

Responses

Code Description
200 OK
400 Validation failure
401 Unauthorised, the header token expired or is missing
500 Server error

Upload a new carbon factor

POST /api/v1/carbonfactors

curl POST https://api.sieraglobal.com/api/v1/carbonfactors \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON  
  {
      "description": "Custom German carbon emission factor",
      "meterType": "Electricity",
      "factorType": "LocationBased",    
      "carbonFactorRates": [
        {
          "fromDate": "2021-01-01T12:00:00.000Z",
          "toDate": "2099-01-01T12:00:00.000Z",
          "rate": 0.12
        }
      ]
    }

Response (201)

{
  "carbonFactorId": 12
}

Summary: Upload a new carbon factor

HTTP Request

POST /api/v1/carbonfactors

Request body

Attribute Type and description
description string
The name of the carbon factor
meterType enumeration
A valid utility from the meter type enumeration
factorType enumeration
A valid factor type of this factor, either market-based or location-based, from the factor type enumeration
carbonFactorRates.fromDate datetime
The start date the carbon factor rate is valid from
carbonFactorRates.toDate datetime
The date the carbon factor rate is valid until
carbonFactorRates.rate float
The carbon factor rate value

Response Body

The response body will a new carbon factor ID relating to the uploaded carbon factor

Attribute Type and description
carbonFactorId integer
The SIERA-generated id of the new carbon factor

Responses

Code Description
200 OK
400 Validation failure
401 Unauthorised, the header token expired or is missing
500 Server error

Update a carbon factor

PUT /api/v1/carbonfactors/{carbonFactorId}

curl PUT https://api.sieraglobal.com/api/v1/carbonfactors/11 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON 
  {
      "description": "Custom France carbon emission factor",
      "meterType": "Electricity",
      "factorType": "LocationBased",    
      "carbonFactorRates": [
        {
          "fromDate": "2021-01-01T12:00:00.000Z",
          "toDate": "2099-01-01T12:00:00.000Z",
          "rate": 0.22
        }
      ]
    }

Response (200)

Summary: Updates an existing carbon factor by ID

HTTP Request

PUT /api/v1/carbonfactors/{carbonFactorId}

Parameters

Name Located in Description Required Type
carbonFactorId path The id of the carbon factor to be updated in SIERA Yes integer

Request body

Attribute Type and description
carbonFactorId integer
The id of the carbon factor
description string
The name of the carbon factor
meterType enumeration
A valid utility from the meter type enumeration
factorType enumeration
A valid factor type of this factor, either market-based or location-based, from the factor type enumeration
carbonFactorRates.carbonFactorRateId integer
The id of the rate
carbonFactorRates.fromDate datetime
The start date the carbon factor rate is valid from
carbonFactorRates.toDate datetime
The date the carbon factor rate is valid until
carbonFactorRates.rate float
The carbon factor rate value

Responses

Code Description
201 Created
400 Validation failure
401 Not found, the specified carbon factor id was not found
500 Server error

Delete a carbon factor

DELETE /api/v1/carbonfactors/{carbonFactorId}

curl -X DELETE https://api.sieraglobal.com/api/v1/carbonfactors/2 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

Summary: Deletes an existing carbon factor by ID

HTTP Request

DELETE /api/v1/carbonfactors/{carbonFactorId}

Parameters

Name Located in Description Required Type
carbonFactorId path The id of the carbon factor to be deleted in SIERA Yes integer

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the specified carbon factor id was not found
500 Server error

Upload a new carbon factor rate

POST /api/v1/carbonfactors/{carbonFactorId}/rates/

curl POST https://api.sieraglobal.com/api/v1/carbonfactors/11/rates \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON  
  {
    "carbonFactorId": 11,
    "rate": 0.13,
    "fromDate": "2022-01-01T12:00:00.000Z",
    "toDate": "2099-01-01T12:00:00.000Z"          
  }

Response (201)

  {
    "rateId": 13,
    "rate": 0.13,
    "fromDate": "2022-01-01T12:00:00.000Z",
    "toDate": "2099-01-01T12:00:00.000Z",         
    "error": ""     
  }

Summary: Upload a new carbon factor rate

HTTP Request

POST /api/v1/carbonfactors/{carbonFactorId}/rates

Parameters

Name Located in Description Required Type
carbonFactorId path The id of the carbon factor to be deleted in SIERA Yes integer

Request body

Attribute Type and description
rateId integer
The id of the parent carbon factor
rate float
The rate value
fromDate datetime
The start date the rate is valid from
toDate datetime
The date the rate is valid until

Response Body

The response body will the new rate with a new rate ID relating to the uploaded carbon rate

Attribute Type and description
rateId integer
The SIERA-generated id of the rate
rate float
The rate value
fromDate datetime
The start date the rate is valid from
toDate datetime
The date the rate is valid until
error string
Any error text from the upload indicating a failure

Responses

Code Description
200 OK
400 Validation failure
401 Unauthorised, the header token expired or is missing
404 Not found, the specified carbon factor id was not found
500 Server error

Update a carbon factor rate

PUT /api/v1/carbonfactors/{carbonFactorId}/rates/{rateId}

curl PUT https://api.sieraglobal.com/api/v1/carbonfactors/11/rates/3 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON  
  {
    "carbonFactorId": 11,
    "rateId": 3,
    "rate": 0.27,
    "fromDate": "2022-01-01T12:00:00.000Z",
    "toDate": "2099-01-01T12:00:00.000Z"          
  }

Response (201)

  {
    "rateId": 13,
    "rate": 0.13,
    "fromDate": "2022-01-01T12:00:00.000Z",
    "toDate": "2099-01-01T12:00:00.000Z",         
    "error": ""
  }

Summary: Update a carbon factor rate

HTTP Request

PUT /api/v1/carbonfactors/{carbonFactorId}/rates/{carbonFactorRateId}

Parameters

Name Located in Description Required Type
carbonFactorId path The parent id of the carbon factor of the rate to be update in SIERA Yes integer
rateId path The id of the rate to be updated in SIERA Yes integer

Request body

Attribute Type and description
carbonFactorId integer
The id of the parent carbon factor
rateId integer
The id of the rate
rate float
The rate value
fromDate datetime
The start date the rate is valid from
toDate datetime
The date the rate is valid until

Responses

Code Description
200 OK
400 Validation failure
401 Unauthorised, the header token expired or is missing
404 Not found, the specified rate or carbon factor id was not found
500 Server error

Delete a carbon factor rate

DELETE /api/v1/carbonfactors/{carbonFactorId}/rates/{carbonFactorRateId}

curl -X DELETE https://api.sieraglobal.com/api/v1/carbonfactors/11/rates/3 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

Summary: Deletes an existing carbon factor by ID

HTTP Request

DELETE /api/v1/carbonfactors/{carbonFactorId}/rates/{rateId}

Parameters

Name Located in Description Required Type
carbonFactorId path The parent id of the carbon factor of the rate to be deleted in SIERA Yes integer
rateId path The id of the carbon factor rate to be deleted in SIERA Yes integer

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the specified rate or carbon factor id was not found
500 Server error

Validation rules

When uploading new carbon factors or updating existing, SIERA will apply the following rules and if they are not met, a response of 400 will be returned with an error message and the field causing the validation failure.

The validation requirements for carbon factors are:

  1. When uploading a new carbon factor, the carbonFactorId must be 0 or null.
  2. When updating a carbon factor, the carbonFactorId must be of an existing carbon factor in SIERA.

The validation requirements for carbon factors rates are:

  1. When uploading a new carbon factor rate, the rateId must be 0 or null.
  2. When updating a carbon factor, the rateId must be of an existing carbon factor rate in SIERA.
  3. The carbonFactorId must be provided and for a valid carbon factor in SIERA.
  4. The fromDate must be before or equal to the toDate. Both must be provided.
  5. The date range specified by fromDate and toDate must not match an existing rate on the same parent carbon factor in SIERA.
  6. The date range specified by fromDate and toDate must not overlap dates of an existing rate on the same parent carbon factor in SIERA.

Unit Rates

Unit rates in SIERA indicate how much a unit of energy costs in financial terms. As an example, unit rates for electricity meters allow SIERA to display a cost for a given kWh of consumption. It's important to bear in mind that unit rates only provide a rough estimation of the cost. When calculating actual costs, per-minute unit rates are used which vary throughout the day. SIERA simply applies a single factor for all consumption on a meter, irrespective of time.

SIERA provides default unit rates which can be used in place of custom unit rates. These default values were created by EVORA consultants, and can only be selected on meters. They cannot be changed or deleted. The default rates are also purposefully valid from the beginning of 2021 until 2099. SIERA can contain multiple annual rates for each unit rate. Each rate must have a valid date range over which the rate can be applied. The date ranges of each rate must not overlap, so that given a date a single rate can be chosen.

The default unit rates are:

Default name Currency Units Valid from Valid to Rate
EVORA standard electricity rate (GBP) GBP kWh 1/1/2021 1/1/2099 0.12
EVORA standard fuel rate (GBP) GBP kWh 1/1/2021 1/1/2099 0.03
EVORA standard water rate (GBP) GBP kWh 1/1/2021 1/1/2099 2.1
EVORA standard electricity rate (USD) USD kWh 1/1/2021 1/1/2099 0.15
EVORA standard fuel rate (USD) USD kWh 1/1/2021 1/1/2099 0.4
EVORA standard water rate (USD) USD kWh 1/1/2021 1/1/2099 3
EVORA standard electricity rate (EUR) EUR kWh 1/1/2021 1/1/2099 0.22
EVORA standard fuel rate (EUR) EUR kWh 1/1/2021 1/1/2099 0.05
EVORA standard water rate (EUR) EUR kWh 1/1/2021 1/1/2099 3.75

Get all unit rates

GET /api/v1/unitrates

curl https://api.sieraglobal.com/api/v1/unitrates \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)


[
  {
    "unitRateID": 1,
    "description": "EVORA standard electricity rate (GBP)",
    "currency": "BritishPound",
    "unit": "kWh",
    "meterType": "Electricity",
    "rates": [
        {
          "rateID": 1,
          "unitRateID": 1,
          "fromDate": "2021-01-01T12:00:00.000Z",
          "toDate": "2099-01-01T12:00:00.000Z",
          "rate": 0.12
        }
      ]
    },
    {
    "unitRateID": 2,
    "description": "EVORA standard fuel rate (GBP)",
    "currency": "BritishPound",
    "unit": "kWh",
    "meterType": null,
    "rates": [
        {
          "rateID": 2,
          "unitRateID": 2,
          "fromDate": "2021-01-01T12:00:00.000Z",
          "toDate": "2099-01-01T12:00:00.000Z",
          "rate": 0.03
        }
      ]
    }
]

Summary: Provides a list of all the unit rates in SIERA, and the SIERA default unit rates

HTTP Request

GET /api/v1/unitrates

Response Body

The response body will be a list of unit rates in the API caller's instance, and the SIERA default unit rates.

Attribute Type and description
unitRateID integer
The SIERA-generated id of the unit rate
description string
The name of the unit rate
currency enumeration
The currency used for reporting in the unit rate, from the currency enumeration
unit string
The units of energy the rate relates to
meterType enumeration
A valid utility from the meter type enumeration
rates.rateID integer
The SIERA-generated id of the rate
rates.unitRateID integer
The id of the parent unit rate
rates.fromDate datetime
The start date the rate is valid from
rates.toDate datetime
The date the rate is valid until
rates.rate float
The rate value

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the unit rate was not found
500 Server error

Get a unit rate

GET /api/v1/unitrates/{unitRateId}

curl https://api.sieraglobal.com/api/v1/unitrates/2 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)


{
    "unitRateID": 2,
    "description": "EVORA standard fuel rate (GBP)",
    "currency": "BritishPound",
    "unit": "kWh",
    "meterType": null,
    "rates": [
        {
          "rateID": 2,
          "unitRateID": 2,
          "fromDate": "2021-01-01T12:00:00.000Z",
          "toDate": "2099-01-01T12:00:00.000Z",
          "rate": 0.03
        }
      ]
    }

Summary: Provides a single unit rate given an ID

HTTP Request

GET /api/v1/unitrates/{unitRateId}

Parameters

Name Located in Description Required Type
unitRateId path A valid id of a unit rate stored in SIERA Yes integer

Response Body

The response body will the specified unit rate which matches the unitRateId given as a parameter.

Attribute Type and description
unitRateID integer
The SIERA-generated id of the unit rate
description string
The name of the unit rate
currency enumeration
The currency used for reporting in the unit rate, from the currency enumeration
unit string
The units of energy the rate relates to
meterType enumeration
A valid utility from the meter type enumeration
rates.rateID integer
The SIERA-generated id of the rate
rates.unitRateID integer
The id of the parent unit rate
rates.fromDate datetime
The start date the rate is valid from
rates.toDate datetime
The date the rate is valid until
rates.rate float
The rate value

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the unit rate was not found
500 Server error

Upload a new unit rate

POST /api/v1/unitrates

curl POST https://api.sieraglobal.com/api/v1/unitrates \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON  
  {
    "description": "Custom electricity rate",
    "currency": "BritishPound",
    "unit": "kWh",
    "meterType": "Electricity",
    "rates": [
      {
        "rate": 0.12,
        "fromDate": "2021-01-01T12:00:00.000Z",
        "toDate": "2099-01-01T12:00:00.000Z"          
      }
    ]
  }

Response (201)

{
  "unitRateId": 11
}

Summary: Upload a new unit rate

HTTP Request

POST /api/v1/unitrates

Request body

Attribute Type and description
description string
The name of the unit rate
currency enumeration
The currency used for reporting in the unit rate, from the currency enumeration
unit string
The units of energy the rate relates to
meterType enumeration
A valid utility from the meter type enumeration
rates.rate float
The rate value
rates.fromDate datetime
The start date the rate is valid from
rates.toDate datetime
The date the rate is valid until

Response Body

The response body will a new unit rate ID relating to the uploaded unit rate

Attribute Type and description
unitRateId integer
The SIERA-generated id of the new unit rate

Responses

Code Description
200 OK
400 Validation failure
401 Unauthorised, the header token expired or is missing
500 Server error

Update a unit rate

PUT /api/v1/unitrates/{unitRateId}

curl PUT https://api.sieraglobal.com/api/v1/unitrates/11 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON 
  {
    "unitRateID": 11,
    "description": "Custom electricity rate",
    "currency": "BritishPound",
    "unit": "kWh",
    "meterType": "Electricity",
    "rates": [
      {
        "unitRateID": 11,
        "rateID": 2,        
        "rate": 0.12,
        "fromDate": "2021-01-01T12:00:00.000Z",
        "toDate": "2099-01-01T12:00:00.000Z"          
      }
    ]
  }

Response (200)

Summary: Updates an existing unit rate by ID

HTTP Request

PUT /api/v1/unitrates/{unitRateId}

Parameters

Name Located in Description Required Type
unitRateId path The id of the unit rate to be updated in SIERA Yes integer

Request body

Attribute Type and description
unitRateID integer
The id of the unit rate to be updated
description string
The name of the unit rate
currency enumeration
The currency used for reporting in the unit rate, from the currency enumeration
unit string
The units of energy the rate relates to
meterType enumeration
A valid utility from the meter type enumeration
rates.rateID integer
The id of the rate to be updated
rates.unitRateID integer
The id of the parent unit rate
rates.fromDate datetime
The start date the rate is valid from
rates.toDate datetime
The date the rate is valid until
rates.rate float
The rate value

Responses

Code Description
200 OK
400 Validation failure
401 Unauthorised, the header token expired or is missing
404 Not found, the specified unit rate id was not found
500 Server error

Delete a unit rate

DELETE /api/v1/unitrates/{unitRateId}

curl -X DELETE https://api.sieraglobal.com/api/v1/unitrates/2 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

Summary: Deletes an existing unit rate by ID

HTTP Request

DELETE /api/v1/unitrates/{unitRateId}

Parameters

Name Located in Description Required Type
unitRateId path The id of the unit rate to be deleted in SIERA Yes integer

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the specified unit rate id was not found
500 Server error

Upload a new rate

POST /api/v1/unitrates/{unitRateId}/rates/

curl POST https://api.sieraglobal.com/api/v1/unitrates/11/rates \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON  
  {
    "unitRateID": 11,
    "rate": 0.13,
    "fromDate": "2022-01-01T12:00:00.000Z",
    "toDate": "2099-01-01T12:00:00.000Z"          
  }

Response (201)

{
  "rateId": 11
}

Summary: Upload a new rate

HTTP Request

POST /api/v1/unitrates/{unitRateId}/rates

Request body

Attribute Type and description
unitRateID integer
The id of the parent unit rate
rate float
The rate value
fromDate datetime
The start date the rate is valid from
toDate datetime
The date the rate is valid until

Response Body

The response body will a new rate ID relating to the uploaded rate

Attribute Type and description
rateId integer
The SIERA-generated id of the new rate

Responses

Code Description
201 Created
400 Validation failure
401 Unauthorised, the header token expired or is missing
404 Not found, the specified unit rate id was not found
500 Server error

Update a rate

PUT /api/v1/unitrates/{unitRateId}/rates/

curl PUT https://api.sieraglobal.com/api/v1/unitrates/11/rates/3 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON  
  {
    "unitRateID": 11,
    "rateID": 3,
    "rate": 0.27,
    "fromDate": "2022-01-01T12:00:00.000Z",
    "toDate": "2099-01-01T12:00:00.000Z"          
  }

Response (201)

Summary: Update a rate

HTTP Request

PUT /api/v1/unitrates/{unitRateId}/rates/{rateId}

Parameters

Name Located in Description Required Type
unitRateId path The parent id of the unit rate of the rate to be update in SIERA Yes integer
rateId path The id of the rate to be updated in SIERA Yes integer

Request body

Attribute Type and description
unitRateID integer
The id of the parent unit rate
rateID integer
The id of the rate
rate float
The rate value
fromDate datetime
The start date the rate is valid from
toDate datetime
The date the rate is valid until

Responses

Code Description
200 OK
400 Validation failure
401 Unauthorised, the header token expired or is missing
404 Not found, the specified unit rate id was not found
500 Server error

Delete a rate

DELETE /api/v1/unitrates/{unitRateId}/rates/{rateId}

curl -X DELETE https://api.sieraglobal.com/api/v1/unitrates/11/rates/3 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

Summary: Deletes an existing unit rate by ID

HTTP Request

DELETE /api/v1/unitrates/{unitRateId}/rates/{rateId}

Parameters

Name Located in Description Required Type
unitRateId path The parent id of the unit rate of the rate to be deleted in SIERA Yes integer
rateId path The id of the rate to be deleted in SIERA Yes integer

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the specified unit rate id was not found
500 Server error

Validation rules

When uploading new unit rates or updating existing, SIERA will apply the following rules and if they are not met, a response of 400 will be returned with an error message and the field causing the validation failure.

The validation requirements for unit rates are:

  1. When uploading a new unit rate, the unitRateId must be 0 or null.
  2. When updating a unit rate, the unitRateId must be of an existing unit rate in SIERA.

The validation requirements for unit rate rates are:

  1. When uploading a new rate, the rateId must be 0 or null.
  2. When updating a rate, the rateId must be of an existing unit rate in SIERA.
  3. The unitRateId must be provided and be for a valid unit rate in SIERA.

Currencies

The Currencies endpoints allow you to upload and manage currencies to associated with data in SIERA. You can upload new currencies, update currencies or delete them from a given instance in SIERA. Default currencies are provided for Great British Pounds (GBP, £), US Dollars (USD, $) and Euros (EUR, €). These defaults can not be deleted or updated. Currencies currently allow correct labelling of data in SIERA, and (at this time) offer no conversion functionality.

Get all currencies

GET /api/v1/currency

curl https://api.sieraglobal.com/api/v1/currency \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)


[
  {
    "currencyCode": "GBP",
    "currencyName": "Great British Pounds",
    "currencySymbol": "£",
    "isDefault": true
  },
  {
    "currencyCode": "USD",
    "currencyName": "US Dollars",
    "currencySymbol": "$",
    "isDefault": true
  },
  {
    "currencyCode": "EUR",
    "currencyName": "Euros",
    "currencySymbol": "€",
    "isDefault": true
  }
]

Summary: Provides a list of all the currencies in SIERA

HTTP Request

GET /api/v1/currency

Response Body

The response body will be a list of currencies.

Attribute Type and description
currencyCode string
The three-letter currency code of the currency
currencyCode string
The full name of the currency
currencyCode string
The currency symbol of the currency
isDefault bool
A flag indicating if the currency is a default in SIERA

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the currency was not found
500 Server error

Get all currencies

GET /api/v1/currency/{currencyCode}

curl https://api.sieraglobal.com/api/v1/currency/GBP \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

{
  "currencyCode": "GBP",
  "currencyName": "Great British Pounds",
  "currencySymbol": "£",
  "isDefault": true
}

Summary: Provides a currency in SIERA

HTTP Request

GET /api/v1/currency/GBP

Response Body

The response body will be a currency.

Attribute Type and description
currencyCode string
The three-letter currency code of the currency
currencyCode string
The full name of the currency
currencyCode string
The currency symbol of the currency
isDefault bool
A flag indicating if the currency is a default in SIERA

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the currency was not found
500 Server error

Upload a new currency

POST /api/v1/currency

curl POST https://api.sieraglobal.com/api/v1/currency \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON  
  {
    "currencyCode": "JPY",
    "currencyName": "Japanese Yen",
    "currencySymbol": "¥"
  }

Response (201)

{
  "currencyCode": "JPY"
}

Summary: Upload a new currency

HTTP Request

POST /api/v1/currency

Request body

Attribute Type and description
currencyCode string
The three-letter currency code of the currency
currencyCode string
The full name of the currency
currencyCode string
The currency symbol of the currency

Response Body

The response body will a new fund ID relating to the uploaded fund

Attribute Type and description
currencyCode integer
The three-letter currency code of the currency

Responses

Code Description
201 Created
400 Validation failure
401 Unauthorised, the header token expired or is missing
500 Server error

Update a currency

PUT /api/v1/currency/{currencyCode}

curl PUT https://api.sieraglobal.com/api/v1/currency/JPY \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -V "Content-Type: application/json" \
  -d @- <<JSON 
  {
    "currencyCode": "JPY",
    "currencyName": "Japanese Yen Updated",
    "currencySymbol": "¥"
  }

Response (200)

Summary: Updates an existing currency by code

HTTP Request

PUT /api/v1/currency/{currencyCode}

Parameter

Name Located in Description Required Type
currencyCode path The code of the currency to be updated in SIERA Yes integer

Request body

Attribute Type and description
currencyCode string
The three-letter currency code of the currency
currencyCode string
The full name of the currency
currencyCode string
The currency symbol of the currency

Responses

Code Description
201 Created
400 Validation failure
401 Unauthorised, the header token expired or is missing
404 Not found, the currency was not found
500 Server error

Delete a currency

DELETE /api/v1/currency/{currencyCode}

curl -X DELETE https://api.sieraglobal.com/api/v1/currency/JPY \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (200)

Summary: Deletes an existing currency by code

HTTP Request

DELETE /api/v1/currency/{currencyCode}

Parameters

Name Located in Description Required Type
currencyCode path The code of the currency to be updated in SIERA Yes integer

Responses

Code Description
200 OK
401 Unauthorised, the header token expired or is missing
404 Not found, the currency was not found
500 Server error

Validation rules

When uploading new currencies or updating existing, SIERA will apply the following rules and if they are not met, a response of 400 will be returned with an error message and the field causing the validation failure.

The validation requirements for currencies are:

  1. When updating a currency, the currencyCode must be of an existing currency in SIERA.
  2. The currencyCode must not belong to a default currency. Default currencies cannot be updated or deleted.

Enumerations

The SIERA API uses the following enumerations to limit variables to a range of choices.

Action Cost Type

[ None, RevenueServiceCharge, CapitalNonRecoverable, CapitalRecoverable ]
Enumeration Description
None
RevenueServiceCharge Actions whose costs are claimed back through the tenant service charge
CapitalNonRecoverable Actions whose costs are classed as capital non-recoverable through the life of the asset or site
CapitalRecoverable Actions whose costs are classed as capital recoverable through the life of the asset or site

Action Measure Description

[ NotApplicable, SystemsCommissioningOrRetroCommissioning, AutomationSystemUpgradesOrReplacements, ManagementSystemsUpgradesOrReplacements, WallOrRoofInsulation, SmartGridOrSmartBuildingTechnologies, WindowReplacements, InstallationOfHighEfficiencyEquipment, InstallationOfOnSiteRenewableEnergy, OccupierEngagementOrInformationalTechnologies, HighEfficiencyOrDryFixtures, MeteringOfWaterSubsystems, ReuseOfStormWaterOrGreyWater, OnSiteWasteWaterTreatment, CoolingTower, LeakDetectionSystem, DripOrSmartIrrigation, DroughtTolerantOrNativeLandscaping, OngoingWastePerformanceMonitoring, Recycling, WasteManagement, WasteStreamAudit, CompostingLandscapeOrFoodWaste, AMR ]
Enumeration Description
NotApplicable
SystemsCommissioningOrRetroCommissioning The process of ensuring that systems are designed, installed, and functionally tested, and that they are capable of being operated and maintained to perform optimally
AutomationSystemUpgradesOrReplacements Refers to the computer-based centralized system installed in buildings that controls and monitors equipment such as ventilation, airconditioning, heating, lighting, alarms and communications Upgrades and replacements refers to the process of ensuring the building automation system is operating at full capacity, as to achieve optimal management of systems and increase energy efficiency
ManagementSystemsUpgradesOrReplacements Energy management software solutions, which include functionality to forecast and adjust energy demand in a building
WallOrRoofInsulation
SmartGridOrSmartBuildingTechnologies Computer-based control and automation of electricity network systems, to support and manage electricity demand in a sustainable, integrated manner
WindowReplacements Windows replacements of any kind on an asset to reduce overall consumption and thermal energy loss
InstallationOfHighEfficiencyEquipment Specification and purchase of electrical equipment and appliances that minimize the building‘s energy needs This includes, but it is not limited to: energy efficient lighting upgrades/replacements and HVAC system upgrades/replacements
InstallationOfOnSiteRenewableEnergy Renewable energy produced on-site, to meet some or all of the building’s energy requirements
OccupierEngagementOrInformationalTechnologies Communication and information technologies implemented to inform and engage with tenants in regards to their energy use
HighEfficiencyOrDryFixtures Appliances and plumbing equipment that conserve water without compromising performance (also known as “ultra-low-flow” fixtures) / Fixtures that do not require the use of water, such as composting toilet systems and waterless urinals
MeteringOfWaterSubsystems Installing sub-meters to measure the water consumption of applicable subsystems, such as irrigation, indoor plumbing fixtures, domestic hot water, reclaimed water or other process water uses, which supports effective water management and identifying opportunities for additional water savings
ReuseOfStormWaterOrGreyWater Water that collects during precipitation, which can be stored on-site for eventual reuse for non-potable applications Examples can include, but are not limited to: landscape irrigation and/or flush fixtures
OnSiteWasteWaterTreatment Process of water decontamination as a consequence of any anthropogenic, industrial or commercial use, before the water is released again into the environment or is re-used
CoolingTower A cooling tower is a heat rejection device which extracts waste heat to the atmosphere through the cooling of a water stream to a lower temperature Reduction of potable water consumption for cooling towers (or evaporative condenser equipment) can be achieved through effective water management, including conducting a water analysis to measure the concentration of at least five control parameters in order to optimize the cooling tower cycles and/or use of non-potable makeup water for a minimum of 20% of the makeup water
LeakDetectionSystem Systems that detect water leaks Examples can include, but are not limited to: condensate water overflow, chiller water leaks, plumbing line cracks, heating/cooling piping leaks and outside seepage
DripOrSmartIrrigation Drip irrigation systems save water by irrigating, fertilizing and aerating trees, shrubs, plants and bushes directly at the roots Smart irrigation systems save water by adjusting the watering schedule and amount of water used for irrigation based on a variety of factors and inputs, including weather, plant species and soil type
DroughtTolerantOrNativeLandscaping Adapted or indigenous vegetation that has evolved to the geography, hydrology and climate of a region requiring minimal or no supplemental watering beyond natural rainfall
OngoingWastePerformanceMonitoring Track and measure ongoing waste volumes generated on a minimum quarterly basis, by either weight or volume, to help identify diversion and recycling opportunities within the organization Conduct a minimum annual review to evaluate performance
Recycling A program for materials that can be locally recycled and contracted with a recycling service provider Provide appropriately sized recycling collection and storage areas within the entity’s real estate holdings to enable occupants to sort, collect and divert materials from landfill
WasteManagement Hazardous and non-hazardous waste including reuse, recycling, composting, recovery, incineration, landfill, and on-site storage
WasteStreamAudit A formal process used to quantify the type and amount of waste being generated, by weight or volume, to help identify effective waste reduction, separation and recycling opportunities
CompostingLandscapeOrFoodWaste Composting is the controlled decomposition of organic material which produces useful soil amendment products Engage in landscape and/or food waste composting either on-site or by contracting with a composting service provider
AMR Meter readings taken automatically at predefined frequencies by building management systems or smart metering systems

Action Scope

[ CommonAreas, Exterior, Landlord, TenantServices, WholeBuilding ]
Enumeration Description
CommonAreas Actions related to areas shared with other building occupants, including entrance areas, corridors, lifts, staircases,waste storage stores, communal kitchen, breakout facilities, etc
Exterior Actions related to the outdoor areas of an asset or site
Landlord
TenantServices Actions related to lettable floor area, both vacant and let/leased
WholeBuilding Actions related to the entirety of an asset or site

Action Status

[ ActionsUnderReview, AgreedActions, Completed, NotApplicable, Applicable ]
Enumeration Description
ActionsUnderReview Actions which are being considered but not yet accepted
AgreedActions Actions which have been agreed to be implemented or planned for implementation
Completed Actions which have been completed
NotApplicable Actions which have been considered not applicable for an asset or site
Applicable Actions which have been considered applicable for an asset or site and which are awaiting review

Action Utility

[ NotApplicable, DistrictCooling, DistrictHeating, Electricity, Gas, Water, Waste, Oil ]
Enumeration Description
NotApplicable This value is only sent by SIERA to indicate missing data. It may not be chosen for uploads or updates
DistrictCooling Actions relating to reductions in energy from district cooling energy sources
DistrictHeating Actions relating to reductions in energy from district heating energy sources
Electricity Actions relating to reductions in electrical energy usage
Gas Actions relating to reductions in gas energy usage
Water Actions relating to reductions in water usage
Waste Actions relating to reductions in waste
Oil Actions relating to meters providing energy as oil, such as flow meters

Area Covered

[ All, CommonAreas, SharedServices, WholeBuilding, OutdoorExteriorAreaParking, TenantSpace, NotSet ]

Area covered describes where the energy is used with the aim of understanding who is responsible for the energy usage or its reduction

Enumeration Description
All This value is only sent by SIERA to indicate missing data. It may not be chosen for uploads or updates
CommonAreas Energy used by areas shared with other building occupants, including entrance areas, corridors, lifts, staircases,waste storage stores, communal kitchen, breakout facilities, etc
SharedServices Shared Services/Central Plant is a central source providing energy for the whole building, including common areas and shared services for tenants
WholeBuilding Energy used by tenants and base building services in both lettable/leasable and common spaces, but is not available or metered separately
OutdoorExteriorAreaParking Energy used in outdoor areas of an asset or site, including any parking spaces
TenantSpace Lettable floor area (both vacant and let/leased areas) that is or can be occupied by tenants
NotSet This value is only sent by SIERA to indicate missing data. It may not be chosen for uploads or updates

Asset Control

[ Unknown, Landlord, Tenant ]

Asset control indicates who is responsible for the overall energy usage of the asset or site

Enumeration Description
Unknown This value is only sent by SIERA to indicate missing data. It may not be chosen for uploads or updates
Landlord An asset or site which is managed by the landlord
Tenant An asset or site which is managed by the tenant

Asset Status

[ NotSpecified, StandingInvestment, Land, ResidentialDevelopment, Built, NewConstruction, MajorRenovation, MajorRefurbishment ]

Asset status indicates the current state of the asset in relation to its ability to be commercially occupied

Enumeration Description
NotSpecified This value is only sent by SIERA to indicate missing data. It may not be chosen for uploads or updates
StandingInvestment Standing Investment
Land Land
ResidentialDevelopment Residential Development
Built Built
NewConstruction New Construction
MajorRenovation Major Renovation
MajorRefurbishment Major Refurbishment

Consumption Energy Source

[ NationalGridStandard, NationalGridGreen, Renewable, Other ]
Enumeration Description
NationalGridStandard Energy sourced from the national energy grid of a country
NationalGridGreen Energy sourced from a 100% renewable energy contract
Renewable Energy sourced from renewable sources
Other Energy sourced from an unknown source

Consumption Sustainable Procurement

[ RenewableEnergyContract, SelfSupplyRenewables, ExportedConsumption, NoRenewableEnergyContract, OnsiteWaterReuse, OnsiteWaterCapture, StandardWaterSupply ]
Enumeration Description
RenewableEnergyContract A renewable energy contract arrangement with an Energy supplier
SelfSupplyRenewables Renewables generated on-site
ExportedConsumption Consumption generated on-site and exported
NoRenewableEnergyContract No renewable energy contract in place
OnsiteWaterReuse Water is reused on-site
OnsiteWaterCapture Water is captured on site but not re-used
StandardWaterSupply Standard water supply

Consumption Use Of Area

[ OccupiedTenantSpace, VacantTenantSpace, LandlordSpace ]
Enumeration Description
OccupiedTenantSpace Tenant space with tenants in place (occupied)
VacantTenantSpace Tenant space with no tenants in place (void)
LandlordSpace Landlord space

Country

[ NotSpecified, Afghanistan, AlandIslands, Albania, Algeria, AmericanSamoa, Andorra, Angola, Anguilla, Antarctica, AntiguaandBarbuda, Argentina, Armenia, Aruba, Australia, Austria, Azerbaijan, Bahamas, Bahrain, Bangladesh, Barbados, Belarus, Belgium, Belize, Benin, Bermuda, Bhutan, Bolivia, BonaireSintEustatiusandSaba, BosniaHerzegovina, Botswana, BouvetIsland, Brazil, BritishIndianOceanTerritory, BruneiDarussalam, Bulgaria, BurkinaFaso, Burundi, CaboVerde, Cambodia, Cameroon, Canada, CaymanIslands, CentralAfricanRepublic, Chad, Chile, China, ChristmasIsland, CocosKeelingIslands, Colombia, Comoros, Congo, CongoDemocraticRepublic, CookIslands, CostaRica, CotedIvoire, Croatia, Cuba, Curacao, Cyprus, Czechia, Denmark, Djibouti, Dominica, DominicanRepublic, Ecuador, Egypt, ElSalvador, EquatorialGuinea, Eritrea, Estonia, Eswatini, Ethiopia, FalklandIslands, FaroeIslands, Fiji, Finland, France, FrenchGuiana, FrenchPolynesia, FrenchSouthernTerritories, Gabon, Gambia, Georgia, Germany, Ghana, Gibraltar, Greece, Greenland, Grenada, Guadeloupe, Guam, Guatemala, Guernsey, Guinea, GuineaBissau, Guyana, Haiti, HeardIslandandMcDonaldIslands, HolySee, Honduras, HongKong, Hungary, Iceland, India, Indonesia, Iran, Iraq, Ireland, IsleofMan, Israel, Italy, Jamaica, Japan, Jersey, Jordan, Kazakhstan, Kenya, Kiribati, KoreaNorth, KoreaSouth, Kuwait, Kyrgyzstan, Lao, Latvia, Lebanon, Lesotho, Liberia, Libya, Liechtenstein, Lithuania, Luxembourg, Macao, Madagascar, Malawi, Malaysia, Maldives, Mali, Malta, Malvinas, MarshallIslands, Martinique, Mauritania, Mauritius, Mayotte, Mexico, Micronesia, Moldova, Monaco, Mongolia, Montenegro, Montserrat, Morocco, Mozambique, Myanmar, Namibia, Nauru, Nepal, Netherlands, NewCaledonia, NewZealand, Nicaragua, Niger, Nigeria, Niue, NorfolkIsland, NorthMacedonia, NorthernMarianaIslands, Norway, Oman, Pakistan, Palau, Palestine, Panama, PapuaNewGuinea, Paraguay, Peru, Philippines, Pitcairn, Poland, Portugal, PuertoRico, Qatar, Reunion, Romania, RussianFederation, Rwanda, SaintBarthelemy, SaintHelenaAscensionandTristandaCunha, SaintKittsandNevis, SaintLucia, SaintMartin, SaintPierreandMiquelon, SaintVincentandtheGrenadines, Samoa, SanMarino, SaoTomeandPrincipe, SaudiArabia, Senegal, Serbia, Seychelles, SierraLeone, Singapore, SintMaarten, Slovakia, Slovenia, SolomonIslands, Somalia, SouthAfrica, SouthGeorgiaandtheSouthSandwichIslands, SouthSudan, Spain, SriLanka, Sudan, Suriname, SvalbardandJanMayen, Sweden, Switzerland, SyrianArabRepublic, Taiwan, Tajikistan, Tanzania, Thailand, TimorLeste, Togo, Tokelau, Tonga, TrinidadandTobago, Tunisia, Turkey, Turkmenistan, TurksandCaicosIslands, Tuvalu, Uganda, Ukraine, UnitedArabEmirates, UnitedKingdom, UnitedStatesMinorOutlyingIslands, UnitedStates, Uruguay, Uzbekistan, Vanuatu, Venezuela, VietNam, VirginIslandsBritish, VirginIslandsUS, WallisandFutuna, WesternSahara, Yemen, Zambia, Zimbabwe ]

SIERA uses the ISO 3166 list of country names.

Enumeration Description
NotSpecified This value is only sent by SIERA to indicate missing data. It may not be chosen for uploads or updates
Afghanistan Afghanistan
AlandIslands Åland Islands
Albania Albania
Algeria Algeria
AmericanSamoa American Samoa
Andorra Andorra
Angola Angola
Anguilla Anguilla
Antarctica Antarctica
AntiguaandBarbuda Antigua and Barbuda
Argentina Argentina
Armenia Armenia
Aruba Aruba
Australia Australia
Austria Austria
Azerbaijan Azerbaijan
Bahamas Bahamas
Bahrain Bahrain
Bangladesh Bangladesh
Barbados Barbados
Belarus Belarus
Belgium Belgium
Belize Belize
Benin Benin
Bermuda Bermuda
Bhutan Bhutan
Bolivia Bolivia (Plurinational State of)
BonaireSintEustatiusandSaba Bonaire, Sint Eustatius and Saba
BosniaHerzegovina Bosnia and Herzegovina
Botswana Botswana
BouvetIsland Bouvet Island
Brazil Brazil
BritishIndianOceanTerritory British Indian Ocean Territory
BruneiDarussalam Brunei Darussalam
Bulgaria Bulgaria
BurkinaFaso Burkina Faso
Burundi Burundi
CaboVerde Cabo Verde
Cambodia Cambodia
Cameroon Cameroon
Canada Canada
CaymanIslands Cayman Islands
CentralAfricanRepublic Central African Republic
Chad Chad
Chile Chile
China China
ChristmasIsland Christmas Island
CocosKeelingIslands Cocos (Keeling) Islands
Colombia Colombia
Comoros Comoros
Congo Congo
CongoDemocraticRepublic Congo, Democratic Republic of the
CookIslands Cook Islands
CostaRica Costa Rica
CotedIvoire Côte d'Ivoire
Croatia Croatia
Cuba Cuba
Curacao Curaçao
Cyprus Cyprus
Czechia Czechia
Denmark Denmark
Djibouti Djibouti
Dominica Dominica
DominicanRepublic Dominican Republic
Ecuador Ecuador
Egypt Egypt
ElSalvador El Salvador
EquatorialGuinea Equatorial Guinea
Eritrea Eritrea
Estonia Estonia
Eswatini Eswatini
Ethiopia Ethiopia
FalklandIslands Falkland Islands (Malvinas)
FaroeIslands Faroe Islands
Fiji Fiji
Finland Finland
France France
FrenchGuiana French Guiana
FrenchPolynesia French Polynesia
FrenchSouthernTerritories French Southern Territories
Gabon Gabon
Gambia Gambia
Georgia Georgia
Germany Germany
Ghana Ghana
Gibraltar Gibraltar
Greece Greece
Greenland Greenland
Grenada Grenada
Guadeloupe Guadeloupe
Guam Guam
Guatemala Guatemala
Guernsey Guernsey
Guinea Guinea
Guinea-Bissau Guinea-Bissau
Guyana Guyana
Haiti Haiti
HeardIslandandMcDonaldIslands Heard Island and McDonald Islands
HolySee Holy See
Honduras Honduras
HongKong Hong Kong
Hungary Hungary
Iceland Iceland
India India
Indonesia Indonesia
Iran Iran (Islamic Republic of)
Iraq Iraq
Ireland Ireland
IsleofMan Isle of Man
Israel Israel
Italy Italy
Jamaica Jamaica
Japan Japan
Jersey Jersey
Jordan Jordan
Kazakhstan Kazakhstan
Kenya Kenya
Kiribati Kiribati
KoreaNorth Korea (Democratic People's Republic of)
KoreaSouth Korea, Republic of
Kuwait Kuwait
Kyrgyzstan Kyrgyzstan
Lao Lao People's Democratic Republic
Latvia Latvia
Lebanon Lebanon
Lesotho Lesotho
Liberia Liberia
Libya Libya
Liechtenstein Liechtenstein
Lithuania Lithuania
Luxembourg Luxembourg
Macao Macao
Madagascar Madagascar
Malawi Malawi
Malaysia Malaysia
Maldives Maldives
Mali Mali
Malta Malta
Malvinas Malvinas
MarshallIslands Marshall Islands
Martinique Martinique
Mauritania Mauritania
Mauritius Mauritius
Mayotte Mayotte
Mexico Mexico
Micronesia Micronesia (Federated States of)
Moldova Moldova, Republic of
Monaco Monaco
Mongolia Mongolia
Montenegro Montenegro
Montserrat Montserrat
Morocco Morocco
Mozambique Mozambique
Myanmar Myanmar
Namibia Namibia
Nauru Nauru
Nepal Nepal
Netherlands Netherlands
NewCaledonia New Caledonia
NewZealand New Zealand
Nicaragua Nicaragua
Niger Niger
Nigeria Nigeria
Niue Niue
NorfolkIsland Norfolk Island
NorthMacedonia North Macedonia
NorthernMarianaIslands Northern Mariana Islands
Norway Norway
Oman Oman
Pakistan Pakistan
Palau Palau
Palestine Palestine, State of
Panama Panama
PapuaNewGuinea Papua New Guinea
Paraguay Paraguay
Peru Peru
Philippines Philippines
Pitcairn Pitcairn
Poland Poland
Portugal Portugal
PuertoRico Puerto Rico
Qatar Qatar
Reunion Réunion
Romania Romania
RussianFederation Russian Federation
Rwanda Rwanda
SaintBarthelemy Saint Barthélemy
SaintHelenaAscensionandTristandaCunha Saint Helena, Ascension and Tristan da Cunha
SaintKittsandNevis Saint Kitts and Nevis
SaintLucia Saint Lucia
SaintMartin Saint Martin (French part)
SaintPierreandMiquelon Saint Pierre and Miquelon
SaintVincentandtheGrenadines Saint Vincent and the Grenadines
Samoa Samoa
SanMarino San Marino
SaoTomeandPrincipe Sao Tome and Principe
SaudiArabia Saudi Arabia
Senegal Senegal
Serbia Serbia
Seychelles Seychelles
SierraLeone Sierra Leone
Singapore Singapore
SintMaarten Sint Maarten (Dutch part)
Slovakia Slovakia
Slovenia Slovenia
SolomonIslands Solomon Islands
Somalia Somalia
SouthAfrica South Africa
SouthGeorgiaandtheSouthSandwichIslands South Georgia and the South Sandwich Islands
SouthSudan South Sudan
Spain Spain
SriLanka Sri Lanka
Sudan Sudan
Suriname Suriname
SvalbardandJanMayen Svalbard and Jan Mayen
Sweden Sweden
Switzerland Switzerland
SyrianArabRepublic Syrian Arab Republic
Taiwan Taiwan, Province of China
Tajikistan Tajikistan
Tanzania Tanzania, United Republic of
Thailand Thailand
TimorLeste Timor-Leste
Togo Togo
Tokelau Tokelau
Tonga Tonga
TrinidadandTobago Trinidad and Tobago
Tunisia Tunisia
Turkey Turkey
Turkmenistan Turkmenistan
TurksandCaicosIslands Turks and Caicos Islands
Tuvalu Tuvalu
Uganda Uganda
Ukraine Ukraine
UnitedArabEmirates United Arab Emirates
UnitedKingdom United Kingdom
UnitedStatesMinorOutlyingIslands United States Minor Outlying Islands
UnitedStates United States
Uruguay Uruguay
Uzbekistan Uzbekistan
Vanuatu Vanuatu
Venezuela Venezuela (Bolivarian Republic of)
VietNam Viet Nam
VirginIslandsBritish Virgin Islands (British)
VirginIslandsUS Virgin Islands (U.S.)
WallisandFutuna Wallis and Futuna
WesternSahara Western Sahara
Yemen Yemen
Zambia Zambia
Zimbabwe Zimbabwe

Currency

[ BritishPound, USDollar, Euros ]
Enumeration Description
BritishPound Great British Pound (GBP £)
USDollar US Dollar (USD $)
Euros Euros (EUR €)

Factor Type

[ LocationBased, MarketBased ]

Factor Type is used on carbon factors to indicate whether a carbon emissions factors relates to a location based factor or a factor which reflects the carbon emissions of a specific supplier and a contract

Enumeration Description
LocationBased Carbon factors based upon a location such as country
MarketBased Carbon factors based upon a specific energy supplier

Generation Type

[ NotSpecified, NationalGrid, NationalGridGreen, CHP, SelfSupplyRenewables ]
Enumeration Description
NotSpecified This value is only sent by SIERA to indicate missing data. It may not be chosen for uploads or updates
NationalGrid Energy sourced from the national energy grid of a country
NationalGridGreen Energy sourced from a 100% renewable energy contract
CHP Combined heat and power, also known as cogeneration, is the concurrent production of electricity or mechanical power and useful thermal energy (heating and/or cooling) from a single source of energy
SelfSupplyRenewables Energy sourced from on-site renewable consumption

GRESB Sector

[ Other, EducationLibrary, EducationOther, EducationSchool, EducationUniversity, Healthcare, HealthcareCenter, HealthcareOther, HealthcareSeniorHomes, Hotel, IndustrialBusinessParks, IndustrialDistributionWarehouse, IndustrialPark, IndustrialManufacturing, IndustrialOther, LodgingLeisureRecreation, LodgingLeisureRecreationFitnessCenter, LodgingLeisureRecreationIndoorArena, LodgingLeisureRecreationMuseumGallery, LodgingLeisureRecreationOther, LodgingLeisureRecreationPerformingArts, LodgingLeisureRecreationSwimmingCenter, MedicalOffice, MixedUseOfficeIndustrial, MixedUseOfficeResidential, MisedUseOfficeRetail, MixedUseOther, Office, OfficeBusinessPark, OfficeCorporateHighRise, OfficeCorporateLowRise, OfficeCorporateMidRise, OfficeMedical, OfficeOther, OtherParkingIndoors, OtherSelfStorage, ResidentialMultiFamily, ResidentialFamilyHomes, ResidentialMultiFamilyHighRise, ResidentialMultiFamilyLowRise, ResidentialMultiFamilyMidRise, ResidentialOther, ResidentialRetirementLiving, ResidentialStudentHousing, RetailHighStreet, RetailOther, RetailRestaurantsBars, RetailLifestyleCenter, RetailShoppingCenter, RetailCenterStripMall, RetailCenterWarehouse, TechnologyScienceDataCenter, TechnologyScienceLaboratory, TechnologyScienceOther ]
Enumeration Description
Other Other
EducationLibrary Education: Library
EducationOther Education: Other
EducationSchool Education: School
EducationUniversity Education: University
Healthcare Healthcare
HealthcareCenter Healthcare: Healthcare Center
HealthcareOther Healthcare: Other
HealthcareSeniorHomes Healthcare: Senior Homes
Hotel Hotel
IndustrialBusinessParks Industrial: Business Parks
IndustrialDistributionWarehouse Industrial: Distribution Warehouse
IndustrialPark Industrial: Industrial Park
IndustrialManufacturing Industrial: Manufacturing
IndustrialOther Industrial: Other
LodgingLeisureRecreation Lodging, Leisure & Recreation
LodgingLeisureRecreationFitnessCenter Lodging, Leisure & Recreation: Fitness Center
LodgingLeisureRecreationIndoorArena Lodging, Leisure & Recreation: Indoor Arena
LodgingLeisureRecreationMuseumGallery Lodging, Leisure & Recreation: Museum/Gallery
LodgingLeisureRecreationOther Lodging, Leisure & Recreation: Other
LodgingLeisureRecreationPerformingArts Lodging, Leisure & Recreation: Performing Arts
LodgingLeisureRecreationSwimmingCenter Lodging, Leisure & Recreation: Swimming Center
MedicalOffice Medical Office
MixedUseOfficeIndustrial Mixed Use: Office/Industrial
MixedUseOfficeResidential Mixed Use: Office/Residential
MisedUseOfficeRetail Mixed Use: Office/Retail
MixedUseOther Mixed Use: Other
Office Office
OfficeBusinessPark Office: Business Park
OfficeCorporateHighRise Office: Corporate: High-Rise Office
OfficeCorporateLowRise Office: Corporate: Low-Rise Office
OfficeCorporateMidRise Office: Corporate: Mid-Rise Office
OfficeMedical Office: Medical Office
OfficeOther Office: Other
OtherParkingIndoors Other: Parking (Indoors)
OtherSelfStorage Other: Self-Storage
ResidentialMultiFamily Residential, Multi-family
ResidentialFamilyHomes Residential: Family Homes
ResidentialMultiFamilyHighRise Residential: Multi-Family: High-Rise Multi-Family
ResidentialMultiFamilyLowRise Residential: Multi-Family: Low-Rise Multi-Family
ResidentialMultiFamilyMidRise Residential: Multi-Family: Mid-Rise Multi Family
ResidentialOther Residential: Other
ResidentialRetirementLiving Residential: Retirement Living
ResidentialStudentHousing Residential: Student Housing
RetailHighStreet Retail: High Street
RetailOther Retail: Other
RetailRestaurantsBars Retail: Restaurants/Bars
RetailLifestyleCenter Retail: Retail Centers: Lifestyle Center
RetailShoppingCenter Retail: Retail Centers: Shopping Center
RetailCenterStripMall Retail: Retail Centers: Strip Mall
RetailCenterWarehouse Retail: Retail Centers: Warehouse
TechnologyScienceDataCenter Technology/Science: Data Center
TechnologyScienceLaboratory Technology/Science: Laboratory/Life Sciences
TechnologyScienceOther Technology/Science: Other

Measurement Unit

[ M2, FT2 ]
Enumeration Description
M2 Meters squared
FT2 Feet squared

Meter Consumption Type

[ Actual, Estimate ]
Enumeration Description
Actual Consumption that was read from the meter
Estimate Consumption that was estimated based upon other readings

Meter Control

[ Landlord, Tenant ]
Enumeration Description
Landlord Meter consumption purchased by the landlord
Tenant Meter consumption purchased by the tenant

Meter Type

[ Electricity, Water, Gas, Oil, DistrictHeating, DistrictCooling, Carbon, Waste ]
Enumeration Description
Electricity Meters providing electrical energy
Water Meters providing water
Gas Meters providing gas energy
Oil Meters providing energy as oil, such as flow meters
DistrictHeating Meters providing heating energy from a centralised source
DistrictCooling Meters providing cooling from a centralised source
Carbon
Waste

EPC Scope

[ NotSpecified, WholeBuilding, Unit ]
Enumeration Description
NotSpecified Not Specified
WholeBuilding Whole Building
Unit Unit

Meter Control

[ Landlord, Tenant ]

Meter control indicates who is responsible for the purchasing of the energy or water of the meter

Enumeration Description
Landlord A meter whose energy or water is purchased by the landlord
Tenant A meter whose energy or water is purchased by the tenant

Sector

[ Retail, Office, Industrial, Residential, Hotel, LodgingLeisureRecreation, Education, TechnologyScience, Healthcare, MixedUseOffice, Other ]

The Sector enumeration defines the different property sectors used by SIERA

Enumeration Description
Retail Any retail site or asset
Office Any office site or asset
Industrial Any industrial site or asset
Residential Any residential site or asset
Hotel Any hotel, motel, youth hostel, lodging or resort
LodgingLeisureRecreation Sites or assets related to leisure and recreation such as (but not limited to) stadiums, fitness centers, museums or theatres
Education Any school, college, university or library.
TechnologyScience Sites or assets related to technology or science such as data centres, laboratories or research facilities
Healthcare Sites or assets related to healthcare, medecine or residential care
MixedUseOffice Offices containing a mix of one or more other sectors, such as Offices with Retail
Other Any site or asset which does not fit another sector

Waste Destination

[ AnaerobicDigestion, Incinerator, Landfill, MRFIncinerator, MRFLandfill, MRFUnknown, Recycled, Compost, Reuse ]

The waste destination indicates the final destination of waste and the method by which its reycled or reused if possible.

Enumeration Description
AnaerobicDigestion Anaerobic digestion is a destination where waste is broken down by microorganisms in the absence of oxygen
Incinerator Incinerated waste which has no recyclable, or reusable component
Landfill Waste which goes to a landfill
MRFIncinerator A materials recovery facility including a incinerator for the waste which cannot be recovered
MRFLandfill A materials recovery facility including a landfill for the waste which cannot be recovered
MRFUnknown A materials recovery facility with an unknown destination for the waste which cannot be recovered
Recycled Directly recycled waste
Compost Directly composted waste for later reuse
Reuse Directly reusable waste

Waste Stream

[ GeneralWaste, MixedRecyclables, Plastics, PaperandCardboard, Glass, MixedMetals, Food, WEEE, FluorescentTubes, InterceptorWaste, PrinterToners ]

The waste stream of a waste destination is a categorisation of the waste being disposed of

Enumeration Description
MixedRecyclables Mixed recyclables disposed of together such as plastic and paper waste
Plastics Any plastic waste
PaperandCardboard Any paper or carboard waste
Glass Glass waste
MixedMetals Metal waste of any kind disposed of alone or aggregated
Food Food waste or any other byproduct
WEEE Waste electrical and electronic equipment
FluorescentTubes Flourescent lighting tubes
InterceptorWaste Materials used as a waste interceptor
PrinterToners Printer toners
GeneralWaste Waste that does not fit into any other stream type

API Version History

All updates to our API will be documented in this section. If a backwards-incompatible update is released, all API users will be notified in advance and be given ample time to upgrade.

Version 1.02 – Apr 27, 2023
  • Added the expected date format (dd/mm/yy) for date values.
Version 1.02 – Sep 29, 2022
  • AreaCovered enum 'all' value description added.
  • Added note for consumption records.
  • Fixed full stop inconsistencies within changelog.
Version 1.01 – Aug 31, 2022
  • Corrected the use of the enum Country in Asset endpoint examples from 'United Kingdom' to the correct 'UnitedKingdom'.
Version 1 – Aug 23, 2022
  • Validation rules added to all endpoints.
  • PropertyId renamed to AssetId on all endpoints.
  • Additional properties added to EPC endpoints.
  • Additional properties added to Assets endpoints.
  • Assets.ControlledBy changed to AssetControl enumeration.
  • POST and PUT endpoints have been adjusted to follow a consistent Rest API URL pattern.
  • All POST endpoints now return the ID of the newly created entity.
  • Waste Destinations endpoints renamed from /wastedestination to /wastedestinations.
  • Waste Records endpoints renamed from /wasterecord to /wasterecords.
  • Individual GET endpoints added to all endpoints using all-entity retrieval.
  • All asset level entity GET endpoints moved to the Asset endpoints.
  • CarbonFactor.TariffType renamed to FactorType.
  • ConsumptionUseOfArea and ConsumptionSustainableProcurement added to Consumption endpoints.
  • Some unselectable enum values which are used to accomodate missing data have been marked in the Enumerations section.
Version 0.1 – Dec 22, 2021
  • Initial upload of draft content.
  • Warning added relating to draft nature and forthcoming authentication changes.
shell