---
title: "Parse invoice"
method: POST
path: "/v1/billValidation/parseInvoice"
tags: ["Bill Validation", "Invoice Parsing"]
---

# Parse invoice

`POST /v1/billValidation/parseInvoice`

Uploads and processes a UK energy supplier invoice (PDF or images) to extract invoice details, supply points (MPANs/MPRNs), and associated consumption and charge information.

## Response `200`

Invoice successfully parsed

- object
  - `success` boolean
  - `data` ExtractedData — Extracted invoice data. Many fields are optional and depend on what can be extracted from the document. Only 'documentType', 'isStatement', and 'items' are always present.
    - `filePath` string — Generated file path for the invoice
    - `documentType` 'invoice' | 'statement' | 'credit_note' | 'debit_note' — Type of document
    - `isStatement` boolean — Whether the document is a statement
    - `supplierName` string — Name of the supplier
    - `supplierCode` string — Supplier code
    - `customerName` string — Name of the customer
    - `billingAddress` string — Billing address
    - `items` object[] — Array of invoice items
      - `itemType` 'invoice' | 'credit' | 'debit' — Type of invoice item
      - `invoiceNumber` string — Invoice number
      - `invoiceDate` string, date — Invoice date in YYYY-MM-DD format
      - `dueDate` string, date — Due date in YYYY-MM-DD format
      - `netAmount` number — Net amount (before VAT)
      - `vatAmount` number — VAT amount
      - `totalAmount` number — Total amount (including VAT)
      - `supplyPoints` object[] — Array of supply points on this invoice
        - `mpanMprn` string — MPAN (electricity) or MPRN (gas) identifier
        - `supplyType` 'electricity' | 'gas' — Type of supply - 'electricity' for MPAN, 'gas' for MPRN
        - `siteAddress` string — Site address for this supply point
        - `consumption` object — Consumption data
          - `total` number, nullable — Total consumption
          - `unit` string — Unit of consumption (e.g., 'kWh')
          - `day` number, nullable — Day consumption (for dual-rate meters)
          - `night` number, nullable — Night consumption (for dual-rate meters)
          - `reactive` number, nullable — Reactive consumption
          - `apparent` number, nullable — Apparent consumption
        - `charges` object[] — Array of charges for this supply point
          - `category` 'energy' | 'standing' | 'distribution' | 'transmission' | 'environmental' | 'capacity' | 'metering' | 'adjustment' | 'other' — Category of charge
          - `description` string — Description of the charge
          - `quantity` number — Quantity for this charge
          - `unit` string — Unit of quantity. Standardised values: 'kWh' (energy), 'days' (standing charges), 'kVA' (capacity), 'kvarh' (reactive energy), 'kVAh' (apparent energy). Example: 'kWh'
          - `rate` number — Rate value as a number (no currency symbols). Units are standardised: energy charges in p/kWh, standing charges in p/day, CCL in p/kWh, capacity charges in p/kVA/day, reactive power in p/kVArh, apparent power in p/kVAh, distribution/transmission in p/kWh or p/day, metering in p/day or £/month. Example: 21.29 (not '21.29p')
          - `rateUnit` string — Standardised unit of rate. Values: 'p/kWh' (energy, CCL, distribution, transmission), 'p/day' (standing charges, metering), 'p/kVA/day' (capacity charges), 'p/kVArh' (reactive power), 'p/kVAh' (apparent power), 'p/kVA' (capacity without day), '£/month' (metering charges). Example: 'p/kWh'
          - `vatRate` number — VAT rate as a percentage (e.g., 20 for 20%, not 0.2). Always a number between 0 and 100.
          - `netAmount` number — Net amount for this charge
        - `meterReadings` object[] — Array of meter readings
          - `date` string, date — Reading date in YYYY-MM-DD format
          - `type` 'actual' | 'estimated' | 'customer' | 'corrected' — Type of reading
          - `reading` string — Meter reading value
          - `register` string, nullable — Register identifier
          - `consumption` number, nullable — Consumption since last reading
          - `unit` string — Unit of reading (e.g., 'kWh')

## Other responses

- `400` — Bad request - Invalid input
- `401` — Unauthorized - Authentication required
- `500` — Server error
- `4XX` — Client error response

## Changes

- **2025-12-09** `d899129585db` — 35 breaking
  - the response property `data/documentType` became optional for the status `200`
  - the response property `data/isStatement` became optional for the status `200`
  - the response property `data/items` became optional for the status `200`
  - the response property `data/items/items/invoiceDate` became optional for the status `200`
  - …31 more
- **2025-11-17** `868245a1febf` — 1 breaking
  - the `data/items/items/supplyPoints/items/charges/items/rate` response's property type/format changed from `string`/`` to `number`/`` for status `200`
- **2025-11-17** `1ecbbc9bbafb` — 1 breaking, 14 warning, 49 info
  - the `data/items/items/supplyPoints/items/charges/items/rate` response's property type/format changed from `number`/`` to `string`/`` for status `200`
  - removed the optional property `data/items/items/chargeEndDate` from the response with the `200` status
  - removed the optional property `data/items/items/chargeStartDate` from the response with the `200` status
  - removed the optional property `data/items/items/outstandingBalance` from the response with the `200` status
  - …60 more

[Change history](https://skmtc.dev/voltview/apis/voltview-api/changes/v1/billValidation/parseInvoice/post.md)

---

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