Three API products

Standardised APIs for three regulated markets

ClauseHub provides three intermediary API products — Energy, Telecoms, and Banking — each standardising a different mandated disclosure format into a uniform, programmatic interface. Suppliers publish their data, consumers retrieve it. All data follows the JSON:API specification.

Product suite

One disclosure format per API, standardised end to end

Each API targets a specific UK regulator's mandated disclosure document and transforms it into a queryable, versioned data layer.

Live

Energy API

Standardises Ofgem Tariff Information Labels (SLC 31). Unit rates, standing charges, exit fees, contract terms, payment methods, and PES region breakdowns.

RegulatorOfgem
DisclosureTariff Information Label
Market size73+ active suppliers
Regions14 DNO + 13 LDZ
Endpoints47
Suppliers: British Gas, Octopus, EDF, E.ON, OVO, Scottish Power
Try it
Planned

Telecoms API

Standardises Ofcom Contract Summaries (General Condition C1). SIM-only, broadband, mobile bundles, mid-contract price rises, early termination fees. National pricing — no regional variation.

RegulatorOfcom
DisclosureContract Summary (5 sections)
Market size~15 providers = ~90% retail
RegionsNational (no variation)
StatusScraping complete
Providers: Vodafone, EE, O2, Three, Sky, BT, Virgin Media
Try it
Planned

Banking API

Standardises FCA Summary Boxes (BCOBS 2 Annex 1R) and Fee Information Documents. Savings accounts, current accounts, cash ISAs, overdraft terms, and APR disclosures. Fills the gap Open Banking does not cover.

RegulatorFCA
DisclosureSummary Box / FID / KFD
Market size250+ banks & building societies
GapOpen Banking covers transactions, not products
StatusSchema designed
Banks: Lloyds, NatWest, Barclays, HSBC, Santander, Monzo, Starling
Try it
Energy API — Data model

Standardised schema with immutable versioning

The Energy API data model. Every resource uses immutable versioning. Updates create new rows. Deletes create archived versions. No data is ever physically deleted.

Supplier
suppliers
resource_idUUID
namestr (1-140)
versionint
statusactive | archived
created_atdatetime
Tariff
tariffs
supplier_idUUID → supplier
client_tariff_idstr
namestr | null
consumable_rangeGas | Electricity | Dual
versionint
Consumable
tariff_consumable
typeGas | Electricity
valuedecimal (unit rate)
price_unite.g. "pence"
consumption_unite.g. "kWh"
standing_chargedecimal / period
Contract
tariff_contract
typeFixed | Variable
payment_methodenum (4 types)
price_guaranteeddatetime | null
tariff_ends_ondatetime | null
Exit Fee
tariff_exit_fee
contract_idUUID → contract
valuedecimal
unite.g. "GBP"
Region
regions
pes_codestr (PES code)
area_namestr
versionint
statusactive | archived

The following features are demonstrated using the Energy API. The same patterns — JSON:API envelope, immutable versioning, role-based auth — will apply to the Telecoms and Banking APIs.

JSON:API specification

Consistent format, predictable interface

All requests and responses use application/vnd.api+json. Uniform envelope, predictable URL structure, consistent error format across all 47 endpoints.

Cursor-based pagination via links.next / links.prev
Structured error envelope with source pointer
Idempotency keys on all write endpoints
OpenAPI 3.0 spec with rich descriptions and examples
JSON:API response envelope
{
"links": {
"self": "/suppliers",
"next": "/suppliers?page[after]=..."
},
"data": [{
"type": "suppliers",
"id": "550e8400-...",
"attributes": {
"name": "British Gas",
"version": 3,
"status": "active"
}
}]
}
Immutable versioning

Every change creates a new record

Updates insert new rows with an incremented version number. Deletes create a final row with status: archived. No data is ever physically deleted. Full audit trail via version endpoints.

Complete version history per resource
Auditable: every version records created_by and created_at
Regulators can query any historical state
GET /tariffs/recent?modifiedSince= for change feeds
version history
Version Name Status
v3 Flexible Oct 2025 active
v2 Flexible Sep 2025 superseded
v1 Flexible Aug 2025 superseded
Search & discovery

Find tariffs by any dimension

The search endpoint filters tariffs by tariff type, fuel type, payment method, and region. The recent endpoint returns tariffs modified since a given timestamp — ideal for building change feeds and sync pipelines.

GET /tariffs/search?region=east_england&fuelType=dual
GET /tariffs/recent?modifiedSince=2026-03-01T00:00:00Z
GET /schema returns full OpenAPI spec for agent discovery
Bulk create/update: up to 100 tariffs per request
GET /tariffs/search
Supplier Tariff Fuel Unit rate
British Gas Price Cap Q1 Dual 24.5p
Octopus Flexible Oct 2025 Dual 22.4p
EDF Simply Fixed Elec 21.8p
Authentication & roles

Role-based access via Supabase JWT

Three roles control who can read, write, and search. Suppliers can only modify their own data — the supplier_id is derived from the JWT, not user input.

Admin
Full CRUD across all resources. Creates suppliers, manages lookup tables.
Full CRUD on all resources
Create/manage lookup tables
Read all version histories
Rate limit: 120 req/min
Supplier
Read all suppliers. Full CRUD on own supplier record and tariffs only.
CRUD own tariffs (single + bulk)
Read all suppliers & lookup tables
Search & read own versions
Rate limit: 60 req/min
Consumer
Read-only access to all suppliers, tariffs, lookup tables, and version histories.
Read all suppliers & tariffs
Search & filter tariffs
Read all version histories
Rate limit: 120 req/min
API example

Query tariffs in one request

All endpoints return application/vnd.api+json. Client libraries auto-generated for Python and TypeScript.

HTTP
Python
TypeScript
# Search tariffs by region and fuel type
GET /v1/tariffs/search?region=east_england&fuelType=dual HTTP/1.1
Host:          api.clausehub.co.uk
Authorization: Bearer <supabase-jwt>
Accept:        application/vnd.api+json

# 200 OK
{
  "links": {
    "self": "/tariffs/search?region=east_england&fuelType=dual",
    "next": "/tariffs/search?...&page[after]=t_48f2a9b1"
  },
  "data": [
    {
      "type": "tariffs",
      "id": "t_48f2a9b1",
      "attributes": {
        "name": "Flexible Oct 2025",
        "consumableRange": "Dual",
        "version": 3,
        "status": "active",
        "createdAt": "2026-03-15T10:00:00Z"
      }
    }
  ]
}
Get started

Start with the Energy API — more markets coming

The Energy API is live now. Telecoms and Banking APIs are in development. Authenticate via Supabase JWT. Full OpenAPI spec at GET /schema.

Get API Key View Documentation