Quickstart - Termina

Extract structured data from an energy bill in three steps. You’ll have clean JSON with usage, charges, tariff rates, and 30+ other fields in under 60 seconds.

Free tier: 50 API credits, no credit card required. Each credit processes one bill page.

1. Get your API key

Sign up at app.termina.io to generate your free API key instantly. No credit card, no approval process. Your key will look like this:

tmn_live_a1b2c3d4e5f6...

Keep your API key private. Do not commit it to version control or expose it in client-side code.

2. Send your first bill

POST an energy bill PDF to the extract endpoint. The API accepts electricity, gas, and LPG bills from any retailer across Australia, NZ, UK, USA, and Canada.

import requests

response = requests.post(
    "https://api.termina.io/v1/extract",
    headers={"X-API-Key": "YOUR_API_KEY"},
    files={"file": open("energy_bill.pdf", "rb")}
)

data = response.json()
print(data)

import fs from "fs";

const form = new FormData();
form.append("file", fs.createReadStream("energy_bill.pdf"));

const response = await fetch("https://api.termina.io/v1/extract", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
  body: form,
});

const data = await response.json();
console.log(data);

curl -X POST https://api.termina.io/v1/extract \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@energy_bill.pdf"

Request details

Parameter	Type	Description
`file`	`multipart/form-data`	The energy bill file. Accepted formats: PDF, JPEG, PNG, TIFF.

The endpoint automatically detects the energy type (electricity, gas, or LPG), the retailer, and the bill layout. No configuration or parameters needed beyond the file itself.

3. Get structured JSON back

The API returns structured data with 30+ fields organised into clear sections. Here’s an example response from an electricity bill:

Example response

{
  "status": "success",
  "bill_type": "elec",
  "retailer": "Origin Energy",
  "account": {
    "account_number": "6102-4471-8823",
    "nmi": "6305012847",
    "customer_name": "Acme Holdings Pty Ltd",
    "supply_address": "123 Collins Street, Melbourne VIC 3000"
  },
  "billing_period": {
    "start": "2026-01-15",
    "end": "2026-04-14",
    "days": 90
  },
  "usage": {
    "total_kwh": 2847.5,
    "peak_kwh": 1423.8,
    "off_peak_kwh": 1138.2,
    "shoulder_kwh": 285.5,
    "demand_kw": 42.0,
    "meter_reads": [
      {
        "meter_id": "E1Q1",
        "previous": 48210,
        "current": 51058,
        "units": "kWh"
      }
    ]
  },
  "charges": [
    {
      "description": "Peak usage",
      "classification": "retail",
      "quantity": 1423.8,
      "unit": "kWh",
      "rate": 0.2860,
      "amount": 407.21,
      "tariff_type": "time_of_use",
      "time_period": "peak"
    },
    {
      "description": "Off-peak usage",
      "classification": "retail",
      "quantity": 1138.2,
      "unit": "kWh",
      "rate": 0.1540,
      "amount": 175.28,
      "tariff_type": "time_of_use",
      "time_period": "off_peak"
    },
    {
      "description": "Shoulder usage",
      "classification": "retail",
      "quantity": 285.5,
      "unit": "kWh",
      "rate": 0.2180,
      "amount": 62.24,
      "tariff_type": "time_of_use",
      "time_period": "shoulder"
    },
    {
      "description": "Supply charge",
      "classification": "retail",
      "quantity": 90,
      "unit": "days",
      "rate": 0.9900,
      "amount": 89.10,
      "tariff_type": "daily"
    },
    {
      "description": "Network access",
      "classification": "network",
      "amount": 38.67
    },
    {
      "description": "GST",
      "classification": "tax",
      "amount": 77.25
    }
  ],
  "totals": {
    "subtotal": 772.50,
    "gst": 77.25,
    "total_due": 849.75,
    "due_date": "2026-05-10"
  },
  "provider": {
    "retailer_name": "Origin Energy",
    "abn": "06 106 643 253",
    "plan_name": "Business Saver Flex"
  },
  "validation": {
    "is_valid": true,
    "validation_issues": [],
    "confidence": 0.98
  }
}

Response structure at a glance

Section	What it contains
`bill_type`	Energy type classification: `elec`, `gas`, or `lpg`
`account`	Account number, NMI/MIRN, customer name, supply address
`billing_period`	Start date, end date, and number of billing days
`usage`	Total consumption (kWh/MJ), peak/off-peak/shoulder breakdowns, demand, meter readings
`charges`	Every line item with classification, quantity, unit rate, tariff type, and time-of-use period
`totals`	Subtotal, GST, total amount due, due date
`provider`	Retailer name, ABN, plan name
`validation`	Whether the bill passed validation, any issues flagged, confidence score

What to do with the data

Now that you’ve extracted your first bill, here are common next steps:

Process bills across multiple sites

Loop through bills for every location and build a consolidated energy cost view.

Feed data into ESG reporting

Use the kWh and MJ usage fields to calculate Scope 2 emissions automatically.

Build it into your own app

Embed the extract endpoint in your product to give your users energy bill intelligence.

Explore the full API reference

See all request parameters, response fields, error codes, and rate limits.

Accessing your data in the dashboard

Every bill you process through the API is also available in your Termina dashboard. You can:

Search and filter across all processed bills by site, retailer, date, or amount
Export to CSV, XLSX, or PDF for reporting, reconciliation, or sharing with your team
Track usage trends and cost anomalies over time across all your sites
Invite team members with role-based permissions so finance, procurement, and sustainability teams can all access the data

Not a developer? You can also upload bills directly through the dashboard - same OCR extraction engine, just drag, drop, and export.

Frequently asked questions

What file formats does the API accept?

The endpoint accepts energy bills as PDF, JPEG, PNG, or TIFF files sent as multipart/form-data under the file field. Both digital PDFs from retailer portals and scanned or photographed paper bills are supported.

How long does extraction take?

Most bills are processed in under 3 seconds. Complex multi-page bills or low-quality scans may take slightly longer. The API responds synchronously — no polling or webhooks required.

Which energy types can the API extract?

Electricity, gas, and LPG bills. The extraction engine covers network charges, retail charges, environmental levies, market charges, and demand charges — with tariff rate steps and time-of-use breakdowns where present on the bill.

Can the API extract time-of-use tariff data?

Yes. Where time-of-use pricing is present on the bill, Termina extracts peak, off-peak, and shoulder rates and consumption separately — including the tariff rate steps and the kWh consumed in each period.

What happens if a bill cannot be fully parsed?

The energy_data field returns null and validation_issues describes what went wrong. Partial extractions return the data that was successfully read along with warnings on uncertain fields — so you always know what you can trust.

How does bill validation work?

Every extraction runs built-in validation that cross-checks the extracted charges against the bill total, verifies billing period dates are consistent, flags unusually high or low usage, and checks that tariff rates fall within expected ranges for the retailer and region. Issues are returned in the validation_issues array.

How do I authenticate API requests?

Include your API key in the X-API-Key request header. You can generate a free key instantly at app.termina.io — no credit card required.

What are the rate limits?

Free tier accounts can process up to 50 bills total. Pro accounts have configurable rate limits based on your plan. The API returns a 429 status code with a Retry-After header if you exceed your limit.

​1. Get your API key

​2. Send your first bill

​Request details

​3. Get structured JSON back

​Response structure at a glance

​What to do with the data

Process bills across multiple sites

Feed data into ESG reporting

Build it into your own app

Explore the full API reference

​Accessing your data in the dashboard

​Frequently asked questions

1. Get your API key

2. Send your first bill

Request details

3. Get structured JSON back

Response structure at a glance

What to do with the data

Accessing your data in the dashboard

Frequently asked questions