invoice_anomaly_check
Detect duplicate, inconsistent, unusual or potentially fraudulent invoices before payment using arithmetic, supplier-history, purchase-order and payment-detail checks. Returns a 0–100 risk score, a risk level, an advisory decision (continue / review / hold) and machine-readable anomalies (e.g. DUPLICATE_INVOICE, POSSIBLE_DUPLICATE, BANK_ACCOUNT_CHANGED, PO_AMOUNT_EXCEEDED, SPLIT_INVOICE_PATTERN, SUBTOTAL_MISMATCH), each with severity, confidence and structured evidence. Works on a single invoice (standalone) or with optional historical invoices, supplier profile, purchase order, contract, approval threshold and payment history (context-aware). Deterministic, decimal-safe, any country and currency.
When to use
Use before approving, paying, booking, reconciling or auditing an invoice, especially when an agent needs to determine whether the invoice requires human review.
Selection guidance
Role: primary. invoice review before payment; duplicate and arithmetic checks; PO, contract and supplier-history comparison
Not for: company-level due diligence; extracting arbitrary document facts; carrier shipping quotes
Use cases
- Check this invoice before I pay it
- Is this invoice a duplicate of one we already received or paid?
- Did the supplier's bank account change?
- Does the invoice exceed the purchase order or contract?
- Are these invoices split to stay under the approval limit?
- Verify invoice arithmetic (quantity × unit price, subtotal, tax, total)
- Accounts-payable automation guardrail
- Pre-payment fraud prevention (invoice redirection / BEC)
- Three-way-match pre-check (invoice vs purchase order)
- Audit sampling and reconciliation
- finance
- accounts-payable
- procurement
Access
- REST:
POST https://api.rafidsystem.com/api/v1/finance/invoice-anomaly-check - x402:
POST https://api.rafidsystem.com/api/v1/x402/finance/invoice-anomaly-check - MCP tool:
invoice_anomaly_check - Free preview:
POST https://api.rafidsystem.com/api/v1/preview/invoice_anomaly_check
Price: $0.25 USD per call. Payment options are deployment-configured; inspect /api/v1/payment-methods. Prices and payment semantics are unchanged from the canonical registry.
Example input
{
"invoice": {
"invoiceNumber": "INV-2026-1043-A",
"supplierName": "ABC Trading LLC",
"supplierId": "SUP-291",
"invoiceDate": "2026-09-20",
"dueDate": "2026-10-20",
"currency": "USD",
"subtotal": 9200,
"tax": 460,
"total": 9660,
"bankAccount": "US123456789",
"paymentTermsDays": 30,
"poNumber": "PO-2026-818",
"lineItems": [
{
"description": "Consulting services",
"quantity": 10,
"unitPrice": 920,
"taxRate": 5,
"total": 9200
}
]
},
"historicalInvoices": [
{
"invoiceId": "AP-7781",
"invoiceNumber": "INV-2026-0981",
"supplierName": "ABC Trading LLC",
"supplierId": "SUP-291",
"invoiceDate": "2026-06-18",
"currency": "USD",
"total": 9177,
"bankAccount": "US987654321",
"paymentTermsDays": 30,
"status": "paid",
"lineItems": [
{
"description": "Consulting services",
"quantity": 9.5,
"unitPrice": 920,
"total": 8740
}
]
},
{
"invoiceId": "AP-7902",
"invoiceNumber": "INV-2026-1002",
"supplierName": "ABC Trading LLC",
"supplierId": "SUP-291",
"invoiceDate": "2026-07-19",
"currency": "USD",
"total": 9901.5,
"bankAccount": "US987654321",
"paymentTermsDays": 30,
"status": "paid",
"lineItems": [
{
"description": "Consulting services",
"quantity": 10.25,
"unitPrice": 920,
"total": 9430
}
]
},
{
"invoiceId": "AP-8015",
"invoiceNumber": "INV-2026-1021",
"supplierName": "ABC Trading LLC",
"supplierId": "SUP-291",
"invoiceDate": "2026-08-20",
"currency": "USD",
"total": 8694,
"bankAccount": "US987654321",
"paymentTermsDays": 30,
"status": "paid",
"lineItems": [
{
"description": "Consulting services",
"quantity": 9,
"unitPrice": 920,
"total": 8280
}
]
},
{
"invoiceId": "AP-8117",
"invoiceNumber": "INV-2026-1043",
"supplierName": "ABC Trading LLC",
"supplierId": "SUP-291",
"invoiceDate": "2026-09-18",
"currency": "USD",
"total": 9660,
"bankAccount": "US987654321",
"paymentTermsDays": 30,
"status": "pending"
}
],
"purchaseOrder": {
"poNumber": "PO-2026-818",
"supplierId": "SUP-455",
"supplierName": "Delta Office Supplies Ltd",
"currency": "USD",
"totalAmount": 20000,
"status": "open"
},
"options": {
"asOfDate": "2026-09-23"
}
}Example output
{
"riskScore": 100,
"riskLevel": "critical",
"decision": "hold",
"anomalyCount": 4,
"anomalies": [
{
"code": "POSSIBLE_DUPLICATE",
"severity": "high",
"confidence": 0.9,
"field": "invoiceNumber",
"explanation": "A same-supplier invoice with the same amount and a slightly altered invoice number (e.g. suffix or typo) was found nearby in time.",
"evidence": {
"reason": "invoice_number_variant_same_amount",
"matchSignals": [
"same_supplier",
"same_amount",
"date_gap_2_days",
"invoice_number_variant"
],
"matchedInvoice": {
"historicalIndex": 3,
"invoiceId": "AP-8117",
"invoiceNumber": "INV-2026-1043",
"supplierName": "ABC Trading LLC",
"invoiceDate": "2026-09-18",
"total": 9660,
"currency": "USD",
"status": "pending"
},
"matchedPayment": null,
"invoiceNumberRelation": "variant",
"amountDifferencePercent": 0,
"dateDifferenceDays": 2,
"lineItemSimilarity": null,
"samePoNumber": false,
"recurringAmountPattern": false,
"previouslyPaid": false,
"additionalMatches": 0
}
},
{
"code": "BANK_ACCOUNT_CHANGED",
"severity": "high",
"confidence": 0.9,
"field": "bankAccount",
"explanation": "The payment account on the invoice differs from the 1 account(s) previously recorded for this supplier; payment details should be verified with the supplier through a known contact before payment.",
"evidence": {
"reason": "account_differs_from_supplier_records",
"invoiceAccountMasked": "****6789",
"knownAccountsMasked": [
"****4321"
],
"knownAccountCount": 1,
"lastUsedAccountMasked": "****4321",
"lastUsedDate": "2026-09-18",
"sources": {
"supplierProfileAccounts": 0,
"historicalInvoicesWithAccount": 4,
"paymentsWithAccount": 0
},
"accountSeenForOtherSuppliers": false,
"otherSuppliers": []
}
},
{
"code": "PO_MISMATCH",
"severity": "high",
"confidence": 0.9,
"field": "poNumber",
"explanation": "The invoice supplier differs from the purchase order supplier.",
"evidence": {
"issues": [
{
"reason": "supplier_differs_from_po",
"severity": "high",
"invoiceSupplier": "ABC Trading LLC",
"poSupplier": "Delta Office Supplies Ltd"
}
]
}
},
{
"code": "INVOICE_NUMBER_ANOMALY",
"severity": "low",
"confidence": 0.85,
"field": "invoiceNumber",
"explanation": "The invoice-number format AAA-9999-9999-A deviates from this supplier's established format AAA-9999-9999.",
"evidence": {
"issues": [
{
"reason": "format_deviates_from_supplier_pattern",
"severity": "low",
"invoiceNumber": "INV-2026-1043-A",
"invoiceNumberFormat": "AAA-9999-9999-A",
"establishedFormat": "AAA-9999-9999",
"establishedFormatShare": 1,
"sampleSize": 4
}
]
}
}
],
"financialChecks": {
"subtotalValid": true,
"taxValid": true,
"totalValid": true,
"lineTotalsValid": true,
"computed": {
"lineItemsSum": 9200,
"expectedTax": 460,
"expectedTotal": 9660,
"tolerance": 0.01
}
},
"recommendedAction": "Compare this invoice with the matched invoice and supporting documents to rule out a duplicate before payment. Verify the payment details directly with the supplier using contact details already on file (not those on the invoice) before paying. Resolve the purchase-order discrepancies (supplier, currency, reference, quantities or prices) before approval.",
"summary": "4 anomalies detected (POSSIBLE_DUPLICATE, BANK_ACCOUNT_CHANGED, PO_MISMATCH, INVOICE_NUMBER_ANOMALY); risk critical (100/100). Advisory decision: hold — the invoice requires human review before payment.",
"mode": "context_aware",
"contextUsed": {
"historicalInvoices": 4,
"supplierHistoryMatched": 4,
"paymentHistory": 0,
"supplierProfile": false,
"purchaseOrder": true,
"contract": false,
"approvalContext": false
},
"invoiceSummary": {
"invoiceNumber": "INV-2026-1043-A",
"supplierName": "ABC Trading LLC",
"supplierId": "SUP-291",
"invoiceDate": "2026-09-20",
"dueDate": "2026-10-20",
"currency": "USD",
"total": 9660,
"lineItemCount": 1,
"bankAccountMasked": "****6789"
},
"dataCompleteness": {
"missingRequiredFields": [],
"missingRecommendedFields": []
},
"scoring": {
"model": "iac-1.0.0",
"components": [
{
"code": "POSSIBLE_DUPLICATE",
"severity": "high",
"confidence": 0.9,
"basePoints": 40,
"points": 36
},
{
"code": "BANK_ACCOUNT_CHANGED",
"severity": "high",
"confidence": 0.9,
"basePoints": 55,
"points": 49.5
},
{
"code": "PO_MISMATCH",
"severity": "high",
"confidence": 0.9,
"basePoints": 35,
"points": 31.5
},
{
"code": "INVOICE_NUMBER_ANOMALY",
"severity": "low",
"confidence": 0.85,
"basePoints": 5,
"points": 4.3
}
],
"lowSeverityPoints": 4.3,
"mediumSeverityPoints": 0,
"highSeverityPoints": 117,
"escalationBonus": 26,
"escalationReasons": [
"3 independent risk families with ≥ medium anomalies (duplicate, payment_details, po_contract): +16",
"payment-detail anomaly combined with a duplicate, PO/contract or split anomaly: +10"
],
"cappedBySeverity": true,
"rawScore": 147.3,
"levelBands": {
"low": "0-14",
"medium": "15-39",
"high": "40-64",
"critical": "65-100"
}
},
"limitations": [
"The capability identifies invoice anomalies and risk indicators. It does not independently establish fraud or replace accounting, audit, compliance, or payment-authorization controls.",
"The decision field is advisory only; it is not an approval or rejection of the payment.",
"Findings are limited to the data supplied in the request; no accounting system, bank or third-party source is consulted."
],
"asOfDate": "2026-09-23",
"checkedAt": "2026-09-23T00:00:00.000Z"
}Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"invoice": {
"type": "object",
"properties": {
"invoiceId": {
"description": "Your system's internal record id for this invoice. A historical invoice with the same invoiceId is treated as this same record and excluded from duplicate matching.",
"type": "string",
"minLength": 1,
"maxLength": 100
},
"invoiceNumber": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"supplierName": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"supplierId": {
"description": "Your vendor/supplier master id. Preferred over the name for matching history.",
"type": "string",
"minLength": 1,
"maxLength": 100
},
"invoiceDate": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"dueDate": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"currency": {
"type": "string",
"minLength": 1,
"maxLength": 10
},
"subtotal": {
"description": "Sum of line totals, before invoice-level discount, tax and shipping.",
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
]
},
"discount": {
"description": "Invoice-level discount amount.",
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
]
},
"shipping": {
"description": "Shipping / other charges added to the total.",
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
]
},
"tax": {
"description": "Total tax amount.",
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
]
},
"taxRate": {
"description": "Invoice-level tax rate, used when lines carry no taxRate.",
"type": "number",
"minimum": 0,
"maximum": 100
},
"total": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
],
"description": "Invoice total payable (subtotal − discount + tax + shipping). Required."
},
"bankAccount": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"paymentTermsDays": {
"type": "integer",
"minimum": 0,
"maximum": 3650,
"description": "Payment terms in days (e.g. 30 for net 30)."
},
"poNumber": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"contractId": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"lineItems": {
"maxItems": 500,
"type": "array",
"items": {
"type": "object",
"properties": {
"description": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"sku": {
"description": "Item/SKU code, used to match purchase-order lines.",
"type": "string",
"minLength": 1,
"maxLength": 100
},
"quantity": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
]
},
"unitPrice": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
]
},
"discount": {
"description": "Line discount amount (subtracted from quantity × unitPrice).",
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
]
},
"taxRate": {
"type": "number",
"minimum": 0,
"maximum": 100,
"description": "Tax rate in percent (e.g. 5 for 5%)."
},
"total": {
"description": "Line total EXCLUDING tax (quantity × unitPrice − discount).",
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
]
}
},
"additionalProperties": false
}
}
},
"required": [
"total"
],
"additionalProperties": false,
"description": "The invoice to check. Only `total` is required. Amounts: number or plain decimal string (\"9200.50\"); dates: ISO 8601; currency: ISO 4217 code; bankAccount is never echoed unmasked."
},
"historicalInvoices": {
"description": "Previously received invoices (any supplier; up to 1000). Enables duplicate, supplier-behavior, payment-detail and split checks.",
"maxItems": 1000,
"type": "array",
"items": {
"type": "object",
"properties": {
"invoiceId": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"invoiceNumber": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"supplierName": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"supplierId": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"invoiceDate": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"dueDate": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"currency": {
"type": "string",
"minLength": 1,
"maxLength": 10
},
"subtotal": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
]
},
"total": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
]
},
"bankAccount": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"paymentTermsDays": {
"type": "integer",
"minimum": 0,
"maximum": 3650,
"description": "Payment terms in days (e.g. 30 for net 30)."
},
"poNumber": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"status": {
"description": "Processing status. cancelled / void / rejected invoices are still used for duplicate matching (resubmissions) but excluded from behavior baselines, contract consumption and split detection.",
"type": "string",
"enum": [
"paid",
"approved",
"pending",
"disputed",
"rejected",
"cancelled",
"void",
"unknown"
]
},
"lineItems": {
"maxItems": 200,
"type": "array",
"items": {
"type": "object",
"properties": {
"description": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"sku": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"quantity": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
]
},
"unitPrice": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
]
},
"total": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
]
}
},
"additionalProperties": false
}
}
},
"required": [
"total"
],
"additionalProperties": false
}
},
"supplierProfile": {
"description": "Supplier master data for the invoice's supplier.",
"type": "object",
"properties": {
"supplierId": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"supplierName": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"aliases": {
"maxItems": 10,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"bankAccounts": {
"description": "Payment accounts on file for this supplier.",
"maxItems": 20,
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 80
},
{
"type": "object",
"properties": {
"account": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"verified": {
"description": "false = on file but not yet verified (e.g. by call-back).",
"type": "boolean"
},
"addedDate": {
"description": "When the account was added/changed in the supplier master.",
"type": "string",
"minLength": 1,
"maxLength": 40
}
},
"required": [
"account"
],
"additionalProperties": false
}
]
}
},
"currencies": {
"description": "Currencies this supplier normally invoices in.",
"maxItems": 10,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 10
}
},
"paymentTermsDays": {
"description": "Agreed standard payment terms.",
"type": "integer",
"minimum": 0,
"maximum": 3650
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"blocked",
"suspended",
"pending_verification"
]
},
"createdDate": {
"description": "When the supplier record was created.",
"type": "string",
"minLength": 1,
"maxLength": 40
},
"country": {
"type": "string",
"minLength": 1,
"maxLength": 60
}
},
"additionalProperties": false
},
"purchaseOrder": {
"description": "The purchase order the invoice is billed against.",
"type": "object",
"properties": {
"poNumber": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"supplierId": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"supplierName": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"currency": {
"type": "string",
"minLength": 1,
"maxLength": 10
},
"totalAmount": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
]
},
"invoicedToDate": {
"description": "Amount already invoiced against this PO (excluding this invoice).",
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
]
},
"remainingAmount": {
"description": "Remaining PO balance before this invoice; takes precedence over totalAmount − invoicedToDate.",
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
]
},
"amountsIncludeTax": {
"description": "Default true: PO amounts are compared with the invoice total. false: compared with the invoice net amount (subtotal − discount).",
"type": "boolean"
},
"issueDate": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"status": {
"type": "string",
"enum": [
"open",
"partially_invoiced",
"closed",
"cancelled"
]
},
"lineItems": {
"maxItems": 500,
"type": "array",
"items": {
"type": "object",
"properties": {
"description": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"sku": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"quantity": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
]
},
"unitPrice": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
]
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"contract": {
"description": "The governing contract.",
"type": "object",
"properties": {
"contractId": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"supplierId": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"supplierName": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"currency": {
"type": "string",
"minLength": 1,
"maxLength": 10
},
"maxAmount": {
"description": "Contract value cap.",
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
]
},
"maxInvoiceAmount": {
"description": "Maximum amount allowed on a single invoice.",
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
]
},
"invoicedToDate": {
"description": "Amount already invoiced under the contract (excluding this invoice). When omitted, supplied historicalInvoices for the supplier inside the contract period are summed instead.",
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
]
},
"startDate": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"endDate": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"paymentTermsDays": {
"type": "integer",
"minimum": 0,
"maximum": 3650,
"description": "Payment terms in days (e.g. 30 for net 30)."
}
},
"additionalProperties": false
},
"approvalContext": {
"type": "object",
"properties": {
"approvalThreshold": {
"description": "Single-invoice amount above which additional approval is required. Enables split-invoice detection.",
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
]
},
"currency": {
"description": "Currency of approvalThreshold (default: the invoice currency).",
"type": "string",
"minLength": 1,
"maxLength": 10
},
"splitWindowDays": {
"description": "Window for grouping same-supplier invoices in split detection (default 7).",
"type": "integer",
"minimum": 1,
"maximum": 90
}
},
"additionalProperties": false
},
"paymentHistory": {
"description": "Past payments (any supplier). Used for known payment accounts and already-paid detection.",
"maxItems": 1000,
"type": "array",
"items": {
"type": "object",
"properties": {
"invoiceNumber": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"supplierId": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"supplierName": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"paymentDate": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"amount": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
]
},
"currency": {
"type": "string",
"minLength": 1,
"maxLength": 10
},
"bankAccount": {
"type": "string",
"minLength": 1,
"maxLength": 80
}
},
"additionalProperties": false
}
},
"options": {
"type": "object",
"properties": {
"asOfDate": {
"description": "Reference date for date checks (default: today, UTC). Supplying it makes the output fully reproducible.",
"type": "string",
"minLength": 1,
"maxLength": 40
},
"roundingTolerance": {
"description": "Absolute arithmetic tolerance in currency units, replacing the default of one minor unit per rounding step.",
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1,
"maxLength": 40
}
]
},
"duplicateWindowDays": {
"description": "Maximum date gap for near-duplicate matching (default 14).",
"type": "integer",
"minimum": 1,
"maximum": 365
},
"minHistoryForPatterns": {
"description": "Minimum same-supplier invoices required before supplier-behavior baselines are used (default 3).",
"type": "integer",
"minimum": 2,
"maximum": 50
}
},
"additionalProperties": false
}
},
"required": [
"invoice"
],
"additionalProperties": false
}Output schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"riskScore": {
"type": "integer",
"minimum": 0,
"maximum": 100,
"description": "0–100, higher = more risk indicators; see scoring for the exact computation."
},
"riskLevel": {
"type": "string",
"enum": [
"low",
"medium",
"high",
"critical"
],
"description": "low 0–14, medium 15–39, high 40–64, critical 65–100."
},
"decision": {
"type": "string",
"enum": [
"continue",
"review",
"hold"
],
"description": "Advisory only: low → continue, medium/high → review, critical → hold. Not a payment approval or rejection."
},
"anomalyCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"anomalies": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"SUBTOTAL_MISMATCH",
"TAX_MISMATCH",
"TOTAL_MISMATCH",
"LINE_TOTAL_MISMATCH",
"DUPLICATE_INVOICE",
"POSSIBLE_DUPLICATE",
"UNUSUAL_AMOUNT",
"SUPPLIER_PATTERN_DEVIATION",
"UNUSUAL_CURRENCY",
"UNUSUAL_PAYMENT_TERMS",
"INVOICE_NUMBER_ANOMALY",
"BANK_ACCOUNT_CHANGED",
"UNKNOWN_BANK_ACCOUNT",
"PO_MISMATCH",
"PO_AMOUNT_EXCEEDED",
"CONTRACT_LIMIT_EXCEEDED",
"APPROVAL_THRESHOLD_EXCEEDED",
"SPLIT_INVOICE_PATTERN",
"DATE_ANOMALY",
"DUE_DATE_ANOMALY",
"DUPLICATE_LINE_ITEM",
"MISSING_REQUIRED_FIELD"
],
"description": "Stable machine code of the anomaly type."
},
"severity": {
"type": "string",
"enum": [
"info",
"low",
"medium",
"high",
"critical"
]
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "0–1 strength of the supporting evidence (not a probability of fraud)."
},
"field": {
"description": "Primary invoice field concerned (e.g. invoiceNumber, bankAccount, total), or null.",
"type": [
"string",
"null"
]
},
"explanation": {
"type": "string",
"description": "One factual sentence, phrased as a risk indicator (never an accusation)."
},
"evidence": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {},
"description": "Structured, factual evidence for the finding (matched records, expected vs stated values, baselines, thresholds). Bank accounts appear only masked (****1234)."
}
},
"required": [
"code",
"severity",
"confidence",
"field",
"explanation",
"evidence"
],
"additionalProperties": false
},
"description": "Most severe first. At most one record per anomaly code; sub-findings are in evidence.issues."
},
"financialChecks": {
"type": "object",
"properties": {
"subtotalValid": {
"description": "Σ line totals ≈ subtotal; null when not checkable (no lines or no subtotal).",
"type": [
"boolean",
"null"
]
},
"taxValid": {
"description": "Stated tax ≈ tax implied by the stated rate(s); null when no rate or no tax is stated.",
"type": [
"boolean",
"null"
]
},
"totalValid": {
"description": "subtotal − discount + tax + shipping ≈ total; null when not checkable.",
"type": [
"boolean",
"null"
]
},
"lineTotalsValid": {
"description": "quantity × unitPrice − discount ≈ line total for every line that states all three; null when none does.",
"type": [
"boolean",
"null"
]
},
"computed": {
"type": "object",
"properties": {
"lineItemsSum": {
"type": [
"number",
"null"
]
},
"expectedTax": {
"type": [
"number",
"null"
]
},
"expectedTotal": {
"type": [
"number",
"null"
]
},
"tolerance": {
"type": "number"
}
},
"required": [
"lineItemsSum",
"expectedTax",
"expectedTotal",
"tolerance"
],
"additionalProperties": false
}
},
"required": [
"subtotalValid",
"taxValid",
"totalValid",
"lineTotalsValid",
"computed"
],
"additionalProperties": false
},
"recommendedAction": {
"type": "string"
},
"summary": {
"type": "string"
},
"mode": {
"type": "string",
"enum": [
"standalone",
"context_aware"
]
},
"contextUsed": {
"type": "object",
"properties": {
"historicalInvoices": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"supplierHistoryMatched": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"paymentHistory": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"supplierProfile": {
"type": "boolean"
},
"purchaseOrder": {
"type": "boolean"
},
"contract": {
"type": "boolean"
},
"approvalContext": {
"type": "boolean"
}
},
"required": [
"historicalInvoices",
"supplierHistoryMatched",
"paymentHistory",
"supplierProfile",
"purchaseOrder",
"contract",
"approvalContext"
],
"additionalProperties": false
},
"invoiceSummary": {
"type": "object",
"properties": {
"invoiceNumber": {
"type": [
"string",
"null"
]
},
"supplierName": {
"type": [
"string",
"null"
]
},
"supplierId": {
"type": [
"string",
"null"
]
},
"invoiceDate": {
"type": [
"string",
"null"
]
},
"dueDate": {
"type": [
"string",
"null"
]
},
"currency": {
"type": [
"string",
"null"
]
},
"total": {
"type": "number"
},
"lineItemCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"bankAccountMasked": {
"type": [
"string",
"null"
]
}
},
"required": [
"invoiceNumber",
"supplierName",
"supplierId",
"invoiceDate",
"dueDate",
"currency",
"total",
"lineItemCount",
"bankAccountMasked"
],
"additionalProperties": false,
"description": "Normalized key fields of the checked invoice (bank account masked)."
},
"dataCompleteness": {
"type": "object",
"properties": {
"missingRequiredFields": {
"type": "array",
"items": {
"type": "string"
}
},
"missingRecommendedFields": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"missingRequiredFields",
"missingRecommendedFields"
],
"additionalProperties": false
},
"scoring": {
"type": "object",
"properties": {
"model": {
"type": "string"
},
"components": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"severity": {
"type": "string"
},
"confidence": {
"type": "number"
},
"basePoints": {
"type": "number"
},
"points": {
"type": "number"
}
},
"required": [
"code",
"severity",
"confidence",
"basePoints",
"points"
],
"additionalProperties": false
}
},
"lowSeverityPoints": {
"type": "number"
},
"mediumSeverityPoints": {
"type": "number"
},
"highSeverityPoints": {
"type": "number"
},
"escalationBonus": {
"type": "number"
},
"escalationReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"cappedBySeverity": {
"type": "boolean"
},
"rawScore": {
"type": "number"
},
"levelBands": {
"type": "object",
"properties": {
"low": {
"type": "string"
},
"medium": {
"type": "string"
},
"high": {
"type": "string"
},
"critical": {
"type": "string"
}
},
"required": [
"low",
"medium",
"high",
"critical"
],
"additionalProperties": false
}
},
"required": [
"model",
"components",
"lowSeverityPoints",
"mediumSeverityPoints",
"highSeverityPoints",
"escalationBonus",
"escalationReasons",
"cappedBySeverity",
"rawScore",
"levelBands"
],
"additionalProperties": false,
"description": "Exact score derivation: per-anomaly points = basePoints × confidence, severity-group caps, correlation bonus, severity ceiling."
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
},
"asOfDate": {
"type": "string",
"description": "Reference date (UTC) used for date checks."
},
"checkedAt": {
"type": "string",
"description": "ISO timestamp of the as-of date (UTC start of day). Deliberately day-granular so identical inputs give identical output; pass options.asOfDate for full reproducibility."
}
},
"required": [
"riskScore",
"riskLevel",
"decision",
"anomalyCount",
"anomalies",
"financialChecks",
"recommendedAction",
"summary",
"mode",
"contextUsed",
"invoiceSummary",
"dataCompleteness",
"scoring",
"limitations",
"asOfDate",
"checkedAt"
],
"additionalProperties": false
}Category: Finance Intelligence · hierarchy: primary · idempotent: yes · side effects: no