Create Facility

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '<string>',
    type: '<string>',
    country: '<string>',
    address: '<string>',
    logistic_factor: 123,
    categories: {},
    cups_list: {}
  })
};

fetch('https://api.dcycle.io/v1/facilities', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/facilities"

payload = {
    "name": "<string>",
    "type": "<string>",
    "country": "<string>",
    "address": "<string>",
    "logistic_factor": 123,
    "categories": {},
    "cups_list": {}
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/facilities \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "name": "<string>",
  "type": "<string>",
  "country": "<string>",
  "address": "<string>",
  "logistic_factor": 123,
  "categories": {},
  "cups_list": {}
}
'

{
  "id": "<string>",
  "name": "<string>",
  "address": {},
  "country": "<string>",
  "type": "<string>",
  "categories": {},
  "cups_list": {},
  "status": "<string>",
  "co2e": {},
  "co2e_biomass": {},
  "logistic_factor": {},
  "facility_purpose_type": {},
  "created_at": {},
  "updated_at": {},
  "invoices_in_review_count": 123,
  "categories_without_data": 123,
  "water_type": {},
  "methane_burned": {},
  "wwt_line": {
    "id": "<string>",
    "line_code": "<string>"
  },
  "sludge_line": {
    "id": "<string>",
    "line_code": "<string>"
  },
  "wwd_line": {
    "id": "<string>",
    "line_code": "<string>"
  }
}

POST

facilities

Create Facility

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '<string>',
    type: '<string>',
    country: '<string>',
    address: '<string>',
    logistic_factor: 123,
    categories: {},
    cups_list: {}
  })
};

fetch('https://api.dcycle.io/v1/facilities', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/facilities"

payload = {
    "name": "<string>",
    "type": "<string>",
    "country": "<string>",
    "address": "<string>",
    "logistic_factor": 123,
    "categories": {},
    "cups_list": {}
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/facilities \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "name": "<string>",
  "type": "<string>",
  "country": "<string>",
  "address": "<string>",
  "logistic_factor": 123,
  "categories": {},
  "cups_list": {}
}
'

{
  "id": "<string>",
  "name": "<string>",
  "address": {},
  "country": "<string>",
  "type": "<string>",
  "categories": {},
  "cups_list": {},
  "status": "<string>",
  "co2e": {},
  "co2e_biomass": {},
  "logistic_factor": {},
  "facility_purpose_type": {},
  "created_at": {},
  "updated_at": {},
  "invoices_in_review_count": 123,
  "categories_without_data": 123,
  "water_type": {},
  "methane_burned": {},
  "wwt_line": {
    "id": "<string>",
    "line_code": "<string>"
  },
  "sludge_line": {
    "id": "<string>",
    "line_code": "<string>"
  },
  "wwd_line": {
    "id": "<string>",
    "line_code": "<string>"
  }
}

Create Facility

Create a new facility in your organization. The system will track energy consumption and calculate CO2e emissions for the facility.

Address or Country Required: You must provide either an address (from which the country is geocoded) or a country code. If both are provided, the geocoded country from the address takes precedence.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Body Parameters

string

required

Name of the facilityExample: "Madrid Office"

string

required

Type of facilityExample: "office"

string

ISO 3166-1 country code. Required if address is not provided.Examples: "ES", "FR", "DE", "US"

string

Physical address of the facility. If provided, the country is automatically geocoded from the address.Example: "Calle Gran Vía 1, Madrid, Spain"

number

default:"0.8"

Logistic factor for scope 2 calculation in logistics reports (0 to 1)Example: 0.8

array[string]

Consumption categories enabled for this facilityAvailable values: heat, electricity, water, rechargeExample: ["heat", "electricity", "water"]

array[string]

List of CUPS (electricity supply point) codesExample: ["ES0021000000000001AA"]

Response

Returns the created facility object with HTTP 201.

string

Facility UUID

string

Facility name

string | null

Physical address

string

ISO country code (e.g. ES, FR, DE)

string

Facility type (e.g. office, warehouse, factory)

array[string] | null

Enabled consumption categories: heat, electricity, water, recharge

array[string] | null

List of CUPS codes

string

Facility status: active or archived

number | null

Total CO2e emissions (tCO2e)

number | null

CO2e emissions from biomass sources

number | null

Logistic factor for scope 2 (0 to 1)

string | null

Purpose type of the facility

datetime

Creation timestamp (ISO 8601)

string | null

Last update timestamp (ISO 8601)

integer

Number of invoices in review status

integer

Number of configured categories with no invoices

string | null

Water type of the waste water treatment line (only for waste_water_facilities)

boolean | null

Whether methane is burned (only for waste_water_facilities)

object | null

Waste water treatment line config (only for waste_water_facilities)

Show WWT Line Object

string

Line UUID

string

Line code identifier

object | null

Sludge treatment line config (only for waste_water_facilities)

Show Sludge Line Object

string

Line UUID

string

Line code identifier

object | null

Water discharge line config (only for waste_water_facilities)

Show WWD Line Object

string

Line UUID

string

Line code identifier

Example

curl -X POST "https://api.dcycle.io/v1/facilities" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Madrid Office",
    "type": "office",
    "country": "ES",
    "address": "Calle Gran Vía 1, Madrid",
    "logistic_factor": 0.8,
    "categories": ["heat", "electricity", "water"]
  }'

import requests
import os

headers = {
    "x-api-key": os.getenv("DCYCLE_API_KEY"),
    "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
    "Content-Type": "application/json"
}

payload = {
    "name": "Madrid Office",
    "type": "office",
    "country": "ES",
    "address": "Calle Gran Vía 1, Madrid",
    "logistic_factor": 0.8,
    "categories": ["heat", "electricity", "water"]
}

response = requests.post(
    "https://api.dcycle.io/v1/facilities",
    headers=headers,
    json=payload
)

facility = response.json()
print(f"Facility created: {facility['id']}")

const axios = require('axios');

const headers = {
  'x-api-key': process.env.DCYCLE_API_KEY,
  'x-organization-id': process.env.DCYCLE_ORG_ID,
  'Content-Type': 'application/json'
};

axios.post('https://api.dcycle.io/v1/facilities', {
  name: "Madrid Office",
  type: "office",
  country: "ES",
  address: "Calle Gran Vía 1, Madrid",
  logistic_factor: 0.8,
  categories: ["heat", "electricity", "water"]
}, { headers })
.then(response => console.log(`Created: ${response.data.id}`));

Successful Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Madrid Office",
  "type": "office",
  "country": "ES",
  "address": "Calle Gran Vía 1, Madrid",
  "status": "active",
  "co2e": null,
  "co2e_biomass": null,
  "logistic_factor": 0.8,
  "categories": ["heat", "electricity", "water"],
  "cups_list": null,
  "facility_purpose_type": "facilities",
  "invoices_in_review_count": 0,
  "categories_without_data": 0,
  "water_type": null,
  "methane_burned": null,
  "wwt_line": null,
  "sludge_line": null,
  "wwd_line": null,
  "created_at": "2024-11-24T10:30:00Z",
  "updated_at": "2024-11-24T10:30:00Z"
}

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}

403 Forbidden

Cause: The authenticated user is not a member of the organization

{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}

422 Validation Error

Cause: Neither address nor country provided

{
  "detail": "Either address or country is required."
}

Cause: Invalid address

{
  "detail": "Invalid address."
}

List Facilities

Retrieve all facilities

Update Facility

Modify facility details

​Create Facility

​Request

​Headers

​Body Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​422 Validation Error

​Related Endpoints

List Facilities

Update Facility

Create Facility

Request

Headers

Body Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

422 Validation Error

Related Endpoints