Export Schemas

Everything the export produces, in one place. 60 canonical columns across 8 sections, 13 warning codes, and the per-meter / invoice-level scope rules you need to read multi-meter bills correctly. Two download formats — a flat CSV for spreadsheet workflows and an advanced two-sheet Excel workbook that adds per-line charge detail — use identical column names and types, so anything that's true of one is true of the other.

Overview

The export turns each uploaded utility bill PDF into structured data. Every column has a stable canonical name regardless of what the utility happens to call it on the bill — see State-specific identifiers for the alias map. The Field reference below is the single source of truth for both CSV and Excel: identical column names, identical types, identical nullability.

CSV vs Excel — which one to choose

Both downloads come off the same extraction. They differ only in cardinality: the CSV is fixed-width and flat; the Excel workbook adds a second sheet for the variable-cardinality per-line detail (TOU bands, tier rows, supplier splits, individual taxes) that doesn't fit in a flat table.

Sheet 1 of the workbook is a strict superset of the CSV — same column order with two FK columns prepended — so you can ignore Sheet 2 and treat the workbook as a richer CSV if you don't need per-line detail. Jump straight to the Excel workbook section for the sheet-by-sheet schema, or read on for the CSV.

• One row per metered service. A service produces a row only when the bill prints a volume reading for it (a physical meter, an NMI, a recorded usage). Flat-fee services that appear as line items without a meter reading — sewerage on a flat residential rate, parks levies, late fees — do not get their own row; they roll into bill_new_charges only. A single-meter bill produces one row; a two-meter bill produces two rows that share invoice-level columns.
• Dates are ISO 8601 (YYYY-MM-DD).
• Strings are emitted verbatim — utility names, tariff names, addresses are not normalized or abbreviated.
• Numbers are raw values: no commas, no currency symbols, no embedded units. Units live in their own column (e.g. meter_total_unit, currency).
• Units include both US-style (kwh, therms, ccf, gallons, kw) and metric (mj, m3, kl) for Australian and European bills.
• Blank means “not stated on the bill”, not zero. See Sign conventions & nulls.

Row scope & sums

Each column has one of three scopes. The scope is shown as a chip in the field-reference tables below.

Calculations

The numeric fields satisfy two summing identities you can use to validate your own roll-ups.

1. Invoice-level rollup (all row-repeated):

bill_total  =  previous_balance
            −  payments_received
            +  bill_new_charges
            +  late_fee

The same numbers appear on every meter row of a single bill. When the bill shows no prior balance and no in-period payment, bill_total == bill_new_charges.

2. Per-meter to invoice rollup:

bill_new_charges  ≈  sum of meter_total_cost
                  across every row of the same bill

Approximate because invoice-level fees, discounts, rounding, or flat-fee services without their own meter reading land outside any single meter row. A multi-utility municipal bill that mixes a metered electric service with a flat sewerage charge will leave a gap here by design — that case emits MULTI_SERVICE, not COST_MISMATCH. We reserve COST_MISMATCH for a single-service bill where the meter-row total is more than 10% off the invoice's stated new charges — the signal of an actual extraction problem worth spot-checking.

Collapsing to one row per bill. Group the CSV by bill_customer_account + bill_start_date. Keep the first value for row-repeated columns; sum the per-meter ones (meter_total_volume, meter_total_cost).

Field reference

60 columns, in the order they appear in the CSV.

Extraction metadata

Pipeline-level fields about the extraction itself. One value per CSV row.

Grid & market

The delivery utility and the ISO/RTO market that operates the wires. Same on every meter row of one bill.

Identification

The customer plus the specific service point being billed. Varies per meter.

Location

Service address (where the meter is) and billing address (where the bill is sent). Row-repeated.

Billing & service agreement

Customer-level account number plus any per-meter service agreement.

Rate & service class

The tariff that prices the meter, plus the derived service-class classification.

Dates

Statement, billing-period, and due dates. Row-repeated.

Usage, demand & cost

Per-meter consumption and cost, plus the invoice-level adjustment fields that satisfy the summing identities.

State-specific identifier notes

Different jurisdictions print the same canonical concept under different labels. We fold them into a single column so downstream tooling doesn't need to special-case them.

Folded into service_account_number

When point_of_delivery_id is populated

A premise-level identifier that stays stable across customer turnover. Populated only when the bill prints it explicitly (most utilities do not).

Folded into bill_customer_account

Sign conventions & nulls

• Credits and solar feed-in: meter_total_cost is negative. A meter that exported more energy than it consumed will roll in as a negative number — that's intentional, the summing identity above relies on it.
• payments_received is always a positive magnitude. The identity above subtracts it; do not double-negate.
• previous_balance is positive when the prior bill was unpaid, negative when the customer was in credit going in.
• late_fee is positive when present; blank when there was no late fee on this bill.

Null versus zero. A blank cell means the bill did not state that line. Don't treat it as zero — that loses the distinction between “no late fee was charged on this bill” (very common, blank) and “the bill explicitly shows a $0.00 late fee” (rare, value 0). This applies to previous_balance, payments_received, and late_fee in particular.

Warning codes

Codes appear semicolon-joined in the extraction_warnings column. Most are informational, not failures.

Sample CSV

Three rows of synthetic data that exercise every concept above: a single-meter US residential bill and a two-meter Australian bill where solar feed-in shows as a negative meter_total_cost.

Download utilitybillreader-sample-export.csv

Three rows; one row per meter. Long lines wrap horizontally — download to see all 60 columns.

Excel workbook (advanced)

The .xlsx download is the same extraction laid out as a two-sheet workbook so per-charge detail — TOU bands, tier rows, supplier splits on CCA bills, individual taxes — doesn't get flattened away. Available from the dashboard's Excel button (next to CSV) and from the same per-row download menu the CSV uses.

Two sheets, one foreign key

• Sheet 1 — Bills. Same 60-column CSV schema, with two FK columns (extraction_id, meter_index) prepended. One row per metered service, same scope rules as the CSV.
• Sheet 2 — Line items. One row per charge line across every meter on every bill in the workbook, with three FK columns (extraction_id, meter_index, line_index) that link each line back to its meter row on Sheet 1.

Sheet 2 is empty (header row only) on bills where no per-line charge detail was itemized — bill totals still appear on Sheet 1's meter_total_cost. The workbook layout is identical either way, so your tooling doesn't change whether or not a bill carries line detail.

Sheet 1: Bills

Header row layout, left-to-right: the two FK columns, then every column from the Field reference in the same order as the CSV.

Sheet 2: Line items

18 columns. One row per charge line, in the order the line appeared on the bill. Strings come back verbatim (no normalization on name, source_section, or supplier); kind and section are the only normalized fields.

Cost signs follow the CSV convention — credits, rebates, and feed-in lines come back as negative cost. See Sign conventions & nulls.

Joining Sheet 2 back to Sheet 1

Both sheets share the (extraction_id, meter_index) pair. Group Sheet 2 by that pair to roll line items back up to a meter; group by extraction_id alone to roll back up to a bill. The pivot below sums Sheet 2's cost by meter and reconciles it against Sheet 1's meter_total_cost:

// Excel formula on Sheet 1, alongside meter_total_cost:
SUMIFS('Line items'!M:M,
       'Line items'!A:A, A2,    // extraction_id
       'Line items'!B:B, B2)    // meter_index

Sheet 2's cost column is column M; the FK columns are A and B. The sum should equal Sheet 1's meter_total_cost within the floored tolerance described under COST_MISMATCH in Warning codes.

Other common pivots:

• Spend by charge type: pivot cost by kind to split consumption vs supply vs taxes vs credits across a whole portfolio of bills.
• Spend by supplier: pivot by supplier on CCA / community-aggregation bills (PG&E + MCE, SDG&E + Clean Energy Alliance, etc.) to see the delivery / generation split per supplier.
• TOU breakdown: filter kind = consumption and pivot volume + cost by time_window to recover peak / off-peak / shoulder usage that the flat CSV folds into a single meter_total_volume.

Sample template

Same three bills as the Sample CSV above — the single-meter US residential bill and the two-meter Australian bill with solar feed-in — laid out in the workbook format with a populated Sheet 2 so you can see exactly how line items shake out on each.

Download utilitybillreader-sample-export.xlsx

Sheet 1: 3 rows + 2 FK columns + the 60 CSV columns. Sheet 2: 6 line items spread across the three meters.

Email Inbox Forwarding

Forward utility bills as PDF attachments to a unique address on @ bills.utilitybillreader.com and they'll appear on your dashboard the same way uploaded files do. Also recieve a reply email summarising the parsed result and a CSV attached. No browser upload or access steps required.

Workflow

1. Sign up, then open the Email Tokens entry in your profile menu to copy your forwarding address. The default token is created automatically.
2. Forward (or set up auto-forward in your inbox) any utility bill emails with PDF attachments to that address. Multiple PDFs in one email are processed as a batch.
3. Each PDF lands on the dashboard as a row with the email-source badge and a "via email from <sender>" subline — first as queued, then completed within ~30s.
4. Once every PDF in the batch finishes, you receive a single reply email with a per-file summary and a CSV containing the parsed line items, threaded with the original forward so it lands in the same conversation in your inbox.

Forwarding addresses follow the format ubr_eml_<20-char>@bills.utilitybillreader.com. The ubr_eml_ prefix lets you spot the addresses at a glance in your inbox and contact lists.

Multiple addresses per team are supported — create labelled tokens (e.g. AGL gas bills, Retail shops) to route different upstream inboxes without losing context.

Allowed senders — senders must be a team member

We only accept forwards from email addresses that are already on the team that owns the token. Mail from anyone else is silently dropped, and the token's owner receives a one-line notification: "Someone at <sender> tried to forward to your ingest address and we rejected it."

To let a colleague forward to your team's address, add them to your team using their registered email address. Any team member's address then becomes a valid sender for every token on the team.

SPF and DKIM must also pass on the sender's domain — we drop forgeries silently. Forwarding from your own Gmail/Outlook generally passes both; forwarding through an old POP3 server that re-stamps headers may not. If a legitimate forward keeps failing, drop us a note with the sender domain.

Limitations

• PDF attachments only. Any other attachment type is ignored. Inline images, bills embedded as the email body itself, or links to a utility's web portal are not parsed today.
• 40 MB total per inbound message (an AWS SES cap we can't override). Most utility bills are well under 1 MB. Oversized forwards bounce back from SES — the failure isn't visible in your dashboard, so the forwarder will see a bounce notice from their own mail server.
• Quota applies the same as web uploads. Pages consumed by email-forwarded bills draw from your team's monthly page allowance. A forward that would exceed the remaining quota is dropped and we log it but don't currently auto-reply — check the dashboard quota meter if a forward seems to have vanished.
• Forwarder identity is the outer From header. If you forward a thread, we attribute it to the immediate forwarder (you), not the utility that sent the original. The utility name shows up in the parsed data, not in the source attribution.
• One reply per inbound, not per attachment. Forward five PDFs in one email and you get one reply once all five have finished extracting (success or failure). Each PDF still becomes visible on the dashboard the moment its individual extraction completes — you don't need to wait for the reply to see results.

Reply email

Sent from noreply@utilitybillreader.com to the original forwarder, threaded with the inbound message (via In-Reply-To and References headers) so most mail clients attach it to the same conversation. The body is a per-file table with status (parsed / could not parse / duplicate — review), the utility we detected, and a button back to the dashboard.

A CSV named parsed-bills-YYYY-MM-DD.csv is attached when at least one PDF parsed successfully. Its column layout matches the Field reference below — same canonical names as the dashboard's CSV download, the Excel workbook's Bills sheet, and the API's JSON response. (The richer Excel workbook isn't auto-attached to email replies; grab it from the dashboard when you need per-line detail.)

Replies are suppressed when the forwarder's address looks like an automation account (postmaster@, noreply@, mailer-daemon@, etc.) to avoid reply loops.

Rotate or revoke a token

Forwarding addresses are stable but rotatable. If one ends up in the wrong hands — or you'd just rather not keep using a particular upstream inbox — use the Email Ingest Tokens page to:

• Rotate — issues a new active address with the same label and immediately disables the old one. Forwards to the old address are dropped from that moment on.
• Revoke — disables an address without replacing it. Mail to the revoked address is dropped before it reaches your account.

Partner API

A small REST surface for partners: upload a bill, fetch the parsed JSON, list every bill on your account, check your remaining quota. JSON responses use the same canonical column names as the Field reference below — each result carries a rows array (identical to the CSV download and Sheet 1 of the Excel workbook) and a line_items array (identical to Sheet 2), so the API mirrors the full workbook, not just the flat CSV. The API returns JSON only; use the dashboard's CSV / Excel buttons (or these response arrays) to drive your own export.

Authentication

Mint a token from your account's API Tokens page (Profile menu → API Tokens). Send it on every request as a Bearer credential:

Authorization: Bearer <your-token>

Tokens are scoped to a single user account; treat them like passwords. Revoke a token anytime from the same page.

Quota

API uploads draw from the same monthly page quota as the web app — one PDF page counts as one page used. Use GET /api/v1/user to check your remaining pages, or visit the pricing page to compare plans. Quota is decremented when an extraction finishes, not at upload time, but a queued bill counts against your remaining balance to prevent racing.

Bills are visible through the API for as long as your plan's retention window lasts — 90 days on the paid tiers and unlimited on Enterprise. Past that window the source PDF is purged and the bill drops out of both the dashboard's history table and every API response (404 on /bill/{id}, omitted from /bill).

Endpoints

All endpoints live under /api/v1/, require the Authorization header, and speak JSON. The collection vs. single-item distinction is the presence of an {id} path segment — there is no /download suffix and no singular-vs-plural convention to keep straight.

POST /api/v1/bill

Upload one PDF. Returns 202 Accepted with the new extraction id. Use the id with GET /api/v1/bill/{id} to track status and fetch the parsed result.

Request — multipart/form-data with a single file field:

curl -X POST https://utilitybillreader.com/api/v1/bill \
  -H "Authorization: Bearer $TOKEN" \
  -F file=@/path/to/bill.pdf

Response 202:

{
  "id": "0193e3a0-7c3b-7000-8f1a-1234567890ab",
  "status": "queued",
  "source_filename": "bill.pdf",
  "source_page_count": 3,
  "created_at": "2026-05-19T12:34:56+00:00"
}

GET /api/v1/bill/{id}

One endpoint covers status polling and result retrieval. The response shape is identical regardless of state: rows and line_items are both null while status is queued or processing, and become arrays once the extraction reaches a terminal state — rows with one object per meter, line_items with one object per charge line across every meter. Always 200 OK — check status (or just rows !== null), not the HTTP code.

curl https://utilitybillreader.com/api/v1/bill/$ID \
  -H "Authorization: Bearer $TOKEN"

Response (terminal):

{
  "id": "0193e3a0-7c3b-7000-8f1a-1234567890ab",
  "status": "completed",
  "source_filename": "bill.pdf",
  "source_page_count": 3,
  "extraction_confidence": 0.97,
  "warnings": [],
  "error_code": null,
  "error_message": null,
  "created_at": "2026-05-19T12:34:56+00:00",
  "extracted_at": "2026-05-19T12:35:12+00:00",
  "rows": [
    {
      "utility_name": "Southern California Edison",
      "service_account_number": "2-12-345-6789",
      "tariff": "DOMESTIC",
      "meter_total_volume": 412,
      "meter_total_unit": "kwh",
      "meter_total_cost": 78.42,
      "bill_total": 78.42,
      "currency": "USD",
      "customer_name": "LASTNAME, FIRSTNAME",
      "...": "..."
    }
  ],
  "line_items": [
    {
      "extraction_id": "0193e3a0-7c3b-7000-8f1a-1234567890ab",
      "meter_index": 0,
      "line_index": 0,
      "kind": "consumption",
      "section": "delivery",
      "supplier": null,
      "name": "Peak",
      "volume": 180,
      "unit": "kwh",
      "rate": 0.31,
      "rate_unit": "$/kwh",
      "cost": 55.8,
      "time_window": "peak",
      "...": "..."
    }
  ]
}

Every key inside a rows[] object is a CSV column name — see Field reference for the full list, types, scopes, and nullability rules. Every key inside a line_items[] object is a column from the Excel workbook's Line items sheet; the meter_index / line_index FKs join each line back to its rows[] entry (row N is meter_index = N). line_items is an empty array on bills whose charge lines haven't been broken out yet.

GET /api/v1/bill

Paginated list of every bill on your team, newest first. Each entry is the same envelope as the single-id endpoint (rows + line_items); in-flight bills appear in the same list with rows: null and line_items: null.

Query parameters:

• limit — 1 to 100, default 50.
• since — ISO 8601 timestamp; only return bills created on or after this moment.
• cursor — opaque pagination token returned as next_cursor on the previous page. Echo it back to fetch the next page.

curl "https://utilitybillreader.com/api/v1/bill?limit=50&since=2026-05-01T00:00:00Z" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "data": [
    { "id": "...", "status": "completed",  "rows": [ ... ], "line_items": [ ... ] },
    { "id": "...", "status": "processing", "rows": null,     "line_items": null }
  ],
  "next_cursor": "MjAyNi0wNS0xOVQxMjozNDo1NisrMDA6MDAi..."
}

When next_cursor is null, you've reached the end of the list.

GET /api/v1/user

Current user, team, and remaining page quota. Poll this before a bulk upload to confirm you have enough pages.

curl https://utilitybillreader.com/api/v1/user \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "id": "0193e399-0000-7000-8f1a-1234567890ab",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "team": {
    "id": "0193e398-0000-7000-8f1a-1234567890ab",
    "name": "Jane Smith's Team",
    "plan": "professional"
  },
  "remaining_pages": 1487,
  "pages_limit": 1500,
  "pages_used_this_period": 13,
  "period_resets_at": "2026-06-01T00:00:00+00:00"
}

Response shape

Objects inside rows[] are keyed by the same canonical column names the CSV uses. The Field reference below is the single source of truth: it lists every key, its type, its scope (per-meter vs. row-repeated vs. metadata), and whether it can be null.

Objects inside line_items[] are keyed by the same columns as the Excel workbook's Line items sheet. Each line carries extraction_id, meter_index, and line_index FKs: join on meter_index to attach a charge line to its rows[] entry, or sum cost per meter_index to reconcile against that row's meter_total_cost. line_items is an empty array on bills with no itemized charge lines, so treat it as optional detail on top of the always-present rows[].

Conventions carry over from the CSV: dates are ISO 8601, numbers carry no commas or currency symbols (units live in their own column), blanks mean not stated on the bill rather than zero, and credits/solar feed-in show as a negative meter_total_cost. See Sign conventions & nulls for the full set.

Error codes

Errors are returned as { "error": "<message>" } with the HTTP status set accordingly.

No 425 Too Early — an in-flight bill returns 200 with rows: null and line_items: null, not an error.