Skip to main content
The Facilities API allows you to create, retrieve, update, and delete facilities within your organization. Each facility represents a physical site (office, warehouse, factory, etc.) and tracks energy consumption and CO2e emissions.
New API: This endpoint is part of the new API architecture with improved design and maintainability.

Key Features

  • Site Management: Create and manage facilities in your organization
  • Consumption Categories: Configure which consumption types apply to each facility (heat, electricity, water, recharge)
  • CO2e Tracking: Automatic emissions calculation based on facility consumption data
  • Regional Support: ISO country codes for region-specific emission factors
  • CUPS Integration: Associate electricity supply point codes (CUPS) with facilities
  • Pagination Support: Efficiently retrieve large lists of facilities

Authentication

All endpoints require authentication using an API key included in the x-api-key header.

Headers

All requests must include:
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef

Available Endpoints

List Facilities

Retrieve all facilities with filtering and pagination

Get Facility

Retrieve a single facility by ID

Create Facilities (v2)

Create up to 1,000 facilities in one request

Delete Facilities (v2)

Delete up to 1,000 facilities with their data

Create Facility (v1, deprecated)

Add a new facility to your organization

Update Facility

Modify facility details

Delete Facility (v1, deprecated)

Remove a facility from your organization

Facility Attributes

Core Information

  • name (string, required): Name of the facility (e.g., “Madrid Office”, “Barcelona Warehouse”)
  • type (string): Ownership of the site, owned or rented. Required by POST /v1/facilities; POST /v2/facilities takes no type and creates every facility as owned.
  • country (string, required): ISO 3166-1 country code (e.g., “ES”, “FR”, “DE”)
  • address (string, optional): Physical address of the facility

Configuration

  • categories (array[string], optional): Consumption categories enabled for this facility (e.g., ["heat", "electricity", "water", "recharge"])
  • cups_list (array[string], optional): List of CUPS (electricity supply point) codes associated with the facility
  • logistic_factor (float, optional): Logistic factor for scope 2 calculation in logistics reports (0 to 1, default 0.8)

Emission Data

  • co2e (float, read-only): Total CO2 equivalent emissions in kg CO2e
  • co2e_biomass (float, read-only): CO2e from biomass sources
  • status (string): Current status: active or archived

Response Format

Facility Object

Error Handling

Common HTTP Status Codes

Use Cases

Find the Facility IDs to Send Consumptions To

Invoices, wastes and the other consumptions name their facility by id (on the v2 routes, the facility_id of each facility_percentages entry). Map your own site names to those ids once:

Authentication Guide

Learn how to get your API key and authenticate requests

Invoices API

Manage energy invoices linked to facilities

MCP Tools

Query facility data from AI assistants via MCP