📘 This documentation reflects the ciflow API available to partners. Some endpoints require specific agreements or are under active development per the roadmap agreed with each partner. For access, terms, additional examples and the latest version, contact the ciflow team at partners@ciflow.net or request access from Request partner access.

ciflow API documentation

REST API to integrate building energy diagnostics, equipment telemetry and commercial reports into your systems. 56 documented endpoints.

Introduction

ciflow is a building energy diagnostics platform. The partner API lets you register properties from their cadastral reference, fetch official data (Catastro, Energy Performance Certificate, building inspection certificate), simulate improvement scenarios, get catalogue recommendations, ingest telemetry from installed equipment and generate reports that close sales.

Qualify visits and prioritise quotes with real building data.
Connect your CRM or ERP to sync clients, leads and reports.
Send PLC/equipment data and let ciflow generate charts, anomalies and reports.

The API is versioned in the path. The current version is /api/v1/partner-api/.... Base URL:

https://api.ciflow.net/api/v1/partner-api

Authentication

Every request authenticates with the X-API-Key header. Keys are prefixed cf_live_… and issued to approved partners. ciflow only stores the key hash and prefix: keep it safe, you won't be able to recover it. To get a key you must be an approved partner — request partner access.

curl https://api.ciflow.net/api/v1/partner-api/properties/8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Rate limits

Limits apply per API key:

1000 requests/min on read operations.
100 requests/min on write operations.
5000 records/min on telemetry ingestion.

Every response includes the X-RateLimit-Remaining header with the requests left in the current window. When the limit is exceeded the API responds 429 Too Many Requests; retry with exponential backoff.

Errors

The API uses standard HTTP codes. Errors return a JSON body with a code, a human-readable message and a request_id we ask for when opening a support ticket.

HTTP code	Meaning
200 OK	Successful request; the body contains the resource.
201 Created	Resource created successfully.
202 Accepted	Accepted for async processing (telemetry, reports).
400 Bad Request	Malformed request.
401 Unauthorized	Missing or invalid X-API-Key.
403 Forbidden	The API key has no access to this resource or feature.
404 Not Found	The resource does not exist or is not yours.
409 Conflict	State conflict (e.g. duplicate resource).
422 Unprocessable Entity	The body does not match the expected schema.
429 Too Many Requests	Rate limit exceeded.
500 Internal Server Error	Internal error; retry.

{
  "error": {
    "code": "validation_error",
    "message": "cadastral_reference is required",
    "request_id": "req_8f1c2d3e4a5b6c7d"
  }
}

Idempotency

Write operations accept the Idempotency-Key header (we recommend a UUID v4). If you resend a request with the same key within 24 hours, ciflow returns the original result without re-running the operation. Use it to protect network retries against lost responses.

curl -X POST https://api.ciflow.net/api/v1/partner-api/properties \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f9a1c2e-1d3b-4a6c-9e8f-0b1c2d3e4f5a" \
  -d '{"cadastral_reference": "9872023VH5797S0001WX"}'

Properties

Register and query properties. When you create a property, ciflow enriches it with official data (Catastro, energy certificate, building inspection) asynchronously and resiliently.

POST/properties

Create a property

Registers a property from its cadastral reference. ciflow runs the enrichment pipeline (Catastro + Energy Performance Certificate + building inspection certificate). Enrichment that doesn't finish in time is retried and notified via the property.enriched webhook; unavailable fields come back as null without blocking the response.

Cuerpo de la petición

Campo	Tipo	Descripción
cadastral_reference*	string	14- or 20-character cadastral reference. Uniquely identifies the property in Catastro.

Errores

HTTP	Código	Cuándo
400	invalid_cadastral_reference	Invalid cadastral reference format.
401	missing_api_key	Missing or invalid X-API-Key header.
422	validation_error	The body does not match the expected schema.
429	rate_limited	Write limit exceeded (100 req/min).

curl -X POST https://api.ciflow.net/api/v1/partner-api/properties \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"cadastral_reference": "9872023VH5797S0001WX"}'

Respuesta de ejemplo

{
  "property_id": "8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "address": "Calle Mayor 5",
  "municipality": "Madrid",
  "province": "Madrid",
  "ccaa": "Comunidad de Madrid",
  "year_built": 1978,
  "climate_zone": "D3",
  "energy_certificate": { "rating": "E", "source": "estimated" },
  "ite_fetch_status": "ok"
}

GET/properties/{id}

Get a property

Returns the property with all available enriched data: cadastral identification, surface, year built, climate zone, energy certificate and building inspection certificate.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Property identifier.

Errores

HTTP	Código	Cuándo
401	missing_api_key	Missing or invalid X-API-Key header.
404	property_not_found	Does not exist or does not belong to your tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/properties/8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "property_id": "8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "cadastral_reference": "9872023VH5797S0001WX",
  "address": "Calle Mayor 5",
  "municipality": "Madrid",
  "province": "Madrid",
  "ccaa": "Comunidad de Madrid",
  "postcode": "28013",
  "year_built": 1978,
  "surface_m2_built": 92.0,
  "surface_m2_useful": 78.0,
  "n_rooms": 3,
  "climate_zone": "D3",
  "energy_certificate": { "rating": "E", "source": "estimated" },
  "ite_fetch_status": "ok",
  "ite_data": { "result": "favorable_con_deficiencias" }
}

GET/properties/{id}/cadastral

Cadastral data

Returns the raw cadastral record for the property: use, surface, age and construction elements according to Catastro.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Property identifier.

Errores

HTTP	Código	Cuándo
404	property_not_found	Does not exist or does not belong to your tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/properties/{id}/cadastral \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "cadastral_reference": "9872023VH5797S0001WX",
  "use": "residential",
  "surface_m2": 92.0,
  "year_built": 1978,
  "elements": [{ "type": "vivienda", "floor": "02", "door": "B" }]
}

GET/properties/{id}/energy-certificate

Energy certificate

Returns the property's Energy Performance Certificate. If it is not found in the official autonomous-region registries, an estimate based on year built and climate zone is returned, flagged with source: "estimated".

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Property identifier.

Errores

HTTP	Código	Cuándo
404	property_not_found	Does not exist or does not belong to your tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/properties/{id}/energy-certificate \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "rating": "E",
  "primary_energy_kwh_m2_year": 168.4,
  "co2_kg_m2_year": 36.1,
  "source": "estimated",
  "registry": null
}

GET/properties/{id}/climate-zone

Climate zone (CTE)

Returns the Spanish Building Code (CTE) climate zone that applies to the property, used by the simulator for the degree-day calculation.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Property identifier.

Errores

HTTP	Código	Cuándo
404	property_not_found	Does not exist or does not belong to your tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/properties/{id}/climate-zone \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{ "climate_zone": "D3", "winter_zone": "D", "summer_zone": "3" }

GET/properties/{id}/ite

Building inspection certificate

Returns the building inspection data obtained from the available official registries (currently Madrid and Comunitat Valenciana). If there is no data or the registry does not respond, ite_fetch_status is returned as something other than "ok" with partial or null data.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Property identifier.

Errores

HTTP	Código	Cuándo
404	property_not_found	Does not exist or does not belong to your tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/properties/{id}/ite \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "ite_fetch_status": "ok",
  "result": "favorable_con_deficiencias",
  "inspection_date": "2021-06-14",
  "next_inspection_due": "2031-06-14",
  "deficiencies": ["fachada", "cubierta"]
}

GET/properties/{id}/thermal-envelope

Estimated thermal envelope

Returns the thermal-envelope estimate (transmittances and demand) used as the basis by the deterministic simulator. I/O-free calculation derived from the climate zone and the year built.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Property identifier.

Errores

HTTP	Código	Cuándo
404	property_not_found	Does not exist or does not belong to your tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/properties/{id}/thermal-envelope \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "u_wall_w_m2k": 1.42,
  "u_roof_w_m2k": 1.05,
  "heating_demand_kwh_m2_year": 96.0,
  "method": "cte_degree_days"
}

GET/properties/{id}/subsidies

Applicable subsidies

Returns the energy-retrofit grants and subsidies potentially applicable to the property based on its autonomous region and characteristics.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Property identifier.

Errores

HTTP	Código	Cuándo
404	property_not_found	Does not exist or does not belong to your tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/properties/{id}/subsidies \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "subsidies": [
    { "program": "PREE 5000", "scope": "municipio < 5000 hab", "max_pct": 0.4 },
    { "program": "Fondos Next Generation", "scope": "rehabilitación integral", "max_pct": 0.8 }
  ]
}

GET/properties/{id}/radon-risk

Radon risk

Returns the municipality's radon risk classification according to the CSN map, relevant for ventilation recommendations.

Endpoint under active development per the roadmap agreed with each partner. Contact the team for availability.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Property identifier.

Errores

HTTP	Código	Cuándo
404	property_not_found	Does not exist or does not belong to your tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/properties/{id}/radon-risk \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{ "radon_zone": "I", "risk_level": "low", "source": "CSN" }

PATCH/properties/{id}

Update a property

Updates editable fields of the property (data the partner provides that complements the automatic enrichment).

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Property identifier.

Cuerpo de la petición

Campo	Tipo	Descripción
n_rooms	integer	Number of rooms.
surface_m2_useful	number	Usable surface in m².
year_built	integer	Year built, if it differs from the cadastral one.

Errores

HTTP	Código	Cuándo
404	property_not_found	Does not exist or does not belong to your tenant.
422	validation_error	Field out of range or wrong type.

curl -X PATCH https://api.ciflow.net/api/v1/partner-api/properties/{id} \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"n_rooms": 4}'

Respuesta de ejemplo

{ "property_id": "8f1c2d3e-...", "updated": true }

DELETE/properties/{id}

Delete a property

Deletes the property and its derived data (associated simulations, recommendations and reports). Irreversible operation.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Property identifier.

Errores

HTTP	Código	Cuándo
404	property_not_found	Does not exist or does not belong to your tenant.

curl -X DELETE https://api.ciflow.net/api/v1/partner-api/properties/{id} \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{ "deleted": true }

Quick Lookup

One-off queries without creating a persistent property. Useful to validate data before registering the property.

POST/lookup/cadastral

Cadastral lookup

Resolves a cadastral reference or a free-text address and returns the cadastral record without persisting anything.

Cuerpo de la petición

Campo	Tipo	Descripción
cadastral_reference	string	Cadastral reference (recommended).
address	string	Free-text address, alternative if there is no reference.

Errores

HTTP	Código	Cuándo
400	ambiguous_address	The address could not be geocoded unambiguously.

curl -X POST https://api.ciflow.net/api/v1/partner-api/lookup/cadastral \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"cadastral_reference": "9872023VH5797S0001WX"}'

Respuesta de ejemplo

{
  "cadastral_reference": "9872023VH5797S0001WX",
  "address": "Calle Mayor 5, 28013 Madrid",
  "use": "residential",
  "year_built": 1978
}

POST/lookup/energy-certificate

Energy certificate lookup

Looks up the energy certificate by cadastral reference in the official registries without creating the property.

Cuerpo de la petición

Campo	Tipo	Descripción
cadastral_reference*	string	Cadastral reference.

Errores

HTTP	Código	Cuándo
404	certificate_not_found	No certificate found in the registries.

curl -X POST https://api.ciflow.net/api/v1/partner-api/lookup/energy-certificate \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"cadastral_reference": "9872023VH5797S0001WX"}'

Respuesta de ejemplo

{ "rating": "E", "source": "registry", "registry": "Comunidad de Madrid" }

POST/lookup/cups

CUPS lookup

Resolves the CUPS code (electricity supply point) associated with an address or cadastral reference.

Requires a prior agreement, contact the team.

Cuerpo de la petición

Campo	Tipo	Descripción
cadastral_reference	string	Cadastral reference.
address	string	Free-text address.

Errores

HTTP	Código	Cuándo
403	agreement_required	CUPS lookup requires a specific agreement.

curl -X POST https://api.ciflow.net/api/v1/partner-api/lookup/cups \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"cadastral_reference": "9872023VH5797S0001WX"}'

Respuesta de ejemplo

{ "cups": "ES0021000000000000XX0F", "distributor": "i-DE" }

Energy Data

Supply points, distributor data-access consents and invoices. Ingesting real consumption feeds the simulator and the reports.

GET/properties/{id}/consumption

Energy consumption

Returns the property's electricity consumption series aggregated at the requested granularity. The source can be the distributor (with consent) or invoices processed by OCR.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Property identifier.

Parámetros de consulta

Campo	Tipo	Descripción
from*	date	Start date (ISO 8601, YYYY-MM-DD).
to*	date	End date (ISO 8601).
granularity	string	hourly \| daily \| monthly. Defaults to monthly.

Errores

HTTP	Código	Cuándo
404	property_not_found	Does not exist or does not belong to your tenant.
409	no_consent	No distributor consent and no invoices uploaded.

curl -X GET https://api.ciflow.net/api/v1/partner-api/properties/{id}/consumption?from=2026-01-01&to=2026-03-31&granularity=monthly \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "granularity": "monthly",
  "series": [
    { "period_start": "2026-01-01", "consumption_kwh": 412.0, "source": "datadis" },
    { "period_start": "2026-02-01", "consumption_kwh": 388.5, "source": "datadis" }
  ]
}

POST/properties/{id}/cups

Associate a CUPS

Registers an electricity supply point (CUPS) for the property, including contracted power and tariff.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Property identifier.

Cuerpo de la petición

Campo	Tipo	Descripción
cups_code*	string	CUPS code (20-22 characters).
distributor	string	Distribuidora.
contracted_power_p1_kw	number	Contracted power period 1.
tariff	string	Access tariff, e.g. 2.0TD.

Errores

HTTP	Código	Cuándo
422	invalid_cups	Invalid CUPS format.

curl -X POST https://api.ciflow.net/api/v1/partner-api/properties/{id}/cups \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"cups_code": "ES0021000000000000XX0F", "tariff": "2.0TD"}'

Respuesta de ejemplo

{ "cups_id": "1a2b3c4d-...", "cups_code": "ES0021000000000000XX0F" }

POST/properties/{id}/cups/{cups}/datadis-consent

Request distributor consent

Starts the consent flow to access the distributor's consumption data through Datadis for the given CUPS.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Property identifier.
cups*	string	CUPS code.

Cuerpo de la petición

Campo	Tipo	Descripción
nif*	string	Tax ID of the supply holder.

Errores

HTTP	Código	Cuándo
409	consent_already_active	A valid consent already exists.

curl -X POST https://api.ciflow.net/api/v1/partner-api/properties/{id}/cups/ES0021000000000000XX0F/datadis-consent \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"nif": "00000000T"}'

Respuesta de ejemplo

{ "consent_status": "pending", "expires_at": "2027-05-18T00:00:00Z" }

POST/properties/{id}/invoices

Upload an energy invoice

Uploads an invoice (PDF or image) that ciflow processes with OCR to extract consumption, power and period. The result is added to the property's consumption series.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Property identifier.

Cuerpo de la petición

Campo	Tipo	Descripción
file*	binary	Invoice file (multipart/form-data).

Errores

HTTP	Código	Cuándo
422	unsupported_file	Unsupported file format.

curl -X POST https://api.ciflow.net/api/v1/partner-api/properties/{id}/invoices \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@factura.pdf"

Respuesta de ejemplo

{ "invoice_id": "9f8e7d6c-...", "status": "processing" }

GET/properties/{id}/invoices

List invoices

Returns the invoices uploaded for the property with their processing status and the extracted data.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Property identifier.

Errores

HTTP	Código	Cuándo
404	property_not_found	Does not exist or does not belong to your tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/properties/{id}/invoices \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "invoices": [
    { "invoice_id": "9f8e7d6c-...", "status": "processed", "ocr_confidence": 0.97 }
  ]
}

Simulations

Deterministic simulator of energy-improvement scenarios (heat pump, insulation, photovoltaics). Reproducible calculation, no hot-path external I/O.

POST/properties/{id}/simulate

Run a simulation

Runs an energy-improvement scenario on the property. It combines the estimated thermal envelope, irradiation data and tariffs, and returns savings, investment and payback period along with the applicable subsidies.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Property identifier.

Cuerpo de la petición

Campo	Tipo	Descripción
scenario_type	string	heat_pump \| insulation \| pv \| full. Defaults to heat_pump.
inputs	object	Optional parameters that override the presets.

Errores

HTTP	Código	Cuándo
404	property_not_found	Does not exist or does not belong to your tenant.
422	unknown_scenario	scenario_type not recognised.

curl -X POST https://api.ciflow.net/api/v1/partner-api/properties/{id}/simulate \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"scenario_type": "heat_pump"}'

Respuesta de ejemplo

{
  "scenario_type": "heat_pump",
  "outputs": {
    "annual_saving_eur": 612.0,
    "investment_eur": 8900.0,
    "payback_years": 11.4,
    "co2_reduction_kg_year": 1180.0
  },
  "thermal_envelope": { "heating_demand_kwh_m2_year": 96.0 },
  "subsidies": [{ "program": "Fondos Next Generation", "max_pct": 0.8 }]
}

GET/properties/{id}/simulations

List simulations

Returns the history of simulations run on the property.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Property identifier.

Errores

HTTP	Código	Cuándo
404	property_not_found	Does not exist or does not belong to your tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/properties/{id}/simulations \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "simulations": [
    { "id": "aa11bb22-...", "scenario_type": "heat_pump", "status": "completed" }
  ]
}

GET/simulations/{id}

Get a simulation

Returns the detail of a specific simulation, including inputs and outputs.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Simulation identifier.

Errores

HTTP	Código	Cuándo
404	simulation_not_found	Does not exist or does not belong to your tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/simulations/aa11bb22-... \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "id": "aa11bb22-...",
  "scenario_type": "heat_pump",
  "status": "completed",
  "inputs": {},
  "outputs": { "annual_saving_eur": 612.0, "payback_years": 11.4 }
}

POST/simulations/{id}/compare

Compare simulations

Compares the given simulation with others for the same property and returns a comparison table of savings, investment and payback.

Endpoint under active development per the roadmap agreed with each partner.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Base simulation.

Cuerpo de la petición

Campo	Tipo	Descripción
against*	string[]	IDs of simulations to compare.

Errores

HTTP	Código	Cuándo
404	simulation_not_found	Some simulation does not exist.

curl -X POST https://api.ciflow.net/api/v1/partner-api/simulations/aa11bb22-.../compare \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"against": ["cc33dd44-..."]}'

Respuesta de ejemplo

{
  "base": "aa11bb22-...",
  "comparison": [
    { "id": "cc33dd44-...", "delta_saving_eur": 120.0, "delta_payback_years": -1.8 }
  ]
}

Recommendations

Technical recommendation of catalogue solutions: scored on real specs (performance, power sizing vs demand, U-value, capacity…), ITE status and the tenant's preferred manufacturer. Optionally re-prices the economics with the product's real cost and adds a natural-language summary.

GET/properties/{id}/recommendations

Get recommendations

Returns the ranking of recommended solutions for the property. The engine scores each product on technical fit using the catalogue specs: performance (SCOP/COP at -7 °C), power sizing against the property's estimated heating demand (under/oversized units are penalised), minimum operating temperature in cold zones, U-value and thickness for insulation, efficiency and Wp for PV, MPPT/hybrid for inverters and capacity/cycles for batteries. It folds in ITE signals and, if the tenant has a preferred manufacturer configured, applies the configured boost (never by name in code). When simulation_id is sent it re-prices the economics with the top product's real cost and adds a natural-language summary.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Property identifier.

Parámetros de consulta

Campo	Tipo	Descripción
scenario_type	string	Base scenario. Defaults to heat_pump.

Errores

HTTP	Código	Cuándo
404	property_not_found	Does not exist or does not belong to your tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/properties/{id}/recommendations?scenario_type=heat_pump \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "category": "heat_pump",
  "ranked_items": [
    { "sku": "GEN-A-12", "name": "Bomba de calor 12 kW", "score": 0.91,
      "reason": "SCOP 4.2 · 12 kW (bien dimensionada para ~10 kW)",
      "manufacturer_boost": false },
    { "sku": "GEN-B-08", "name": "Bomba de calor 8 kW", "score": 0.78,
      "reason": "SCOP 4.0 · 8 kW: puede quedarse corta para ~10 kW" }
  ],
  "manufacturer_boost_applied": false,
  "summary_text": "Para el escenario heat_pump, la opción mejor valorada es...",
  "recommended_economics": {
    "investment_eur": 7500, "annual_savings_eur": 848,
    "payback_years": 8.8, "sku": "GEN-A-12",
    "generic_investment_eur": 9971
  }
}

POST/recommendations/{id}/feedback

Send recommendation feedback

Records partner feedback on a recommendation (accepted, rejected, reason) to feed the commercial follow-up.

Endpoint under active development per the roadmap agreed with each partner.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Recommendation identifier.

Cuerpo de la petición

Campo	Tipo	Descripción
outcome*	string	accepted \| rejected \| deferred.
reason	string	Motivo opcional.

Errores

HTTP	Código	Cuándo
404	recommendation_not_found	Does not exist or does not belong to your tenant.

curl -X POST https://api.ciflow.net/api/v1/partner-api/recommendations/{id}/feedback \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"outcome": "accepted"}'

Respuesta de ejemplo

{ "recorded": true }

Clients

Management of the partner's end-client portfolio, their properties and accumulated reports.

POST/clients

Create a client

Registers an end client within your tenant.

Endpoint under active development per the roadmap agreed with each partner.

Cuerpo de la petición

Campo	Tipo	Descripción
name*	string	Client name.
email	string	Contact email.
external_ref	string	Reference in your CRM.

Errores

HTTP	Código	Cuándo
422	validation_error	Invalid client data.

curl -X POST https://api.ciflow.net/api/v1/partner-api/clients \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Comunidad C/ Mayor 5"}'

Respuesta de ejemplo

{ "client_id": "dd44ee55-...", "name": "Comunidad C/ Mayor 5" }

GET/clients

List clients

Returns the client portfolio with cursor pagination. Use the next_cursor field for the next page.

Endpoint under active development per the roadmap agreed with each partner.

Parámetros de consulta

Campo	Tipo	Descripción
cursor	string	Cursor for the next page.
limit	integer	Page size (max 100, default 50).

Errores

HTTP	Código	Cuándo
400	invalid_cursor	Malformed cursor.

curl -X GET https://api.ciflow.net/api/v1/partner-api/clients?limit=50 \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "clients": [{ "client_id": "dd44ee55-...", "name": "Comunidad C/ Mayor 5" }],
  "next_cursor": "eyJvZmZzZXQiOjUwfQ=="
}

GET/clients/{id}

Get a client

Returns the detail of a client.

Endpoint under active development per the roadmap agreed with each partner.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Client identifier.

Errores

HTTP	Código	Cuándo
404	client_not_found	Does not exist or does not belong to your tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/clients/{id} \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{ "client_id": "dd44ee55-...", "name": "Comunidad C/ Mayor 5", "properties_count": 3 }

PATCH/clients/{id}

Update a client

Updates a client's contact data or external reference.

Endpoint under active development per the roadmap agreed with each partner.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Client identifier.

Cuerpo de la petición

Campo	Tipo	Descripción
email	string	New contact email.

Errores

HTTP	Código	Cuándo
404	client_not_found	Does not exist or does not belong to your tenant.

curl -X PATCH https://api.ciflow.net/api/v1/partner-api/clients/{id} \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@finca.es"}'

Respuesta de ejemplo

{ "client_id": "dd44ee55-...", "updated": true }

GET/clients/{id}/properties

Properties of a client

Returns the properties associated with a client.

Endpoint under active development per the roadmap agreed with each partner.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Client identifier.

Errores

HTTP	Código	Cuándo
404	client_not_found	Does not exist or does not belong to your tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/clients/{id}/properties \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{ "properties": [{ "property_id": "8f1c2d3e-...", "address": "Calle Mayor 5" }] }

POST/clients/{id}/reports

Generate accumulated client report

Generates an accumulated report consolidating all of the client's properties: cadastral data, real consumption, telemetry and simulations, in a single document to close the sale and build loyalty.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Client identifier.

Cuerpo de la petición

Campo	Tipo	Descripción
period_start	date	Report period start.
period_end	date	Report period end.

Errores

HTTP	Código	Cuándo
404	client_not_found	Does not exist or does not belong to your tenant.

curl -X POST https://api.ciflow.net/api/v1/partner-api/clients/{id}/reports \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"period_start": "2026-01-01", "period_end": "2026-04-30"}'

Respuesta de ejemplo

{ "report_id": "rep-77aa88-...", "status": "processing" }

GET/clients/{id}/reports

List a client's reports

Returns the accumulated reports generated for the client.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Client identifier.

Errores

HTTP	Código	Cuándo
404	client_not_found	Does not exist or does not belong to your tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/clients/{id}/reports \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{ "reports": [{ "report_id": "rep-77aa88-...", "status": "completed" }] }

Leads

Commercial opportunities. ciflow automatically prioritises buildings with an expiring ITE or relevant deficiencies as high-value leads.

POST/leads

Create a lead

Creates a commercial opportunity, optionally linked to a property.

Endpoint under active development per the roadmap agreed with each partner.

Cuerpo de la petición

Campo	Tipo	Descripción
property_id	uuid	Associated property.
value_estimate_eur	number	Estimated value of the opportunity.

Errores

HTTP	Código	Cuándo
422	validation_error	Invalid lead data.

curl -X POST https://api.ciflow.net/api/v1/partner-api/leads \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"value_estimate_eur": 8900}'

Respuesta de ejemplo

{ "lead_id": "lead-99cc-...", "status": "new" }

GET/leads

List leads

Returns the tenant's leads, filterable by status.

Endpoint under active development per the roadmap agreed with each partner.

Parámetros de consulta

Campo	Tipo	Descripción
status	string	new \| contacted \| won \| lost.

Errores

HTTP	Código	Cuándo
401	missing_api_key	Missing or invalid X-API-Key header.

curl -X GET https://api.ciflow.net/api/v1/partner-api/leads?status=new \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{ "leads": [{ "lead_id": "lead-99cc-...", "status": "new" }] }

PATCH/leads/{id}

Update a lead

Updates the status or data of a lead.

Endpoint under active development per the roadmap agreed with each partner.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Lead identifier.

Cuerpo de la petición

Campo	Tipo	Descripción
status	string	New lead status.

Errores

HTTP	Código	Cuándo
404	lead_not_found	Does not exist or does not belong to your tenant.

curl -X PATCH https://api.ciflow.net/api/v1/partner-api/leads/{id} \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"status": "contacted"}'

Respuesta de ejemplo

{ "lead_id": "lead-99cc-...", "updated": true }

POST/leads/{id}/notes

Add a note to a lead

Adds a commercial follow-up note to the lead.

Endpoint under active development per the roadmap agreed with each partner.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Lead identifier.

Cuerpo de la petición

Campo	Tipo	Descripción
text*	string	Note content.

Errores

HTTP	Código	Cuándo
404	lead_not_found	Does not exist or does not belong to your tenant.

curl -X POST https://api.ciflow.net/api/v1/partner-api/leads/{id}/notes \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"text": "Visita agendada"}'

Respuesta de ejemplo

{ "lead_id": "lead-99cc-...", "notes_count": 3 }

Devices & Telemetry

Register installed equipment (HVAC, photovoltaics, monitoring) and send its telemetry. ciflow turns it into charts, anomalies and insights for the end client.

POST/devices

Register a device

Registers (or updates, if the external_id already exists) a device within your tenant, optionally linked to a property. Idempotent with respect to external_id.

Cuerpo de la petición

Campo	Tipo	Descripción
external_id*	string	Your unique device identifier.
device_type*	string	heat_pump \| pv_inverter \| meter \| sensor.
model	string	Device model.
serial_number	string	Serial number.
property_id	uuid	Property where it is installed.
metadata	object	Free data, opaque to ciflow.

Errores

HTTP	Código	Cuándo
422	validation_error	Missing external_id or device_type.
429	rate_limited	Write limit exceeded.

curl -X POST https://api.ciflow.net/api/v1/partner-api/devices \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "PLC-0427", "device_type": "heat_pump", "property_id": "8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f"}'

Respuesta de ejemplo

{
  "device_id": "dev-aa11-...",
  "external_id": "PLC-0427",
  "created": true
}

GET/devices

List devices

Returns all devices registered in your tenant with their status and last telemetry received.

Errores

HTTP	Código	Cuándo
401	missing_api_key	Missing or invalid X-API-Key header.

curl -X GET https://api.ciflow.net/api/v1/partner-api/devices \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "devices": [
    {
      "device_id": "dev-aa11-...",
      "external_id": "PLC-0427",
      "device_type": "heat_pump",
      "status": "active",
      "last_telemetry_at": "2026-05-18T09:12:00Z"
    }
  ]
}

GET/devices/{external_id}

Get a device

Returns the detail of a device by its external_id.

Parámetros de ruta

Campo	Tipo	Descripción
external_id*	string	Your device identifier.

Errores

HTTP	Código	Cuándo
404	device_not_found	Does not exist or does not belong to your tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/devices/PLC-0427 \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "device_id": "dev-aa11-...",
  "external_id": "PLC-0427",
  "device_type": "heat_pump",
  "status": "active"
}

PATCH/devices/{external_id}

Update a device

Updates the status, model, serial number or metadata of a device.

Parámetros de ruta

Campo	Tipo	Descripción
external_id*	string	Your device identifier.

Cuerpo de la petición

Campo	Tipo	Descripción
status	string	active \| inactive \| maintenance.
model	string	Modelo.
serial_number	string	Serial number.
metadata	object	Free metadata.

Errores

HTTP	Código	Cuándo
404	device_not_found	Does not exist or does not belong to your tenant.

curl -X PATCH https://api.ciflow.net/api/v1/partner-api/devices/PLC-0427 \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"status": "maintenance"}'

Respuesta de ejemplo

{ "ok": true }

DELETE/devices/{external_id}

Decommission a device

Marks the device as decommissioned. Historical telemetry is kept.

Parámetros de ruta

Campo	Tipo	Descripción
external_id*	string	Your device identifier.

Errores

HTTP	Código	Cuándo
404	device_not_found	Does not exist or does not belong to your tenant.

curl -X DELETE https://api.ciflow.net/api/v1/partner-api/devices/PLC-0427 \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{ "ok": true, "status": "decommissioned" }

POST/devices/{external_id}/telemetry

Send telemetry

Ingests a batch of telemetry records for the device. Valid records are accepted (HTTP 202) and invalid ones are returned in drops without aborting the batch. Triggers the device.telemetry_received event.

Parámetros de ruta

Campo	Tipo	Descripción
external_id*	string	Your device identifier.

Cuerpo de la petición

Campo	Tipo	Descripción
records*	array	List of objects { ts (ISO 8601), metric, value_numeric \| value_string, unit }.

Errores

HTTP	Código	Cuándo
404	device_not_found	Does not exist or does not belong to your tenant.
429	rate_limited	Telemetry limit exceeded (5000 records/min).

curl -X POST https://api.ciflow.net/api/v1/partner-api/devices/PLC-0427/telemetry \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"records": [{"ts": "2026-05-18T09:00:00Z", "metric": "cop", "value_numeric": 3.8, "unit": "ratio"}, {"ts": "2026-05-18T09:05:00Z", "metric": "power", "value_numeric": 1.42, "unit": "kW"}]}'

Respuesta de ejemplo

{
  "accepted": 2,
  "dropped": 0,
  "drops": []
}

GET/devices/{external_id}/telemetry

Query telemetry

Returns the device's telemetry for a metric and range, optionally aggregated (avg, min, max, sum).

Endpoint under active development per the roadmap agreed with each partner.

Parámetros de ruta

Campo	Tipo	Descripción
external_id*	string	Your device identifier.

Parámetros de consulta

Campo	Tipo	Descripción
metric*	string	Metric to query (e.g. cop, power).
from*	datetime	Start (ISO 8601).
to*	datetime	End (ISO 8601).
aggregation	string	raw \| hourly \| daily \| monthly.

Errores

HTTP	Código	Cuándo
404	device_not_found	Does not exist or does not belong to your tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/devices/PLC-0427/telemetry?metric=cop&from=2026-05-01T00:00:00Z&to=2026-05-18T00:00:00Z&aggregation=daily \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "metric": "cop",
  "aggregation": "daily",
  "points": [{ "period_start": "2026-05-18", "avg": 3.74, "min": 2.9, "max": 4.5 }]
}

GET/devices/{external_id}/insights

Device insights

Returns the insights detected about the device (performance anomalies, faults, degraded efficiency) with severity and category.

Endpoint under active development per the roadmap agreed with each partner.

Parámetros de ruta

Campo	Tipo	Descripción
external_id*	string	Your device identifier.

Errores

HTTP	Código	Cuándo
404	device_not_found	Does not exist or does not belong to your tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/devices/PLC-0427/insights \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "insights": [
    {
      "severity": "warning",
      "category": "efficiency_degradation",
      "message": "COP medio 18% por debajo de la línea base",
      "detected_at": "2026-05-17T22:00:00Z"
    }
  ]
}

POST/devices/bulk-telemetry

Bulk multi-device telemetry

Ingests telemetry from several devices in a single call. Designed for batch syncs from a gateway or central PLC.

Endpoint under active development per the roadmap agreed with each partner.

Cuerpo de la petición

Campo	Tipo	Descripción
items*	array	List of objects { external_id, records: [...] }.

Errores

HTTP	Código	Cuándo
429	rate_limited	Telemetry limit exceeded.

curl -X POST https://api.ciflow.net/api/v1/partner-api/devices/bulk-telemetry \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"external_id": "PLC-0427", "records": [{"ts": "2026-05-18T09:00:00Z", "metric": "cop", "value_numeric": 3.8}]}]}'

Respuesta de ejemplo

{ "accepted": 240, "dropped": 0, "devices": 12 }

Reports

Generation and download of energy reports. The PDF is delivered proxied by the API (bytes), never as a storage URL.

POST/properties/{id}/report

Generate property report

Runs the given scenario, computes recommendations and subsidies and returns the energy report PDF directly (application/pdf). The report identifier travels in the X-Report-Id header.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Property identifier.

Cuerpo de la petición

Campo	Tipo	Descripción
scenario_type	string	Base scenario. Defaults to heat_pump.

Errores

HTTP	Código	Cuándo
404	property_not_found	Does not exist or does not belong to your tenant.
422	unknown_scenario	scenario_type not recognised.

curl -X POST https://api.ciflow.net/api/v1/partner-api/properties/{id}/report \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"scenario_type": "heat_pump"}' \
  --output informe.pdf

Respuesta de ejemplo

# Respuesta: application/pdf (bytes)
# Cabecera: X-Report-Id: rep-77aa88-99bb-...

GET/reports/{id}

Report metadata

Returns the report metadata (status, size, dates) without downloading the PDF.

Endpoint under active development per the roadmap agreed with each partner.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Report identifier.

Errores

HTTP	Código	Cuándo
404	report_not_found	Does not exist or does not belong to your tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/reports/{id} \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "report_id": "rep-77aa88-...",
  "status": "completed",
  "file_size_bytes": 184320,
  "generated_at": "2026-05-18T09:20:00Z"
}

GET/reports/{id}/download

Download a report PDF

Downloads the PDF of an already-generated report. The content is served proxied by the API.

Endpoint under active development per the roadmap agreed with each partner.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Report identifier.

Errores

HTTP	Código	Cuándo
404	report_not_found	Does not exist or does not belong to your tenant.

curl https://api.ciflow.net/api/v1/partner-api/reports/{id}/download \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  --output informe.pdf

Respuesta de ejemplo

# Respuesta: application/pdf (bytes)

GET/reports

List reports

Returns the reports generated in your tenant.

Endpoint under active development per the roadmap agreed with each partner.

Errores

HTTP	Código	Cuándo
401	missing_api_key	Missing or invalid X-API-Key header.

curl -X GET https://api.ciflow.net/api/v1/partner-api/reports \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{ "reports": [{ "report_id": "rep-77aa88-...", "status": "completed" }] }

Catalog

Catalogue of solutions the recommender reasons about. Pro+ plans can load their own catalogue.

GET/catalog/items

List catalogue items

Returns the items of your tenant's active catalogue, filterable by category.

Endpoint under active development per the roadmap agreed with each partner.

Parámetros de consulta

Campo	Tipo	Descripción
category	string	Category (e.g. heat pump, insulation).

Errores

HTTP	Código	Cuándo
401	missing_api_key	Missing or invalid X-API-Key header.

curl -X GET https://api.ciflow.net/api/v1/partner-api/catalog/items?category=aerotermia \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "items": [
    { "sku": "GEN-A-12", "category": "aerotermia", "name": "Bomba de calor 12 kW", "price_eur": 6200 }
  ]
}

GET/catalog/items/{sku}

Get a catalogue item

Returns the detail of a catalogue item by its SKU.

Endpoint under active development per the roadmap agreed with each partner.

Parámetros de ruta

Campo	Tipo	Descripción
sku*	string	Item SKU.

Errores

HTTP	Código	Cuándo
404	item_not_found	SKU not found in your catalogue.

curl -X GET https://api.ciflow.net/api/v1/partner-api/catalog/items/GEN-A-12 \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "sku": "GEN-A-12",
  "category": "aerotermia",
  "name": "Bomba de calor 12 kW",
  "specs": { "power_kw": 12, "scop": 4.6 },
  "price_eur": 6200
}

POST/catalog/items

Create a catalogue item (Pro+)

Adds an item to the tenant's own catalogue. Available on Pro and Enterprise plans.

Available on Pro+ plans and under active development per the roadmap agreed with each partner.

Cuerpo de la petición

Campo	Tipo	Descripción
sku*	string	Unique SKU in your catalogue.
category*	string	Item category.
name*	string	Commercial name.
specs	object	Technical specifications.
price_eur	number	Reference price.

Errores

HTTP	Código	Cuándo
403	plan_required	Requires a Pro or Enterprise plan.
409	sku_exists	The SKU already exists in your catalogue.

curl -X POST https://api.ciflow.net/api/v1/partner-api/catalog/items \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"sku": "GEN-A-12", "category": "aerotermia", "name": "Bomba de calor 12 kW", "price_eur": 6200}'

Respuesta de ejemplo

{ "sku": "GEN-A-12", "created": true }

Webhooks

HMAC-SHA256-signed push notifications. Subscribe to events to react in real time from your CRM.

Available events

Event	Description
property.created	A property has been registered.
property.enriched	The property enrichment pipeline has finished.
simulation.completed	A simulation has finished.
report.generated	A report has been generated and is available.
device.telemetry_received	A batch of telemetry from a device has been ingested.
device.insight_detected	An insight about a device has been detected.
device.fault_detected	A fault has been detected in a device.
lead.created	A lead has been created (includes auto-prioritised leads).
lead.status_changed	A lead's status has changed.
client.report_ready	A client's accumulated report is ready.

Signature verification (HMAC SHA-256)

Every delivery includes the X-Ciflow-Signature header in the form sha256=…. Always verify the signature with the webhook secret before processing the body:

import hmac, hashlib

def verify(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

POST/webhooks

Register a webhook

Registers a URL ciflow will send events to. The response includes the HMAC secret once: keep it, it is used to verify the X-Ciflow-Signature of every delivery.

Cuerpo de la petición

Campo	Tipo	Descripción
url*	string	Destination HTTPS URL.
events	string[]	List of events to subscribe to. Empty = all.

Errores

HTTP	Código	Cuándo
422	validation_error	Invalid or non-HTTPS URL.

curl -X POST https://api.ciflow.net/api/v1/partner-api/webhooks \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://tu-crm.example.com/hooks/ciflow", "events": ["simulation.completed", "report.generated"]}'

Respuesta de ejemplo

{
  "id": "wh-aa11-...",
  "url": "https://tu-crm.example.com/hooks/ciflow",
  "secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxx",
  "note": "Guarda el secret: firma X-Ciflow-Signature (HMAC-SHA256). No se vuelve a mostrar."
}

GET/webhooks

List webhooks

Returns the webhooks registered in your tenant with their status and last delivery.

Errores

HTTP	Código	Cuándo
401	missing_api_key	Missing or invalid X-API-Key header.

curl -X GET https://api.ciflow.net/api/v1/partner-api/webhooks \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "webhooks": [
    {
      "id": "wh-aa11-...",
      "url": "https://tu-crm.example.com/hooks/ciflow",
      "events": ["simulation.completed"],
      "status": "active",
      "last_delivery_at": "2026-05-18T09:30:00Z"
    }
  ]
}

DELETE/webhooks/{id}

Delete a webhook

Deletes a webhook. ciflow stops sending deliveries to that URL.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Webhook identifier.

Errores

HTTP	Código	Cuándo
404	webhook_not_found	Does not exist or does not belong to your tenant.

curl -X DELETE https://api.ciflow.net/api/v1/partner-api/webhooks/{id} \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{ "deleted": true }

GET/webhooks/{id}/deliveries

Delivery history

Returns the last 50 deliveries of a webhook with response code, number of attempts and status.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Webhook identifier.

Errores

HTTP	Código	Cuándo
404	webhook_not_found	Does not exist or does not belong to your tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/webhooks/{id}/deliveries \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "deliveries": [
    {
      "id": "del-99-...",
      "event": "simulation.completed",
      "status_code": 200,
      "delivered": true,
      "attempts": 1,
      "last_attempt_at": "2026-05-18T09:30:01Z"
    }
  ]
}

SDKs

Official SDKs are in development. Meanwhile, any standard HTTP client works: the API is REST over JSON with header authentication. The examples on this page cover cURL, Python (requests) and Node (fetch).

Changelog

Version	Date	Changes
v1.5	2026-05-12	Equipment telemetry: single and bulk ingestion, insights and anomaly detection.
v1.4	2026-04-03	Accumulated client report (cadastre + consumption + telemetry + simulations).
v1.3	2026-03-06	Webhooks with signed deliveries (HMAC SHA-256) and retries.
v1.2	2026-02-10	Catalogue recommendations with commercial feedback.
v1.1	2026-01-15	Simulator presets and scenario comparison.
v1.0	2025-12-09	Initial release: properties, quick lookup and simulations.

Schemas

Objects reused across the API.

Property

A property registered in ciflow and its enriched data.

Field	Type	Description
property_id	uuid	Unique identifier of the property.
cadastral_reference	string	Cadastral reference (14 or 20 characters).
address	string \| null	Postal address.
municipality	string \| null	Municipality.
province	string \| null	Province.
ccaa	string \| null	Autonomous region.
postcode	string \| null	Postcode.
year_built	integer \| null	Year built.
surface_m2_built	number \| null	Built surface (m²).
surface_m2_useful	number \| null	Usable surface (m²).
n_rooms	integer \| null	Number of rooms.
climate_zone	string \| null	CTE climate zone (e.g. D3).
energy_certificate	object \| null	Energy certificate (see Schema).
ite_fetch_status	string \| null	Status of the ITE query (ok, not_found, error).
ite_data	object \| null	Building inspection certificate data.

EnergyCertificate

Energy Performance Certificate, real or estimated.

Field	Type	Description
rating	string	Rating letter (A–G).
primary_energy_kwh_m2_year	number \| null	Non-renewable primary energy.
co2_kg_m2_year	number \| null	CO₂ emissions.
source	string	registry (official) or estimated (estimate by year/zone).
registry	string \| null	Source autonomous-region registry, if applicable.

Simulation

Result of an energy-improvement scenario.

Field	Type	Description
id	uuid	Identifier of the simulation.
scenario_type	string	heat_pump \| insulation \| pv \| full.
status	string	pending \| completed \| failed.
inputs	object	Input parameters used.
outputs	object \| null	annual_saving_eur, investment_eur, payback_years, co2_reduction_kg_year.
subsidies_applicable	object \| null	Subsidies considered.

Recommendation

Ranking of catalogue solutions for a property.

Field	Type	Description
category	string	Recommended scenario (heat_pump, insulation, pv, hybrid).
ranked_items	array	Ordered list of { catalog_item_id, sku, name, category, score 0-1, reason, manufacturer_boost }.
manufacturer_boost_applied	boolean	Whether the tenant's preferred-manufacturer boost was applied.
summary_text	string	Natural-language summary of the recommendation (AI, with deterministic fallback).
recommended_economics	object	Economics re-priced with the top product's real cost: { investment_eur, annual_savings_eur, payback_years, irr_pct, sku, name, generic_investment_eur }. Null when no simulation is linked.

Device

Equipment installed and registered by the partner.

Field	Type	Description
device_id	uuid	ciflow internal identifier.
external_id	string	The device identifier in your systems.
device_type	string	heat_pump \| pv_inverter \| meter \| sensor.
model	string \| null	Device model.
serial_number	string \| null	Serial number.
property_id	uuid \| null	Property where it is installed.
status	string	active \| inactive \| maintenance \| decommissioned.
last_telemetry_at	datetime \| null	Last telemetry received.
metadata	object	Free data, opaque to ciflow.

TelemetryRecord

A single measurement sent by a device.

Field	Type	Description
ts	datetime	Measurement timestamp (ISO 8601).
metric	string	Metric name (e.g. cop, power, temp_in).
value_numeric	number \| null	Numeric value.
value_string	string \| null	Text value (for non-numeric metrics).
unit	string \| null	Unit (e.g. kW, ratio, °C).

Report

Generated energy report (PDF proxied by the API).

Field	Type	Description
report_id	uuid	Identifier of the report.
status	string	processing \| completed \| failed.
scope	string	property \| client (accumulated report).
file_size_bytes	integer \| null	PDF size.
period_start	date \| null	Period start (accumulated reports).
period_end	date \| null	Period end (accumulated reports).
generated_at	datetime	Generation date.

Lead

Commercial opportunity, possibly auto-prioritised.

Field	Type	Description
lead_id	uuid	Identifier of the lead.
property_id	uuid \| null	Associated property.
status	string	new \| contacted \| won \| lost.
value_estimate_eur	number \| null	Estimated value of the opportunity.
notes	array	Follow-up notes.
next_action_at	datetime \| null	Next scheduled action.

Webhook

Event subscription with signed deliveries.

Field	Type	Description
id	uuid	Identifier of the webhook.
url	string	Destination HTTPS URL.
events	string[]	Subscribed events (empty = all).
status	string	active \| disabled.
last_delivery_at	datetime \| null	Last delivery.

Ready to integrate? Request your API key as an approved partner.

Request partner access