FINANCE API IMPLEMENTATION GUIDE
Invoice OCR API for agents: evidence, confidence, and asynchronous document handling
A production pattern for private invoice uploads, traditional OCR, canonical fields, confidence, and page-level evidence.
Treat document intake as an asynchronous job
Invoice PDFs and images vary in page count, size, and OCR time. Return an upload URL, accept the resulting upload ID with an idempotency key, and expose QUEUED, PROCESSING, COMPLETED, and FAILED states. Do not hold a normal HTTP request open for a multi-stage document job.
- One document per upload.
- Short-lived, single-object presigned URLs.
- Strict content type, size, and file-signature checks.
- A terminal failure with a stable extraction error code.
Store evidence beside every extracted value
An agent needs more than a field value. Preserve the OCR confidence, page number, bounding location, and original normalized evidence so a reviewer can inspect where the value came from. Missing fields should remain missing; do not synthesize an invoice number or total to make the schema look complete.
Separate source-document retention from audit retention
Source documents often contain sensitive commercial data and should expire according to the organization's configured retention. Structured fields, exception codes, decisions, and audit events may need a longer retention period for workflow traceability. Deletion workers should remove expired objects without deleting the retained audit record.
- Private object storage by default.
- Configurable document deletion window.
- Short-lived authenticated download links.
- No document content in routine webhook payloads.
Use low confidence as a routing signal
Confidence is not a cosmetic score. Define a fixed threshold for review, name the low-confidence fields, and return their source locations. Downstream automation can continue only when its own policy accepts the evidence.
REPRESENTATIVE CONTRACT
Invoice extraction result
The values below are synthetic. Use a tenant-scoped key stored as a secret, and evaluate the documented status, decision, evidence, and next action before continuing a workflow.
GET /v1/invoices/inv_01.../extraction
Authorization: Bearer apc_...{
"invoice_id": "inv_01...",
"status": "COMPLETED",
"fields": {
"vendor_name": "Northstar Supply",
"invoice_number": "INV-1042",
"currency": "USD",
"total": "1250.00"
},
"confidence": 0.97,
"evidence": {
"pages": [
1
]
},
"next_action": "Use the canonical fields in downstream controls."
}IMPLEMENTATION CHECKLIST
Ship the control with its safety boundary intact.
- Use constrained private uploads.
- Verify the actual file signature.
- Model processing as a job.
- Preserve field confidence and page evidence.
- Never invent missing values.
- Expire source objects independently from audit metadata.
FREQUENTLY ASKED QUESTIONS
Questions workflow builders ask
Why not return OCR synchronously?
Document size and OCR latency are variable. An asynchronous job gives callers stable retries, progress states, and explicit terminal failures.
Should low-confidence fields be omitted?
Return the observed candidate with confidence and location when available, then add a named review exception. Do not silently present it as certain.
Does OCR validation detect duplicates?
No. OCR extracts evidence. Duplicate detection is a separate comparison step over normalized fields and document hashes.