FINANCE API IMPLEMENTATION GUIDE
How to design a duplicate-invoice detection API an automation can trust
A practical architecture for exact and near duplicate invoice controls, explainable evidence, historical baselines, and safe workflow decisions.
Start with more than one duplicate signal
A filename or invoice number alone is not a reliable duplicate key. Vendors resend documents with renamed files, altered spacing, OCR variation, or reused numbers. A useful API evaluates independent signals and keeps them visible in the result.
- Exact source-document hash for byte-identical resubmissions.
- Normalized vendor, invoice number, total, and currency for deterministic business duplicates.
- Vendor, number, amount, and date similarity for review candidates rather than automatic blocks.
Separate exact blocks from near-match review
Exact evidence can justify a BLOCKED result because the system can name the prior invoice and rule. Similarity is different: a high score is a candidate, not proof. Return REVIEW_REQUIRED with the score, basis, matched invoice, and next safe action instead of silently choosing.
Keep thresholds fixed and versioned in the first release. An operator should be able to reconstruct why two invoices matched without consulting a model transcript.
Build the historical baseline safely
Duplicate controls become useful only when they can compare against retained customer history. Import historical invoices as an unbilled baseline, scope every query to the authenticated organization, and avoid emitting workflow webhooks during the import. Preserve stable external references so a reviewer can find the original system record.
- Tenant-filter every candidate query.
- Normalize on ingestion rather than during every search.
- Retain structured audit metadata longer than source documents.
Return a workflow decision, not a fraud claim
Duplicate evidence should stop or review a workflow, but it does not establish intent or fraud. The API boundary should end at structured evidence. A customer-controlled approval or payment system decides what happens next.
REPRESENTATIVE CONTRACT
Asynchronous duplicate analysis
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/invoices
Authorization: Bearer apc_...
Idempotency-Key: inv-demo-1042
Content-Type: application/json
{
"invoice": {
"vendor_name": "Northstar Supply",
"invoice_number": "INV-1042",
"invoice_date": "2026-08-09",
"currency": "USD",
"total": "1250.00"
}
}{
"id": "inv_01...",
"status": "QUEUED",
"decision": null,
"source_type": "STRUCTURED",
"exceptions": []
}IMPLEMENTATION CHECKLIST
Ship the control with its safety boundary intact.
- Use an idempotency key for every intake request.
- Block exact hash and deterministic composite matches.
- Route similarity matches to review.
- Return the matched invoice and rule evidence.
- Never search another customer's history.
- Keep accounting and payment writes outside the control API.
FREQUENTLY ASKED QUESTIONS
Questions workflow builders ask
Should a duplicate score automatically reject an invoice?
Only deterministic exact evidence should block automatically. A similarity score should produce a review candidate with the matching basis and prior invoice.
Does duplicate detection prove fraud?
No. It identifies repeated or similar records and provides evidence for a customer-controlled review process.
How should historical imports be billed?
Treat them as an unbilled baseline rather than new workflow analyses, and suppress normal completion webhooks during the import.