Core API

Parsing documents

Upload a document, get back structured JSON.

Parse endpoint

POST/v1/invoices

Send a multipart/form-data request:

curl -X POST https://api.lumiparser.com/v1/invoices \
  -H "Authorization: Bearer inv_live_YOUR_KEY" \
  -F "file=@invoice.pdf" \
  -F "document_type=invoice"

Form fields

Field	Type	Description
file	required	PDF, PNG, JPG, WebP, or GIF. Max 5MB (free) / 25MB (paid).
document_type	optional	`invoice` (default) · `receipt` · `purchase_order` · `bank_statement`

Sync vs async

Sync (file < 1MB)

201 Created

Result returned immediately in the response body.

Async (file ≥ 1MB)

202 Accepted

Returns a pending invoice ID. Poll or use webhooks.

Response format

{
  "id": "inv_a1b2c3d4e5f6g7h8",
  "status": "completed",
  "file_name": "invoice.pdf",
  "parsed": {
    "vendor_name": "Acme Corp",
    "vendor_address": "123 Main St, New York, NY 10001",
    "vendor_email": "billing@acme.com",
    "vendor_phone": "+1 (555) 000-0000",
    "invoice_number": "INV-2024-0042",
    "invoice_date": "2024-01-15",
    "due_date": "2024-02-15",
    "payment_terms": "Net 30",
    "line_items": [
      {
        "description": "Web Development Services",
        "quantity": 10,
        "unit_price": 150.00,
        "total": 1500.00
      }
    ],
    "subtotal": 1500.00,
    "tax_rate": 0.08,
    "tax_amount": 120.00,
    "discount": null,
    "grand_total": 1620.00,
    "currency": "USD",
    "po_number": "PO-2024-007",
    "bank_details": "Chase Bank — Acct: 1234, Routing: 5678"
  },
  "confidence": {
    "vendor_name": 0.99,
    "vendor_address": 0.95,
    "vendor_email": 0.98,
    "invoice_number": 0.98,
    "invoice_date": 0.99,
    "grand_total": 0.97,
    "line_items": 0.94,
    "currency": 0.99
  },
  "created_at": "2024-01-20T10:30:00Z",
  "completed_at": "2024-01-20T10:30:02Z"
}

Confidence scores

Every field returns a score from 0.0 to 1.0:

Score range	Meaning	Recommendation
0.85 – 1.0	High	Auto-process
0.60 – 0.84	Medium	Spot-check before processing
0.0 – 0.59	Low	Manual review required

Polling for async results

For files ≥ 1MB, poll until status is completed or failed:

GET /v1/invoices/:id

We recommend polling every 2–3 seconds. Most documents complete in under 10 seconds. Consider webhooks instead of polling for production workloads.

Listing documents

GET /v1/invoices?page=1&limit=20&status=completed

Returns paginated results with total, page, and limit. Filter by status: pending, processing, completed, failed.