List Invoice Filter Options

const options = {method: 'GET', headers: {'x-organization-id': '<x-organization-id>'}};

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

{
  "cups": {},
  "suppliers": {},
  "uploaded_by": {
    "id": "<string>",
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "<string>"
  },
  "sources": {},
  "stationary_fuels": {},
  "refrigerant_fuels": {},
  "supply_contracts": {}
}

GET

invoices

filter-options

List Invoice Filter Options

const options = {method: 'GET', headers: {'x-organization-id': '<x-organization-id>'}};

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

{
  "cups": {},
  "suppliers": {},
  "uploaded_by": {
    "id": "<string>",
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "<string>"
  },
  "sources": {},
  "stationary_fuels": {},
  "refrigerant_fuels": {},
  "supply_contracts": {}
}

← Invoices API Get the contents of all seven invoice filter dropdowns for one facility and invoice type, in a single call — CUPS codes, suppliers, uploaders, sources, stationary fuels, refrigerant fuels and supply contracts.

The lists do not cascade. Each list is the full universe of values that exist for the (facility, type) pair, and is not narrowed by whatever filters the user has already selected. This is deliberate: it keeps multi-select dropdowns stable, so picking a supplier does not empty the fuel list underneath it.The consequence to design around: a user can combine two options that no invoice actually has, and get an empty result. The lists tell you what exists on the facility, not which combinations are valid together.

type is free text, not a closed list. An unrecognised type is not rejected — it simply matches no invoices, and every one of the seven lists comes back empty. The values the enum defines are heat, electricity, water, recharge, process and waste_water_treatment.So “this facility has no invoice data” and “I sent electric instead of electricity” produce the same response. Check the spelling before concluding the facility is empty.

Request

Headers

string

required

UUID of the organization you are working in.Format: UUID

string

Your API key.

Query Parameters

string

required

UUID of the facility whose invoices you are filtering.The facility is resolved across the organization family — the header organization and its accepted descendants — so a holding can read a subsidiary’s filter options. A facility outside that perimeter returns 404, never 403.Format: UUID

string

required

Invoice type.Accepted values: heat, electricity, water, recharge, process, waste_water_treatment

Response

Seven lists, always present, each possibly empty.

array[string]

CUPS codes found on this facility’s invoices. Plain strings — relevant for Spanish electricity and gas supplies.

array[object]

Suppliers, as { id, name }.

array[object]

The users who uploaded invoices.

Show User Option

string

User UUID.

string

Given name.

string

Family name.

string

Email address — useful as the disambiguator when two users share a name.

array[string]

Where the invoices came from, as plain strings.

array[object]

Stationary combustion fuels present on the invoices, as { id, name }.

array[object]

Refrigerant gases present on the invoices, as { id, name }.

array[object]

Supply contracts, as { id, name }. Note that name carries the contract’s CUPS, not a contract title — so this list and cups above can show the same codes in two different shapes.

Two shapes in one response. cups and sources are arrays of plain strings; the other five are arrays of objects. Send id back as the filter value for the object lists, and the string itself for the other two.

Example

curl -X GET "https://api.dcycle.io/v1/invoices/filter-options?facility_id=YOUR_FACILITY_ID&type=electricity" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID"

import requests

HEADERS = {
    "x-api-key": "YOUR_API_KEY",
    "x-organization-id": "YOUR_ORGANIZATION_ID",
}

INVOICE_TYPES = {"heat", "electricity", "water", "recharge", "process", "waste_water_treatment"}


def filter_options(facility_id, invoice_type):
    # An unknown type returns empty lists rather than an error, so check first
    if invoice_type not in INVOICE_TYPES:
        raise ValueError(f"{invoice_type!r} is not one of {sorted(INVOICE_TYPES)}")

    return requests.get(
        "https://api.dcycle.io/v1/invoices/filter-options",
        headers=HEADERS,
        params={"facility_id": facility_id, "type": invoice_type},
        timeout=30,
    ).json()


options = filter_options("YOUR_FACILITY_ID", "electricity")
print([s["name"] for s in options["suppliers"]])
print(options["cups"])

const INVOICE_TYPES = [
  "heat",
  "electricity",
  "water",
  "recharge",
  "process",
  "waste_water_treatment",
];

async function filterOptions(facilityId, invoiceType) {
  if (!INVOICE_TYPES.includes(invoiceType)) {
    throw new Error(`${invoiceType} is not one of ${INVOICE_TYPES.join(", ")}`);
  }

  const params = new URLSearchParams({
    facility_id: facilityId,
    type: invoiceType,
  });
  const response = await fetch(
    `https://api.dcycle.io/v1/invoices/filter-options?${params}`,
    {
      headers: {
        "x-api-key": "YOUR_API_KEY",
        "x-organization-id": "YOUR_ORGANIZATION_ID",
      },
    },
  );
  return response.json();
}

Successful Response

Returns 200 OK.

{
  "cups": ["ES0031408000000000AB0F"],
  "suppliers": [
    {
      "id": "3f8a1c74-5d29-4e63-b018-7c4e9a2b5f61",
      "name": "Iberdrola"
    }
  ],
  "uploaded_by": [
    {
      "id": "6b2d9e41-7a83-4c50-9f27-1e5b8d3a0c94",
      "first_name": "Ana",
      "last_name": "Ruiz",
      "email": "ana.ruiz@example.com"
    }
  ],
  "sources": ["manual"],
  "stationary_fuels": [],
  "refrigerant_fuels": [],
  "supply_contracts": []
}

The empty lists here are normal: an electricity facility has no stationary or refrigerant fuels.

Common Errors

404 Not Found

Cause: The facility does not exist, or it sits outside the organization family. Both return the same 404 on purpose — the API never confirms that a facility exists elsewhere.

422 Unprocessable Entity

Cause: facility_id or type is missing. Both are required.

{
  "detail": [
    {
      "loc": ["query", "type"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

A misspelled type produces no error — see the warning above.

Use Cases

Because all seven lists arrive together, you can build the complete filter bar for a facility with a single call rather than one request per dropdown.

Decide which dropdowns to hide

An empty list means the facility has no invoices carrying that attribute. Hiding those dropdowns instead of showing them empty is usually the better interface — and this response is what tells you which ones they are.

List Invoices

Apply the filters you just populated

Get Invoice Totals

Aggregate the filtered set

Create Invoice

Add the invoices these options describe

Invoices API

Everything the Invoices API covers

​Request

​Headers

​Query Parameters

​Response

​Example

​Successful Response

​Common Errors

​404 Not Found

​422 Unprocessable Entity

​Use Cases

​Render a whole filter panel in one request

​Decide which dropdowns to hide

​Related Endpoints

List Invoices

Get Invoice Totals

Create Invoice

Invoices API

Request

Headers

Query Parameters

Response

Example

Successful Response

Common Errors

404 Not Found

422 Unprocessable Entity

Use Cases

Render a whole filter panel in one request

Decide which dropdowns to hide

Related Endpoints