CUcubee
Studies

Create a savings study

Changed on

Generates the customer-facing savings-study PDF, stores it privately, e-mails it to the recipient (shareable link + the PDF attached), and returns the link. The link points at GET /api/v1/studies/{id}/pdf, which redirects to a short-lived SAS on each visit — the PDF is never a permanently-open public URL (GDPR: expiry + access logs + revocation on delete).

post/api/v1/studies

Request

  • Base URL
    https://api.partner.cubee.cz
  • URL
    https://api.partner.cubee.cz/api/v1/studies
  • Auth
    none required

Headers

X-Cubee-External-Userstring

Optional id of the caller's own end-user this study belongs to. Tag studies with it to list them back later via GET /api/v1/studies. Opaque to Cubee — never send a name or e-mail.

X-Cubee-Cinstring

Cube IT only. Company identification number (IČO) of the company embedding the calculator, which brands the study (logo + contact) as that partner's instead of generic Cubee. Marks the call as an embed: any other token sending it gets 403, and a CIN matching no partner falls back to generic Cubee branding.

Request body

periodTypestring nullable

Type of time period to evaluate — a specific year like "2024", "2025", or the rolling range "12M" (last 12 completed months). Accepted values come from GET /api/v1/reference/periods.

Optional: leave it null and set from + to instead to evaluate an explicit date range. When both from and to are provided this field is ignored. Exactly one of { periodType } or { from + to } must be supplied.

fromstring date nullable

Optional explicit start of the evaluation period (date only, inclusive), e.g. "2025-01-01". Must be set together with to. When both are set, periodType is ignored — this lets you pin the exact window a study was computed over (e.g. a "last 12 months" run) so it can be reproduced later. The range must fall within the available data window (see the 400 response for the allowed bounds).

tostring date nullable

Optional explicit end of the evaluation period (date only, inclusive), e.g. "2025-12-31". Must be set together with from. The whole day is included. A full calendar year (from = Jan 1, to = Dec 31) yields the same result as the matching periodType year.

yearlyConsumptionKWhnumber float

Estimated total annual electricity consumption of the household in kilowatt-hours (kWh).

totalKWpnumber float required

Total installed PV power - kWp.

Constraints: The system currently supports only a single PV array, so this represents the total capacity.

If you need to create custom production profiles, use the CustomProductionConsumptionData property instead.

Response

OK

idstring uuid

The calculation id (also the blob name).

urlstring nullable

Absolute URL of the public broker endpoint that redirects to a short-lived SAS.

emailSentboolean

true if the e-mail was sent; false if e-mail is disabled or sending failed (PDF is still stored and reachable via Url).

Example response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "url": "https://api.partner.cubee.cz/api/v1/studies/3fa85f64-5717-4562-b3fc-2c963f66afa6/pdf",
  "emailSent": true
}

Changes