---
title: "Parse contract"
method: POST
path: "/v1/billValidation/parseContract"
tags: ["Bill Validation", "Contract Parsing"]
---

# Parse contract

`POST /v1/billValidation/parseContract`

Upload and process a UK energy supplier contract (PDF or images) to extract contract details, supply points (MPANs/MPRNs), and associated tariff information.

## Response `200`

Contract successfully parsed

- ContractData — Extracted contract data. Many fields are optional and depend on what can be extracted from the document. Only 'customerType' and 'supplyPoints' are always present (supplyPoints may be an empty array).
  - `filePath` string — Generated file path for the contract
  - `customerType` 'domestic' | 'non_domestic' — Customer classification - residential (domestic) or business (non_domestic)
  - `supplierAccountNumber` string — Supplier account number
  - `supplierName` string — Name of the supplier
  - `supplierAddress` string — Supplier's full address
  - `supplierId` string — Internal supplier identifier
  - `supplierCode` string — Supplier code
  - `customerName` string — Name of the customer
  - `billingAddress` string — Address where bills are sent (customer's address)
  - `contractNumber` string — Contract number
  - `contractStartDate` string, date — Contract start date in YYYY-MM-DD format
  - `contractEndDate` string, date — Contract end date in YYYY-MM-DD format
  - `cclRate` number — Climate Change Levy (CCL) rate in pence per kWh (p/kWh). Converted from £/kWh if necessary (e.g., 0.00775 £/kWh becomes 0.775 p/kWh).
  - `isFixedContract` boolean — Whether this is a fixed-rate contract
  - `isMarketRates` boolean — Whether this contract uses market rates
  - `isMicroBusiness` boolean — Whether the customer is classified as a micro business
  - `paymentMethod` string — Payment method (e.g., 'Direct Debit', 'Credit Card')
  - `contractTermMonths` number — Contract term in months
  - `supplyPoints` object[] — Array of supply points in the contract
    - `mpanMprn` string — MPAN (electricity) or MPRN (gas) identifier. MPAN must be exactly 13 digits, MPRN must be 6-10 digits
    - `supplyType` 'electricity' | 'gas' — Type of supply - 'electricity' for MPAN, 'gas' for MPRN
    - `meterSerialNumber` string — Meter serial number
    - `siteName` string — Name of the site
    - `siteAddress` string — Address of the site
    - `tariffName` string — Full name of the tariff
    - `isNonContractedRate` boolean — True if rates are out of contract or deemed rates
    - `standingCharge` number — Standing charge in pence per day (p/day). Always normalised to p/day regardless of how it appears on the contract.
    - `standingChargeType` string — Standing charge type. Standardised to 'p/day'.
    - `unitRate` number — Single unit rate in pence per kWh (p/kWh). Always a number (use for single-rate meters only).
    - `dayUnitRate` number — Day unit rate in pence per kWh (p/kWh). Always a number (use for dual-rate meters).
    - `nightUnitRate` number — Night unit rate in pence per kWh (p/kWh). Always a number (use for dual-rate meters).
    - `estimatedAnnualConsumption` number — Estimated annual consumption in kWh
    - `previous12MonthsConsumption` number — Previous 12 months consumption in kWh
    - `maximumImportCapacity` number — Maximum import capacity in kVA (electricity only)
    - `capacityRate` number — Capacity charge rate in pence per kVA per day (p/kVA/day). Always a number (electricity only).
    - `directDebitDiscount` number — Direct debit discount percentage
    - `brokerName` string — Name of the energy broker
    - `brokerUplift` number — Broker uplift in pence per kWh
    - `vatRate` number — VAT rate percentage

## Other responses

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

## Changes

- **2025-12-09** `d899129585db` — 10 breaking
  - the response property `customerType` became optional for the status `200`
  - the response property `error` became optional for the status `400`
  - the response property `error` became optional for the status `401`
  - the response property `error` became optional for the status `500`
  - …6 more
- **2025-11-17** `868245a1febf` — 4 info
  - added the optional property `supplierAddress` to the response with the `200` status
  - added the optional property `supplyPoints/items/isNonContractedRate` to the response with the `200` status
  - added the optional property `supplyPoints/items/previous12MonthsConsumption` to the response with the `200` status
  - added the optional property `supplyPoints/items/tariffName` to the response with the `200` status
- **2025-11-17** `1ecbbc9bbafb` — 4 warning, 12 info
  - removed the optional property `supplierAddress` from the response with the `200` status
  - removed the optional property `supplyPoints/items/isNonContractedRate` from the response with the `200` status
  - removed the optional property `supplyPoints/items/previous12MonthsConsumption` from the response with the `200` status
  - removed the optional property `supplyPoints/items/tariffName` from the response with the `200` status
  - …12 more

[Change history](https://skmtc.dev/voltview/apis/voltview-api/changes/v1/billValidation/parseContract/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)