Utility Bill Parsing API

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 <jwt> from Parsepoint ID.
• Organization scope: X-Organization-ID: <company_id>.
• Base URL: https://api.app-parsepoint.com

OpenAPI Schema

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.

# 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_<key>' \
  -H 'X-Organization-ID: <company_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 '<upload.url>' --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/<source_document_id>/finalize/' \
  -H 'X-API-Key: pp_live_<key>' \
  -H 'X-Organization-ID: <company_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_<key>' \
  -H 'X-Organization-ID: <company_id>' \
  -H 'Content-Type: application/json' \
  -d '{
    "source_document_id": "<source_document_id>",
    "document_type": "utility_bill",
    "requested_via": "api",
    "idempotency_key": "parse-2026-001"
  }'

Poll the extraction job

curl 'https://api.app-parsepoint.com/v1/document-parse/jobs/<job_id>/' \
  -H 'X-API-Key: pp_live_<key>' \
  -H 'X-Organization-ID: <company_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.

{
  "id": "<job_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/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.

curl -X POST 'https://api.app-parsepoint.com/v1/document-parse/integrations/webhooks/endpoints/' \
  -H 'Authorization: Bearer <jwt>' \
  -H 'X-Organization-ID: <company_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.