API Documentation

The Utility Bill Extractor API converts utility bills into structured rows programmatically — POST a file, get clean JSON back. Use it to wire conversion into your own scripts, workflows, or product.

Authentication

Every request needs your personal API key in the Authorization header. Find and manage it in Settings. API access requires an active Pro subscription (or conversion credits). Keep your key secret.

Authorization: Bearer YOUR_API_KEY

Convert a document

POST https://utilitybillextractor.com/api/v1/convert

Send a file as multipart form-data (field name file), or as JSON with a base64 string. Accepts PDF, PNG, JPG, WebP up to 20 MB. Rate limit: 30 requests/minute, 1,000/day.

cURL

curl -X POST https://utilitybillextractor.com/api/v1/convert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@your-utility-bill.pdf"

Python

import requests

res = requests.post(
    "https://utilitybillextractor.com/api/v1/convert",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    files={"file": open("your-utility-bill.pdf", "rb")},
)
data = res.json()
print(data["rowCount"], "rows")
for row in data["rows"]:
    print(row)

JavaScript (Node)

const form = new FormData();
form.append("file", new Blob([fileBuffer]), "document.pdf");

const res = await fetch("https://utilitybillextractor.com/api/v1/convert", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_KEY" },
  body: form,
});
const data = await res.json();
console.log(data.rows);

JSON body (base64)

curl -X POST https://utilitybillextractor.com/api/v1/convert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_base64": "<BASE64>", "filename": "doc.pdf", "media_type": "application/pdf"}'

Response

A JSON object with the extracted rows and the column schema for this converter:

{
  "filename": "utility-bill.pdf",
  "mode": "text",
  "rowCount": 2,
  "columns": [
    {
      "key": "account_number",
      "label": "Account #"
    },
    {
      "key": "meter_number",
      "label": "Meter #"
    },
    {
      "key": "provider",
      "label": "Provider"
    }
  ],
  "rows": [
    {
      "account_number": "…",
      "meter_number": "…",
      "provider": "…"
    },
    {
      "account_number": "…",
      "meter_number": "…",
      "provider": "…"
    }
  ]
}

Errors

  • 401 — missing or invalid API key
  • 402 — no active Pro subscription or credits
  • 429 — rate limit exceeded
  • 400 / 413 — bad request or file too large (20 MB max)

Need higher limits or a bespoke integration? Get in touch.