Invoice Intelligence

POST https://kovca.io/api/v1/invoices/check

Authenticate with your API key in the Authorization: Bearer header. Send JSON with Content-Type: application/json; bodies are limited to 16 KB.

The API checks the invoice you send against the purchase order and receipts you send. All arithmetic is exact decimal arithmetic in code. Interpretation is used only to decide which purchase-order line a differently worded invoice line describes. It never authorizes or initiates payments.

Request body

{
  "invoice": {
    "number": "INV-20931",
    "vendor": {
      "name": "Northwind Supply",
      "id": "V-1042"
    },
    "currency": "USD",
    "lines": [
      {
        "sku": "NW-4410",
        "description": "Nitrile gloves, large, box of 100",
        "quantity": 40,
        "unit_price": "12.50",
        "amount": "500.00"
      },
      {
        "description": "Hand sanitizer gel 500ml pump bottle",
        "quantity": 24,
        "unit_price": "4.10",
        "amount": "98.40"
      }
    ],
    "subtotal": "598.40",
    "tax": "47.87",
    "total": "646.27"
  },
  "purchase_order": {
    "number": "PO-7781",
    "currency": "USD",
    "lines": [
      {
        "line_id": "1",
        "sku": "NW-4410",
        "description": "Gloves, nitrile, L (100/box)",
        "quantity": 40,
        "unit_price": "12.50"
      },
      {
        "line_id": "2",
        "description": "Sanitizer, gel, 500 ml pump",
        "quantity": 24,
        "unit_price": "3.95"
      }
    ]
  }
}

Response

{
  "request_id": "req_2bWq9Lm4Ks7TzXcN",
  "status": "discrepancies_found",
  "recommended_action": "reject_for_correction",
  "issues": [
    {
      "type": "unit_price_mismatch",
      "invoice_line": 1,
      "po_line": 1,
      "expected": "3.95",
      "actual": "4.10",
      "explanation": "The unit price differs from the purchase order price.",
      "evidence": [
        "invoice.lines[1]",
        "purchase_order.lines[1]"
      ]
    }
  ],
  "matched_lines": [
    {
      "invoice_line": 0,
      "po_line": 0,
      "method": "identifier"
    },
    {
      "invoice_line": 1,
      "po_line": 1,
      "method": "description"
    }
  ],
  "unmatched_lines": [],
  "missing_information": []
}

How an invoice is checked

1. Duplicates: the invoice number and vendor are compared with known_invoices.
2. Arithmetic: each line amount, the subtotal, and the total (when tax is given) are recomputed with exact decimals.
3. Line matching: lines with the same sku or line_id are paired in code. Remaining lines are matched by description. A description match must be confident and can't be claimed by two invoice lines; otherwise it's ambiguous_line_match.
4. Matched lines: quantities are compared with the order and receipts, units must agree, and unit prices are compared in the same currency.

Statuses (first match wins)

• requires_review: A possible duplicate, an ambiguous line match, or a currency mismatch. Action: manual_review.
• discrepancies_found: A quantity, price, or amount discrepancy (action: reject_for_correction), or an invoice line with no order line (action: manual_review).
• insufficient_information: No purchase order and no other problems. Action: request_information.
• matched: Every line matched and agreed. Action: approve_for_processing.

Issue types

• quantity_mismatch: A line bills more than was ordered or received (beyond quantity_percent), or uses a different unit than the order line.
• unit_price_mismatch: A line's unit price differs from the order price beyond the price tolerances.
• amount_mismatch: A line amount isn't quantity × unit price, the subtotal isn't the sum of the lines, or the total isn't subtotal plus tax.
• currency_mismatch: The invoice and purchase order currencies differ. Prices aren't compared.
• unmatched_line: No purchase-order line describes this invoice line.
• ambiguous_line_match: It's unclear which purchase-order line an invoice line describes. A person should decide.
• missing_purchase_order: No purchase order was supplied; only the invoice's own arithmetic and duplicates were checked.
• possible_duplicate: known_invoices has the same invoice number from the same vendor.

Without a purchase order

{
  "invoice": {
    "number": "INV-88",
    "vendor": {
      "name": "Acme Facilities"
    },
    "currency": "EUR",
    "lines": [
      {
        "description": "Quarterly HVAC maintenance visit",
        "quantity": 1,
        "unit_price": "450.00",
        "amount": "450.00"
      }
    ],
    "total": "535.50",
    "tax": "85.50"
  }
}

Code

curl https://kovca.io/api/v1/invoices/check \
  -H "Authorization: Bearer $KOVCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "invoice": {
    "number": "INV-20931",
    "vendor": {
      "name": "Northwind Supply",
      "id": "V-1042"
    },
    "currency": "USD",
    "lines": [
      {
        "sku": "NW-4410",
        "description": "Nitrile gloves, large, box of 100",
        "quantity": 40,
        "unit_price": "12.50",
        "amount": "500.00"
      },
      {
        "description": "Hand sanitizer gel 500ml pump bottle",
        "quantity": 24,
        "unit_price": "4.10",
        "amount": "98.40"
      }
    ],
    "subtotal": "598.40",
    "tax": "47.87",
    "total": "646.27"
  },
  "purchase_order": {
    "number": "PO-7781",
    "currency": "USD",
    "lines": [
      {
        "line_id": "1",
        "sku": "NW-4410",
        "description": "Gloves, nitrile, L (100/box)",
        "quantity": 40,
        "unit_price": "12.50"
      },
      {
        "line_id": "2",
        "description": "Sanitizer, gel, 500 ml pump",
        "quantity": 24,
        "unit_price": "3.95"
      }
    ]
  }
}'

Errors

• 400 INVALID_REQUEST: a field is missing, too long, the wrong type, or not allowed. The message names the field.
• 400 INVALID_REQUEST also covers amounts that aren't plain decimals (for example "$12" or 1e3) and currencies that aren't 3-letter codes.
• 413 PAYLOAD_TOO_LARGE: the body is larger than 16 KB.
• 401 UNAUTHORIZED, 429 RATE_LIMITED, 503 SERVICE_UNAVAILABLE, 504 TIMEOUT: see Errors and limits.

Limitations

• Matching is one purchase order per request. Split invoices spanning several orders.
• No currency conversion. Different currencies are flagged, never converted.
• Duplicates are detected only against known_invoices you supply.
• Billing less than ordered is treated as a partial invoice, not a discrepancy.
• Request data is processed to produce the result and is not stored by Kovca.