Documentation
API Documentation
Utility Bills

Utility Bills

Endpoints

All Buildings

List:
/api/v1/buildings/{building ID}/utility_bills/
Detail:
/api/v1/buildings/{building ID}/utility_bills/{utility bill ID}

Buildings within Portfolio

List:
/api/v1/portfolios/{portfolio ID}/buildings/{building ID}/utility_bills/
Detail:
/api/v1/portfolios/{portfolio ID}/buildings/{building ID}/utility_bills/{utility bill ID}

So you've created a new building via the API and you want to run building analytics. Before you can, you need to attach a sufficient number (at least 12 consecutive months) of utility bills to your building to give the BETTER application enough information to fit change-point model(s) and generate building analytics data.

You can use the utility bill API endpoint to add a series of utility bills to your building.

IMPORTANT NOTE:
If you create, modify or delete a utility bill for a building, any existing building analytics for that building will be set to INVALIDATED. Furthermore, any portfolio analytics that involve the affected building analytics will also be set to INVALIDATED.

Creating a Utility Bill

You can create a utility bill by sending a POST request to a particular building's utility bills endpoint. You must send in five pieces of information for BETTER to create a utility bill for a building. That information -- in JSON form in the body of the POST request -- should look like this: 


{
    "fuel_type": "ELECTRIC_GRID",
    "bill_start_date": "2020-01-01",
    "bill_end_date": "2020-01-31",
    "consumption": 59961,
    "unit": "KWH"
}

The fuel_type must be one of a limited set of values describing the fuel type reported in the utility bill...see the FuelTypeEnum definitions in the API Schema docs.

The bill_start_date and bill_end_date properties must be dates in the form YYYY-MM-DD.

The consumption is a number describing consumption reported on the utility bill.

The unit property must be one of a limited set of values describing the consumption units...see the UnitType definitions in the API Schema docs.

Listing Utility Bills

You can get a complete list of utility bills for a particular building by sending a GET request to the /api/v1/buildings/{building ID}/utility_bills/ endpoint. The returned information will include the properties for each utility bill assigned to the building.

Retrieve a Utility Bill

You can retrieve a complete description of a utility bill for a building by sending a GET request to the endpoint for that utility bill, using the building's ID and the utility bill's ID.

For example, to retrieve the details of a utility bill with ID of 27, for a building with ID 18, would require sending a GET request to /api/v1/buildings/18/utility_bills/27/

Editing a Utility Bill

You can edit a utility bill by sending a PATCH request to the utility bill endpoint for a particular building, using the building's ID and the utility bill's ID, in the same manner as the 'retrieve' process described above (e.g /buildings/18/utility_bills/27/).

You could update the utility bill's consumption value with a PATCH request like: 


{
    "consumption": 5000
}

Deleting a Utility Bill

You can delete a utility bill by sending a DELETE request to that particular utility bill, using the building's ID and the utility bill's ID (in the same way as retrieve or update, e.g. /api/v1/buildings/18/utility_bills/27/).