# Utility Bill Parsing API Upload utility bills, create extraction jobs, inspect source-linked results, and send completion events to your systems. ## Workflow 1. **Create an upload intent** — Receive a signed upload URL and source document ID. 2. **Upload and finalize** — Send the file to the signed URL, then finalize the source document. 3. **Create a parse job** — Submit the source document ID with document_type set to utility_bill. 4. **Read the result** — Poll the job or receive a signed webhook when processing finishes. ## Best fit - Server-side utility bill ingestion and extraction - Asynchronous jobs with polling or signed webhooks - Organization-scoped records and idempotent retries ## Integration limits - Keep API keys on the server; do not expose them in browsers - Clients must handle asynchronous terminal states and retries - Validate required field coverage on your utility bill schema ## Authentication - API key: `X-API-Key: pp_live_*` or `X-API-Key: pp_test_*`. - JWT: `Authorization: Bearer ` from Parsepoint ID. - Organization scope: `X-Organization-ID: `. - Base URL: `https://api.app-parsepoint.com` ## OpenAPI Schema [OpenAPI Schema](https://api.app-parsepoint.com/v1/schema/) — Canonical endpoint definitions for code generation, integration checks, and agent tooling. ## Upload and parse a utility bill Use an idempotency key on upload and parse requests so a retry returns the existing resource instead of creating a duplicate. ```bash # 1. Request a signed upload URL curl -X POST 'https://api.app-parsepoint.com/v1/document-parse/source-documents/upload-intents/' \ -H 'X-API-Key: pp_live_' \ -H 'X-Organization-ID: ' \ -H 'Content-Type: application/json' \ -d '{ "original_filename": "utility-bill.pdf", "content_type": "application/pdf", "size_bytes": 2048, "idempotency_key": "upload-2026-001" }' # 2. Upload the file to the returned upload.url curl -X PUT '' --data-binary '@utility-bill.pdf' # 3. Finalize the returned source_document.id curl -X POST 'https://api.app-parsepoint.com/v1/document-parse/source-documents//finalize/' \ -H 'X-API-Key: pp_live_' \ -H 'X-Organization-ID: ' \ -H 'Content-Type: application/json' \ -d '{"size_bytes": 2048, "page_count": 1}' # 4. Create an extraction job curl -X POST 'https://api.app-parsepoint.com/v1/document-parse/jobs/' \ -H 'X-API-Key: pp_live_' \ -H 'X-Organization-ID: ' \ -H 'Content-Type: application/json' \ -d '{ "source_document_id": "", "document_type": "utility_bill", "requested_via": "api", "idempotency_key": "parse-2026-001" }' ``` ## Poll the extraction job ```bash curl 'https://api.app-parsepoint.com/v1/document-parse/jobs//' \ -H 'X-API-Key: pp_live_' \ -H 'X-Organization-ID: ' ``` Job states: A job moves through `created`, `queued`, `running`, and a terminal `succeeded`, `failed`, or `canceled` state. Processing stages identify ingest, OCR, layout, template selection, extraction, post-processing, and completion. ## Utility bill result Illustrative values using the production response fields. ```json { "id": "", "document_type": "utility_bill", "status": "succeeded", "stage": "complete", "result_artifact": { "status": "succeeded", "normalized_output": { "vendor_name": { "value": "Acme Power", "confidence": 0.94 }, "account_number": { "value": "ACC-1", "confidence": 0.91 }, "overall_total_invoice_amount": { "value": "$42.00", "confidence": 0.90 }, "electricity": { "invoice_total": { "value": "42.00", "confidence": 0.93 }, "native_usage": { "value": "100", "confidence": 0.92 }, "native_uom": { "value": "kWh", "confidence": 0.92 }, "usage_start_date": { "value": "2025-01-01", "confidence": 0.90 }, "usage_end_date": { "value": "2025-01-31", "confidence": 0.90 }, "meter_number": { "value": "MTR-1", "confidence": 0.91 } } }, "source_refs": { "vendor_name": { "page": 1 } }, "confidence_summary": { "vendor_name": 0.94 }, "diagnostics": { "pages_parsed": 1 } } } ``` ## Utility-specific output A utility bill schema can include provider and account identity, service dates, meter numbers, usage, native units, demand, invoice totals, and charge details. Extracted values can include confidence and source references. Treat confidence as a review signal, not as measured field-level accuracy. Use `normalized_output` for downstream data, `source_refs` for traceability, `confidence_summary` for review routing, and `diagnostics` when investigating a parse. ## Validation and errors ```http HTTP/1.1 400 Bad Request { "source_document_id": ["This field is required."], "document_type": ["This field is required."], "requested_via": ["This field is required."] } ``` Expect `400` for invalid input, `401` for missing or invalid credentials, `403` for insufficient organization access, and `404` for a job outside the active organization or an unknown job ID. ## Completion webhooks Organization admins can subscribe an HTTPS endpoint to queued, running, succeeded, or failed extraction events. The creation response returns the signing secret once. ```bash curl -X POST 'https://api.app-parsepoint.com/v1/document-parse/integrations/webhooks/endpoints/' \ -H 'Authorization: Bearer ' \ -H 'X-Organization-ID: ' \ -H 'Content-Type: application/json' \ -d '{ "name": "Utility extraction results", "target_url": "https://example.com/webhooks/parsepoint", "subscribed_events": [ "document_parse.extraction_job.succeeded", "document_parse.extraction_job.failed" ] }' ``` Verify `X-Parsepoint-Signature` over the exact request body using HMAC-SHA256 and the value `${timestamp}.${payload}`. Use `X-Parsepoint-Event-ID` to make the consumer idempotent. Parsepoint does not follow webhook redirects. ## Evaluate Parsepoint - [Contact us](https://www.parsepoint.com/demo) - [Pricing](https://www.parsepoint.com/pricing) - [Security](https://www.parsepoint.com/security) - [Customer Stories](https://www.parsepoint.com/customer-stories) - [Utility Bill Parsing](https://www.parsepoint.com/solutions/utility-bill-parsing-energy-cost-analytics)