logo
API docs by Redocly

ESG API (1.0)

Download OpenAPI specification:

Introduction

You can use the Alasco API to integrate your application with Alasco. The Alasco API is REST-based and follows JSON:API principles for structuring responses.

Starting from version 1.0, the API is stable. We are continuously improving our API and new endpoints will be added. Any updates or changes within this major version will be backward-compatible and can be found in this documentation.

For getting acccess to the Alasco API, please reach out to us: kontakt@alasco.de.

The base URL for all endpoints is: https://api.alasco.de/esg/v1

The Alasco API supports compressed payloads. If you would like to make use of this, you have to specify the Accept-Encoding header. Supported encodings are gzip and br.

Domain model

Objects relate as follows (each → is a navigable sub-resource):

  • Building → Utility Meters, plus custom data and analysis results.
  • Utility Meter → Meter Readings, which roll up into Consumption (annual and interval).
  • Tenants are linked to consumption via tenant-consumption links.
  • Files carry metadata and external IDs; file events and audit logs track changes.

The Alasco API uses pagination. The page size is 100, additional pages can be accessed using a next link.

Annual Consumption

Annual Consumption is the system-computed consumption per meter and calendar year, including emission factors and tenant allocations. The figures are derived from readings rather than written directly; you can read them and update the market-based emission factor.

Get Annual Consumption

Authorizations:
API KeyAPI Token
query Parameters
external_building_id
required
string (External Building Id)

External ID of the building.

year
required
integer (Year)

The calendar year to retrieve consumption for.

External Meter Id (string) or External Meter Id (null) (External Meter Id)

Optional. Filter results to the consumption entry for a specific meter, identified by its external ID. Filtering by null is not supported- omit this parameter to get all entries.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Update Annual Consumption

Authorizations:
API KeyAPI Token
path Parameters
annual_consumption_id
required
string <uuid> (Annual Consumption Id)
Request Body schema: application/json
required
required
object (AnnualConsumptionPatchPayloadData)

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Audit Log

The Audit Log is a read-only account-level trail of changes. A raw audit feed reports table-level inserts, updates and deletes, and a user audit feed reports user- and API-triggered changes; both are queried over a bounded time range (up to 24 hours).

Get Events

Authorizations:
API KeyAPI Token
query Parameters
start
required
string <date-time> (Start)
end
required
string <date-time> (End)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Get User Events

Authorizations:
API KeyAPI Token
query Parameters
start
required
string <date-time> (Start)
end
required
string <date-time> (End)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Buildings

A Building is a property in your Alasco asset register and the anchor for ESG data - its Utility Meters, Tenants and Documents all attach to it. Buildings are read-only here, identified by a UUID (and an external_building_id used when creating related records); each also exposes its custom data and latest CO2 analysis result.

Get Analysis Result

Authorizations:
API KeyAPI Token
path Parameters
building_uuid
required
string <uuid> (Building Uuid)

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Get Buildings

Authorizations:
API KeyAPI Token
query Parameters
include
string (Include)
Default: ""
Examples: include=energy_certificates,building_certificates 
    Optional, comma-separated list of entities to include in the building attributes.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Get Custom Data

Authorizations:
API KeyAPI Token
path Parameters
building_uuid
required
string <uuid> (Building Uuid)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Consumption Intervals

A Consumption Interval is a consumption total for a period (start to end date) for a meter. Intervals are created individually or in bulk - all-or-nothing (/bulk/) or per-item (/bulk-partial/) - with upsert semantics.

Bulk Create Consumption Intervals

Authorizations:
API KeyAPI Token
Request Body schema: application/json
required
required
Array of objects (Data)

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Bulk Create Consumption Intervals Partial

Authorizations:
API KeyAPI Token
Request Body schema: application/json
required
required
Array of objects (Data)

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Create Consumption Interval

Authorizations:
API KeyAPI Token
Request Body schema: application/json
required
required
object (ConsumptionIntervalPayloadData)

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Documents

A Document is a file attached to one or more Buildings (certificates, leases and similar). Documents can be uploaded, downloaded, given an external id, have their metadata read and updated, and be deleted; a file-events feed reports document changes over a time range. Metadata edits and deletion apply to API-sourced documents.

Create File External Id

Authorizations:
API KeyAPI Token
path Parameters
file_id
required
string <uuid> (File Id)
Request Body schema: application/json
required
required
object (ExternalIdRequestData)

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Delete File

Authorizations:
API KeyAPI Token
query Parameters
external_id
required
string (External Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get File

Authorizations:
API KeyAPI Token
path Parameters
file_id
required
string <uuid> (File Id)

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Get File Events

Authorizations:
API KeyAPI Token
query Parameters
start_time
required
string <date-time> (Start Time)
end_time
required
string <date-time> (End Time)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Get File Metadata

Authorizations:
API KeyAPI Token
query Parameters
external_id
required
string (External Id)

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Patch File Metadata

Authorizations:
API KeyAPI Token
query Parameters
external_id
required
string (External Id)
Request Body schema: application/json
required
required
object (FileMetadataUpdateData)

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Upload File

Authorizations:
API KeyAPI Token
Request Body schema: multipart/form-data
required
file
required
string <application/octet-stream> (File)

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Create Tenant Consumption Link

Authorizations:
API KeyAPI Token
Request Body schema: application/json
required
required
object (TenantConsumptionLinkCreatePayloadData)

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Delete Tenant Consumption Link

Authorizations:
API KeyAPI Token
query Parameters
external_tenant_id
required
string (External Tenant Id)

External ID of the tenant.

annual_consumption_id
required
string <uuid> (Annual Consumption Id)

UUID of the annual consumption entry.

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Tenants

A Tenant is an occupant of a Building, identified by your external_id and linked to a building by external_building_id. Tenants are upserted through the API (created or updated by external id) and can carry attachments.

Create Tenant Attachment

Authorizations:
API KeyAPI Token
path Parameters
external_tenant_id
required
string (External Tenant Id)
Request Body schema: application/json
required
required
object (TenantAttachmentCreatePayloadData)

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Upsert Tenant

Authorizations:
API KeyAPI Token
Request Body schema: application/json
required
required
object (TenantCreatePayloadData)

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Utility Data Batch Info

Utility Data Batch Info records the source and label of a batch of imported utility data. Create one and reference it (via batch_info_uuid) when writing meters, readings or consumption intervals to group them under an import; it cannot be changed once created.

Add Utility Data Batch Info

Authorizations:
API KeyAPI Token
Request Body schema: application/json
required
required
object (alasco__public_api__esg__web__v1__schemas__utilities__utility_batch_info__UtilityDataBatchInfoWrite)

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Utility Meter Readings

A Utility Meter Reading is a timestamped meter value. Readings are written individually or in bulk (upsert), keyed by the meter's external id, and feed the derived consumption figures.

Bulk Create Utility Meter Readings

Authorizations:
API KeyAPI Token
Request Body schema: application/json
required
required
Array of objects (Data)

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Create Utility Meter Reading

Authorizations:
API KeyAPI Token
path Parameters
building_uuid
required
string <uuid> (Building Uuid)
meter_uuid
required
string <uuid> (Meter Uuid)
Request Body schema: application/json
required
required
object (UtilityMeterReadingPayloadData)

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Create Utility Meter Reading With External Id

Authorizations:
API KeyAPI Token
Request Body schema: application/json
required
required
object (UtilityMeterReadingWithExternalIdPayloadData)

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Utility Meters

A Utility Meter measures consumption (electricity, gas, water, heating or cooling) for a Building. Meters are created and updated through the API, identified by your external_id, and own their Readings and consumption data.

Add Utility Meter

Authorizations:
API KeyAPI Token
Request Body schema: application/json
required
required
object (UtilityMeterCreatePayloadData)

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Add Utility Meter Import

Authorizations:
API KeyAPI Token
Request Body schema: application/json
required
required
object (UtilityMeterImportCreatePayloadData)

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Bulk Add Utility Meter Import Partial

Authorizations:
API KeyAPI Token
Request Body schema: application/json
required
required
Array of objects (Data)

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Get Utility Meters

Authorizations:
API KeyAPI Token
path Parameters
building_uuid
required
string <uuid> (Building Uuid)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}

Update Utility Meter

Authorizations:
API KeyAPI Token
path Parameters
meter_external_id
required
string (Meter External Id)
Request Body schema: application/json
required
required
object (UtilityMeterPatchPayloadData)

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "included": [
    ],
  • "links": {
    }
}