Reference

Invoice checks

Check a supplier invoice against its PO and delivery note#

POST/invoice-checks

Authorization: API-Key · Rate limit 120 requests / 60 s (sandbox 10 in total)

Business plan. Multipart: files[] (the invoice, purchase order and delivery note: PDF, JPEG or PNG; up to 10) and data ({ kinds? }). One invoice check is charged (allowance, then 5 credits). The documents are read at once; a person approves in the account area. Live keys only.

Headers#

Idempotency-Keystring
Replays the first response for 24 hours.
max length 255

Request body#

multipart/form-data · required

files[]array of string (binary)required
dataobjectrequired
JSON string
- kindsarray of string
  Kind of each file in files[], in the same order; left out (or shorter than files[]) means detect it.
  invoicepurchase_orderdelivery_notecredit_note
  max items 10

curl -X POST "https://macaaw.com/public/v1/invoice-checks" \
  -H "Authorization: API-Key $MACAAW_API_KEY" \
  -F "files[]=@document.pdf;type=application/pdf" \
  -F 'data={"kinds":["invoice"]}'

Responses#

201OKapplication/json · InvoiceCheck
400Validation errorapplication/json · Error
401Missing, unknown or revoked API keyapplication/json · Error
403Plan or permissionapplication/json · Error
404Not foundapplication/json · Error
409Wrong stateapplication/json · Error
413File too largeapplication/json · Error
422Unprocessable fileapplication/json · Error
429Rate limitedapplication/json · Error
Headers: Retry-After

201 response

{
  "id": "string",
  "status": "received",
  "supplier": "string",
  "invoice_number": "string",
  "po_number": "string",
  "dn_number": "string",
  "invoice_date": "string",
  "due_date": "string",
  "currency": "string",
  "invoiced_total_pence": 1,
  "matched_total_pence": 1,
  "difference_pence": 1,
  "issues": [
    {
      "code": "string",
      "line": 1,
      "amount_pence": 1,
      "detail": "string"
    }
  ],
  "decision": null,
  "approved_amount_pence": 1,
  "documents": [
    {
      "id": "string",
      "kind": null,
      "status": "pending"
    }
  ],
  "lines": [
    {
      "position": 1,
      "description": "string",
      "result": "string",
      "amount_at_stake_pence": 1
    }
  ],
  "url": "https://example.com/webhooks/macaaw",
  "date_created": "2026-10-30T11:35:00.000000Z",
  "date_modified": "2026-10-30T11:35:00.000000Z"
}

Invoice check status and result#

GET/invoice-checks/{id}

Authorization: API-Key · Rate limit 600 requests / 60 s (sandbox 10 in total)

Path parameters#

idstringrequired

curl "https://macaaw.com/public/v1/invoice-checks/$ID" \
  -H "Authorization: API-Key $MACAAW_API_KEY"

Responses#

200OKapplication/json · InvoiceCheck
400Validation errorapplication/json · Error
401Missing, unknown or revoked API keyapplication/json · Error
403Plan or permissionapplication/json · Error
404Not foundapplication/json · Error
429Rate limitedapplication/json · Error
Headers: Retry-After

200 response

{
  "id": "string",
  "status": "received",
  "supplier": "string",
  "invoice_number": "string",
  "po_number": "string",
  "dn_number": "string",
  "invoice_date": "string",
  "due_date": "string",
  "currency": "string",
  "invoiced_total_pence": 1,
  "matched_total_pence": 1,
  "difference_pence": 1,
  "issues": [
    {
      "code": "string",
      "line": 1,
      "amount_pence": 1,
      "detail": "string"
    }
  ],
  "decision": null,
  "approved_amount_pence": 1,
  "documents": [
    {
      "id": "string",
      "kind": null,
      "status": "pending"
    }
  ],
  "lines": [
    {
      "position": 1,
      "description": "string",
      "result": "string",
      "amount_at_stake_pence": 1
    }
  ],
  "url": "https://example.com/webhooks/macaaw",
  "date_created": "2026-10-30T11:35:00.000000Z",
  "date_modified": "2026-10-30T11:35:00.000000Z"
}