---
title: "Analyze an uploaded energy invoice"
method: POST
path: "/v1/invoices/analyze"
tags: ["Intake"]
---

# Analyze an uploaded energy invoice

`POST /v1/invoices/analyze`

Accepts a single energy-invoice PDF (multipart/form-data, field 'file'), validates it is a genuine energy invoice, extracts its structured figures (per-energy-type consumption, injection, billed cost, billing period, merchant, EAN), and — when annualize=true — also returns figures rescaled to a full year. A readable PDF that is not an energy invoice returns 200 with status 'rejected'. Nothing is stored: the consumer owns any persistence. Each non-2xx response is an RFC 7807 Problem whose `type` says exactly what went wrong — see the individual error responses below.

## Query parameters

- `annualize` string

## Response `200`

Default Response

- union — Invoice analysis result. `rejected` = a readable PDF that is not an energy invoice (no extraction was run). `analyzed` = validated and extracted, with an optional annualised block.
  - object
    - `status` 'rejected', required
    - `validation` object, required
      - `isEnergyInvoice` boolean, required
      - `invoiceType` 'ADVANCE_INVOICE' | 'MONTHLY_SETTLEMENT' | 'YEARLY_SETTLEMENT', nullable, required — Invoice classification. Settlement invoices reconcile real consumption; an advance invoice (voorschot) bills a flat amount with no meter readings.
      - `merchant` string, nullable, required — Energy merchant as read from the invoice, or null.
      - `electricityPeriod` object, nullable, required — Billing period for one energy type. Returned so the consumer can decide whether it is long enough for their purpose — the API does not judge sufficiency.
        - `startDate` string, nullable, required — ISO date (YYYY-MM-DD) or null.
        - `endDate` string, nullable, required — ISO date (YYYY-MM-DD) or null.
        - `daysInPeriod` number, nullable, required — Day span of the period, or null when the dates are unknown.
      - `gasPeriod` object, nullable, required — Billing period for one energy type. Returned so the consumer can decide whether it is long enough for their purpose — the API does not judge sufficiency.
        - `startDate` string, nullable, required — ISO date (YYYY-MM-DD) or null.
        - `endDate` string, nullable, required — ISO date (YYYY-MM-DD) or null.
        - `daysInPeriod` number, nullable, required — Day span of the period, or null when the dates are unknown.
      - `hasExclusiveNightMeter` boolean, required — True if the invoice uses an exclusive night meter (exclusief nachtmeter) — a metering structure not yet supported by Simulation.
      - `confidence` number, required — Validation confidence (0–1).
      - `reason` string, required — Human-readable explanation of the verdict.
  - object
    - `status` 'analyzed', required
    - `validation` object, required
      - `isEnergyInvoice` boolean, required
      - `invoiceType` 'ADVANCE_INVOICE' | 'MONTHLY_SETTLEMENT' | 'YEARLY_SETTLEMENT', nullable, required — Invoice classification. Settlement invoices reconcile real consumption; an advance invoice (voorschot) bills a flat amount with no meter readings.
      - `merchant` string, nullable, required — Energy merchant as read from the invoice, or null.
      - `electricityPeriod` object, nullable, required — Billing period for one energy type. Returned so the consumer can decide whether it is long enough for their purpose — the API does not judge sufficiency.
        - `startDate` string, nullable, required — ISO date (YYYY-MM-DD) or null.
        - `endDate` string, nullable, required — ISO date (YYYY-MM-DD) or null.
        - `daysInPeriod` number, nullable, required — Day span of the period, or null when the dates are unknown.
      - `gasPeriod` object, nullable, required — Billing period for one energy type. Returned so the consumer can decide whether it is long enough for their purpose — the API does not judge sufficiency.
        - `startDate` string, nullable, required — ISO date (YYYY-MM-DD) or null.
        - `endDate` string, nullable, required — ISO date (YYYY-MM-DD) or null.
        - `daysInPeriod` number, nullable, required — Day span of the period, or null when the dates are unknown.
      - `hasExclusiveNightMeter` boolean, required — True if the invoice uses an exclusive night meter (exclusief nachtmeter) — a metering structure not yet supported by Simulation.
      - `confidence` number, required — Validation confidence (0–1).
      - `reason` string, required — Human-readable explanation of the verdict.
    - `extraction` object, required
      - `merchant` string, nullable, required — Energy merchant name (listed merchant or free text).
      - `customer` object, required
        - `postalCode` string, nullable, required
        - `city` string, nullable, required
      - `electricity` object, nullable, required
        - `ean` string, nullable, required
        - `tariffType` 'enkelvoudig' | 'tweevoudig' | 'nachtmeter', nullable, required
        - `priceModel` 'FIXED' | 'VARIABLE' | 'DYNAMIC', nullable, required
        - `period` object, required — Billing period for one energy type. Returned so the consumer can decide whether it is long enough for their purpose — the API does not judge sufficiency.
          - `startDate` string, nullable, required — ISO date (YYYY-MM-DD) or null.
          - `endDate` string, nullable, required — ISO date (YYYY-MM-DD) or null.
          - `daysInPeriod` number, nullable, required — Day span of the period, or null when the dates are unknown.
        - `consumptionTotalKwh` number, nullable, required
        - `consumptionDayKwh` number, nullable, required
        - `consumptionNightKwh` number, nullable, required
        - `injectionTotalKwh` number, nullable, required
        - `hasSolarPanels` boolean, nullable, required
        - `cost` object, required
          - `value` object, required
            - `exclVat` number, nullable, required — Amount excluding VAT. Null when not present on the invoice.
          - `unit` 'EUR', required
      - `gas` object, nullable, required
        - `ean` string, nullable, required
        - `priceModel` 'FIXED' | 'VARIABLE' | 'DYNAMIC', nullable, required
        - `period` object, required — Billing period for one energy type. Returned so the consumer can decide whether it is long enough for their purpose — the API does not judge sufficiency.
          - `startDate` string, nullable, required — ISO date (YYYY-MM-DD) or null.
          - `endDate` string, nullable, required — ISO date (YYYY-MM-DD) or null.
          - `daysInPeriod` number, nullable, required — Day span of the period, or null when the dates are unknown.
        - `consumptionTotalKwh` number, nullable, required
        - `cost` object, required
          - `value` object, required
            - `exclVat` number, nullable, required — Amount excluding VAT. Null when not present on the invoice.
          - `unit` 'EUR', required
      - `confidence` number, required — Overall extraction confidence (0–1).
      - `requiresReview` boolean, required — True when the extraction flagged itself for human review.
    - `annualised` object, nullable, required — Figures rescaled to a full year (365 days), per energy type, using the simulate endpoint's field names so they can feed POST /v1/products/{productId}/versions/{versionId}/simulate directly.
      - `electricity` object, nullable, required
        - `daysInPeriod` number, nullable, required
        - `periodReliable` boolean, required
        - `advisory` string, nullable, required — Set (non-null) only when the period is too short to annualise reliably; explains why. The figures are still provided.
        - `totalConsumption` number, nullable, required
        - `dayConsumption` number, nullable, required
        - `nightConsumption` number, nullable, required
        - `injection` number, nullable, required
        - `cost` object, required
          - `value` object, required
            - `exclVat` number, nullable, required — Amount excluding VAT. Null when not present on the invoice.
          - `unit` 'EUR', required
      - `gas` object, nullable, required
        - `daysInPeriod` number, nullable, required
        - `periodReliable` boolean, required
        - `advisory` string, nullable, required — Set (non-null) only when the period is too short to annualise reliably; explains why. The figures are still provided.
        - `totalConsumption` number, nullable, required
        - `cost` object, required
          - `value` object, required
            - `exclVat` number, nullable, required — Amount excluding VAT. Null when not present on the invoice.
          - `unit` 'EUR', required

## Other responses

- `400` — Default Response
- `413` — Default Response
- `415` — Default Response
- `422` — Default Response
- `502` — Default Response

---

[API](https://skmtc.dev/vwala/apis/energy-platform-api.md) · [All operations](https://skmtc.dev/vwala/apis/energy-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/vwala/energy-platform-api/revisions/b2511b6c1cfa/schema)