Parse API reference

Technical reference for the POST /v1/parse/receipt endpoint. Convert receipt images and PDFs into structured JSON data.

Endpoint

Parse a receipt or invoice into structured JSON. Deskewing runs automatically for best results.

Method: POST

Path: /v1/parse/receipt

Auth: Bearer token in Authorization: Bearer <API_KEY>

Request body

Send an image (JPEG, PNG, WEBP, HEIC/HEIF) or a PDF. Images are automatically deskewed before processing. The supported formats apply to both fileUrl andfileBase64.

Fields

fileUrl (string, optional) - Public or signed URL to the source image (JPEG, PNG, WEBP, HEIC/HEIF) or PDF.
fileBase64 (string, optional) - Base64-encoded file content. Used if fileUrl is not provided.
Every response includes a requestId for tracing requests through logs.

File type notes

HEIC/HEIF uploads are converted to PNG before OCR (and before deskewing, if deskew runs).

{
  "fileUrl": "https://example.com/deskewed-receipt.jpg"
}

// Or with base64:
{
  "fileBase64": "iVBORw0KGgoAAAANS..."
}

Response

Successful 200 OK response body.

{
  "requestId": "7b4b44b0-34c2-4e65-8b65-6fe7c7d8e1a2",
  "data": {
    "store_id": "STORE_123",
    "store_name": "Example Market",
    "purchase_date": "2025-02-01T12:34:56Z",
    "store_address": "123 Main St, Springfield, IL 62704",
    "store_address_street": "123 Main St",
    "store_address_city": "Springfield",
    "store_address_state": "IL",
    "store_address_zip_code": "62704",
    "total": 42.35,
    "items": [
      {
        "id": "SKU_A",
        "name": "ITEM A",
        "full_name": "ITEM A 12OZ",
        "category": "Groceries",
        "price": 20.0
      },
      {
        "id": "SKU_B",
        "name": "ITEM B",
        "full_name": "ITEM B 2-PACK",
        "category": "Groceries",
        "price": 22.35
      }
    ]
  },
  "extractedText": "RAW OCR TEXT ...",
  "processingMethod": "state_machine_v2",
  "ocrMetadata": {
    "contentType": "application/pdf",
    "languageHints": ["en"],
    "pageCount": 3
  },
  "notes": [],
  "billing": {
    "billablePages": 3
  }
}

The data object contains the extracted receipt details. billing.billablePages shows how many pages were charged. See Credits & Billing for pricing details.