A utility bill is a customer's monthly electricity statement, uploaded as a PDF or image to a project. Aurora runs Optical Character Recognition (OCR) against the document to extract monthly usage (kWh) and cost values, and uses those to seed the project's load profile and consumption estimates.

Use cases

The Utility Bills API lets you:

• Upload a customer's utility bill to a project from your CRM, sales tool, or document management system.
• Subscribe to a webhook so you know when the bill has been parsed and is ready to fetch.
• List every bill that has ever been uploaded to a project, with fresh presigned download URLs.
• Retrieve a single bill (e.g. to re-display the bill to a customer in your own UI).

Flow

1. Call Run Utility Bill Upload with the bill bytes in the request body and the original filename in the Content-Disposition header. The endpoint synchronously stores the file and returns a job_id plus the new utility_bill_id.
2. Subscribe to the utility_bill_upload_job_completed webhook to be notified when the parse finishes. The webhook fires for bills uploaded by users in Aurora as well, so you also get notified when a sales rep attaches a bill in the in-app UI.
3. On the succeeded webhook, call Retrieve Utility Bill (or List Utility Bills) to get a fresh presigned download URL. Download URLs expire after 24 hours; re-call the endpoint to refresh.

Last-parse-wins semantics

A project can hold multiple utility bills, and all of them are returned by List Utility Bills as historical artifacts. However, only the most recently parsed bill feeds the project's load profile and consumption data. Each new upload replaces the prior bill's contributions on the project.

Because parse jobs run asynchronously and are not strictly FIFO, an earlier upload that finishes parsing after a later upload will become the active bill. If you upload several bills back-to-back, wait for each utility_bill_upload_job_completed webhook (or polled succeeded status) before uploading the next one to keep the active bill predictable.

This matches the behavior of the in-app utility bill upload UI, which only ever displays the most recent upload.

Accepted formats

PDF, JPG, JPEG, PNG, GIF, WEBP. Maximum file size is enforced by the upload endpoint and surfaced as a 422 on rejection.

Webhook

Aurora dispatches the utility_bill_upload_job_completed webhook on every parse completion (success or failure) — for both bills uploaded via this API and bills uploaded by Aurora users in the app. Use it as a "ready to fetch" signal. The payload includes the job_id, utility_bill_id, project_id, and a status of succeeded or failed.