Changelog

Here are the latest updates and improvements to the Alasco Public API.

2026-08-26

Changes: Update an invoice payment [FinCon, CapEx]

  • Added: PATCH /invoices/{invoice_id}/payments/{payment_id}/ endpoint to correct a payment that is already registered against an invoice. Accepts payment_amount_gross, payment_date and payment_comment, and responds with the updated payment. Take the payment_id from GET /invoices/{id}/payments/.
  • Note: Only the attributes you send are changed; anything you leave out keeps its current value. Send payment_comment as null to remove the comment.
  • Note: As when registering a payment, the gross amount is split into a net amount and tax using the invoice's approved amounts. The response returns the stored net and tax.
  • Note: The invoice's invoice_process_state is never changed by this endpoint, not even when the payments no longer add up to the approved amount. Use POST /invoices/{id}/register-payment/ to settle an invoice.
  • Note: Payments of invoices in any status can be updated, including invoices that are already PAID. This is unrelated to POST /invoices/{id}/update-paid-invoice/, which remains limited to invoices created through POST /invoices/add-paid-invoice/.

2026-08-25

Changes: Partial payments on register-payment [FinCon, CapEx]

  • Added: An optional is_final_payment attribute on POST /invoices/{id}/register-payment/. It defaults to true, so existing requests are unaffected: the payment settles the invoice, which moves to PAID, and an invoice that is already PAID is still rejected.
  • Added: Pass false to record a partial payment. The invoice keeps its current status, further payments can be registered against it, and an invoice that is already PAID is accepted. Invoices still waiting on an approval step are rejected either way.
  • Note: Partial payments are neither capped at the approved amount nor deduplicated, so a repeated request records a further payment.
  • Note: While an invoice is settled by partial payments its own payment fields keep summarising them — payment_amount_gross is the running total, payment_date and payment_comment come from the most recent payment — while invoice_process_state stays APPROVED. Use GET /invoices/{id}/payments/ for the per-payment breakdown.

2026-08-19

Changes: Invoice payments endpoint [FinCon, CapEx]

  • Added: GET /invoices/{id}/payments/ endpoint listing the individual payments registered against an invoice, oldest first. Each payment carries payment_date, paid_amount (net and tax), payment_comment and date_created, and relates back to its invoice.
  • Added: A payments relationship link on the invoice resource, alongside documents and tags.
  • Note: An invoice can be settled by several partial payments. The invoice's own payment fields summarise them: payment_amount_gross is the total paid, while payment_date, payment_comment and payment_created describe the most recent payment. Use the new endpoint for the per-payment breakdown. These fields are unchanged.

2026-06-22

Changes: Documentation improvements

  • Added: llms.txt entry point for LLMs and AI agents, summarising authentication and conventions and linking the machine-readable OpenAPI specifications for all products.
  • Added: Domain model overviews for all products, describing how the main objects relate to help make sense of the endpoint structure.
  • Added: Complete English and German field descriptions using in-app labels for all products.

2026-06-10

Changes: Contract unit create and update endpoints [FinCon]

  • Added: POST /contract_units/ endpoint to create a contract unit in a project. Accepts name, description, lifecycle state, and optional initial_budget (non-cost-element projects only). Responds with HTTP 201.
  • Added: PATCH /contract_units/{id}/ endpoint to update a contract unit's name, description, state, and initial_budget. Does not support changing the project.
  • Note: CONTINGENCY and FINANCING states cannot be set or changed via the API.

2026-05-15

Changes: Launch of Alasco MCP server v1 (beta)

  • Added: Alasco MCP server at https://mcp.alasco.de, exposing Public API product capabilities as Model Context Protocol tools for compatible AI clients. Authentication uses Auth0 OAuth 2.0.
  • Added: Get started with Alasco MCP Server documentation on the developer portal.

2026-05-05

Changes: Tenant upsert endpoint [ESG]

  • Added: POST /tenants/ endpoint to create or update a tenant for the building given by external_building_id in the request body. If a tenant with the same external_id already exists, it is updated (including association to the target building); otherwise a new tenant is created. Responds with HTTP 201 when created and HTTP 200 when updated.

2026-03-18

Changes: New building fields and endpoints [ESG]

  • Added: external_asset_id, gross_external_area, and gross_internal_area fields to the GET /buildings/ response.
  • Added: GET /buildings/{building_uuid}/analysis-result/ endpoint to retrieve the latest CO2 analysis result for a building. Returns null data if no analysis has been performed.
  • Added: GET /buildings/{building_uuid}/custom-data/ endpoint to retrieve all custom data groups and field values associated with a building.

2026-02-27

Changes: New endpoints for file metadata by external ID [ESG]

  • Added: /files/metadata/ endpoint (GET) to retrieve file metadata by external ID.
  • Added: /files/metadata/ endpoint (PATCH) to update file metadata (name, document_type, building_external_id) for API-sourced documents.
  • Added: /files/ endpoint (DELETE) to delete a file and its metadata for API-sourced documents.

2026-02-23

Changes: New endpoint for setting a file's external ID [ESG]

  • Added: /files/{file_id}/external-id/ endpoint (POST) to set the external ID for a file. Has no effect if the file already has an external ID.

2026-02-19

Changes: New endpoint for downloading documents [ESG]

  • Added: /files/{file_id}/ endpoint (GET) to download a document by its UUID.

2026-02-17

Changes: New endpoint for uploading documents [ESG]

  • Added: /files/ endpoint (POST) to upload documents.

2026-02-13

Changes: New endpoint for retrieving document events [ESG]

  • Added: /file-events/ endpoint (GET) to retrieve document events.

2026-01-22

Changes: New endpoints for retrieving raw audit and user audit events [ESG]

  • Added: /raw-audit-log/ endpoint (GET) to retrieve raw audit events.
  • Added: /raw-user-audit-log/ endpoint (GET) to retrieve raw user-related audit events.

2025-10-15

Changes: Added additional fields to contracting entity [FinCon, CapEx]

  • Added: various fields for legal and tax information to the /contracting_entities/ endpoints (GET, POST and PATCH).

2025-10-10

Changes: New endpoint for retrieving budget shifts [FinCon]

  • Added: /budget_shifts/ endpoint to retrieve budget shifts of contract units.

2025-08-22

Changes: Add include parameter to buildings endpoint [ESG]

  • Added: include parameter to /buildings/ endpoint to retrieve energy certificates and building certificates.

2025-07-22

Changes: Cooling meters support in utilities API [ESG]

  • Added: COOLING enum to category attribute of utility meters (GET, POST, PATCH).
  • Added: cooling_system attribute to utility meters (GET, POST, PATCH).

2025-07-01

Changes: download annotated files for invoices and change orders [FinCon] [CapEx], upload invoices to an asset [CapEx]

  • Added: download-annotated endpoints for invoices and change orders. If there is no annotated file for the document, the original is downloaded instead.
  • Added: submit-invoice endpoint to upload invoices for a specified asset in state NEW and start the corresponding workflow.

2025-06-16

Changes: Bulk meter reading upsert endpoint [ESG]

  • Added: New endpoint to bulk upsert meter readings (POST).

2025-06-06

Changes: New filters for contractors endpoint

  • Added: Option to filter for contractors in a given project (FinCon only).
  • Added: Option to filter for contractors in a given asset (CapEx only).

2025-06-03

Changes: Added endpoint to update utility meters and improved error handling with codes in error response [ESG]

  • Added: New endpoint to update utility meters including error codes (PATCH).
  • Improved: Error codes for utility meter create endpoint (POST, communicated in code property of error response).

2025-05-15

Changes: introduce create contract endpoint, and improve update contract capabilities [CapEx, FinCon]

  • Added: new endpoint to create contracts
    • It is possible to provide base data, for instance name, description, and contract volume.
    • Contracts are always created in status DRAFT.
    • It is not possible to create recurring or multi-part contracts.
  • Improved: endpoint to update contracts
    • It is now possible to update the status, and relationships to contractor, contracting entity and measure (CapEx) or contract unit (FinCon).

2025-05-06

Changes: Support for tracking fine-grained data source information with Utility Data Batch Info object [ESG]

  • Added: New endpoint to Utility Data Batch Info objects for fine-grained data source & batch tracking for utility endpoints (POST).
  • Added: Ability to specify data source via batch_info_uuid field (optional) when creating meters, meter readings and consumption intervals.

2025-04-16

Changes: Bulk consumption interval API endpoint with error codes [ESG]

  • Added: Bulk consumption interval public API endpoint to create/edit consumption intervals (POST).
  • Added: Error codes for consumption interval create endpoint (communicated in code property of error response).

2025-04-03

Changes: some changes and new endpoint for custom fields [FinCon]

  • Improved: custom field definition endpoint
    • Now returns and additional unit attribute that can further specify decimal fields.
    • Instances with field type MONEY will now be returned as field type DECIMAL with unit CURRENCY.
  • Added: new endpoint to get custom field values for a project

2025-03-14

Changes: new endpoints for invoices, contracts and contractors [CapEx]

  • Added: endpoints to submit and update new invoices, and to register payment for an invoice
  • Added: endpoint to update contracts (basic data)
  • Added: endpoints to get and create contract documents
  • Added: endpoint to create and update contractors

2025-02-12

Changes: new endpoint to post a utility meter [ESG]

  • Added: new /utility-meters/ endpoint to create utility meter.

2025-01-24

Changes: new endpoint to post utility meter consumption [ESG]

  • Added: new /consumption-intervals/ endpoint to allow creating consumption for a utility meter.

2025-01-21

Changes: add more data to meters and buildings endpoints [ESG]

  • Improved: meters and buildings endpoints by adding external_id attribute.

2024-12-16

Changes: public release of version 1 of Public API for ESG [ESG]

  • Added: endpoints to retrieve buildings and meters, and two options to post meter readings.

2024-12-11

Changes: add cost element reporting capabilities to Reporting API [FinCon]

  • Added: endpoints for cost reporting structured by cost elements on account, contract unit and contract levels. Important: using a project filter is required for these endpoints.

2024-09-30

Changes: launch new public API gateway and developer portal [FinCon] [ESG] [CapEx]

  • Added: landing page and sections for the different product APIs to developer.alasco.de
  • Added: support for files larger than 10MB for all file endpoints.

2024-09-11

Changes: add more data to cost reporting endpoints [FinCon]

  • Improved: cost reporting endpoints by adding progress_reported, contractual_discounts, and contractual_cost_allocations attributes.

2024-08-30

Changes: introduce Paid Invoices that skip the workflow [FinCon] [CapEx]

  • Added: endpoints to create, update, and delete invoices directly in status PAID
    • Such invoices do not trigger a workflow and can be changed and deleted.
    • They count as paid invoices for all relevant features. It is possible to add additional documents to them. A coversheet is generated when creating the paid invoice.
    • Only invoices of type SINGLE are supported.
  • Added: financing data to the cost reporting endpoints.

2024-08-02

Changes: add more data to Contract endpoints [FinCon] [CapEx]

  • Improved: Contract GET endpoints by adding contract_type attribute.

2024-07-25

Changes: add endpoint to read contract terms of a contract [FinCon] [CapEx]

  • Added: an endpoint to the contractor resource to get the contract terms.

2024-05-24

Changes: support Tax Waiver for Contractor endpoints, get more details from Contracts and Change Orders [FinCon] [CapEx]

  • Added: support for setting a security number to the Contractor endpoints.
    • Setting it creates a related tax waiver object if none exists, and sets the tax_waiver_required attribute (app only) to TRUE. This requires the tax_authority and tax_id attributes to be set first.
    • Setting it empty sets the tax_waiver_required attribute (app only) to FALSE.
  • Added: new endpoints to upload and download tax waiver documents.
  • Improved: contract and change order endpoints by adding financial data.