FINANCE API IMPLEMENTATION GUIDE
Invoice validation API: fields, arithmetic, dates, and agent-readable exceptions
Design a synchronous invoice validation step that catches malformed data before duplicate analysis or ERP routing.
Validate the canonical record, not the presentation
A validation API should accept a documented invoice schema regardless of whether the source was a PDF, form, email parser, or EDI message. Keep extraction separate: OCR supplies fields and evidence; validation evaluates the canonical values.
- Required vendor and positive total.
- Three-letter alphabetic currency normalized to uppercase.
- Invoice and due dates with explicit ordering checks.
- Line quantity, unit price, line total, and invoice-total arithmetic.
Make every failure useful to an automation
A 422 response is appropriate when the request cannot match the schema. Business exceptions belong in a successful structured result so the caller can branch on them. Return code, severity, message, evidence, retryability, and a next action for each exception.
- Schema error: correct the request before retrying.
- Business exception: route or repair according to the returned code.
- Service error: preserve the same idempotency key when retrying a stateful call.
Use deterministic arithmetic
Financial arithmetic should use decimal values, documented rounding, and fixed tolerances. Binary floating-point comparisons create false exceptions. When totals do not reconcile, show the supplied invoice total and calculated line total so the workflow does not have to reproduce hidden math.
Place validation before expensive or consequential work
Run synchronous validation before OCR enrichment, duplicate history writes, or ERP preparation when normalized data already exists. A CLEAR validation result means the record passed these checks; it is not approval to pay and does not replace duplicate, matching, or authorization controls.
REPRESENTATIVE CONTRACT
Synchronous validation
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.
POST /v1/invoice-validations
Authorization: Bearer apc_...
Content-Type: application/json
{
"invoice": {
"vendor_name": "Northstar Supply",
"invoice_number": "INV-1042",
"invoice_date": "2026-08-09",
"due_date": "2026-09-08",
"currency": "USD",
"total": "1250.00",
"line_items": [
{
"description": "Office chairs",
"quantity": "10",
"unit_price": "125.00",
"line_total": "1250.00"
}
]
}
}{
"status": "COMPLETED",
"decision": "CLEAR",
"exceptions": [],
"confidence": 1,
"next_action": "Continue through the authorized workflow."
}IMPLEMENTATION CHECKLIST
Ship the control with its safety boundary intact.
- Publish one canonical invoice schema.
- Use decimal arithmetic.
- Separate request errors from business exceptions.
- Return stable codes and evidence.
- Keep validation synchronous and idempotent by nature.
- Do not describe CLEAR as an approval.
FREQUENTLY ASKED QUESTIONS
Questions workflow builders ask
Should invoice validation call an LLM?
Not for deterministic field, date, currency, and arithmetic checks. Fixed rules are cheaper, reproducible, and easier to audit.
What should happen when lines do not equal the total?
Return a named arithmetic exception with both values and direct the workflow to correct or review the invoice.
Is a valid invoice safe to pay?
No. Validation covers record correctness, not duplicates, purchase-order matching, approval authority, or payment authorization.