OpenAuditor Start free

Verify an item

Check one record or decision against the supplied rules and related records.

POST /v1/verify verifies one item synchronously and returns its Verification object. Use it for a record entering a workflow or a decision that is ready for review. Batch audits handle populations.

Request structure

FieldRequiredWhat it contains
use_caseYesA registered use-case ID, such as financial-audit, which runs its current version; or a served version, such as financial-audit@1, to keep the checks you integrated against.
itemYesA supported type, stable id and type-specific data.
context.recordsAs needed by checksArrays of related records keyed by record type. Context records have their own id.
context.referencesAs needed by checksThe rule and reference sets read by the chosen pack, such as financial approval limits.
context.engagementOptionalThe entity and/or period of the review, where relevant to its checks.
optionsOptionalQuestion use, certainty target, explicit skipped assertions and pack parameter overrides.

Use the discovery endpoints and schemas to build the data object for your chosen item type. Required fields differ between an expense, an approval, a contract line and an agent action.

Supply the context the checks need

The request defines the evidence boundary. A vendor ID does not make the service fetch a vendor record, and a document ID does not make it retrieve a document. Supply those records under context.records using the types registered by the use case.

For a single verification, an explicitly empty comparison list declares that no other comparison records were supplied. Omitting a required population can leave its check unresolved. If relevant history exists but was not exported, an empty list would misrepresent your intended review scope.

Send money and decimal quantities as strings, such as "24800.00". Use YYYY-MM-DD for dates and include timezone offsets on action timestamps. Keep field names and types consistent with the published schema.

Options

OptionDefaultEffect
questions"auto""none" disables model questions while direct checks still run. A required judgment can remain unresolved.
certainty_target"0.995"Sets the gate error budget to one minus this decimal-string target. It does not guarantee accuracy or require returned measured certainty to reach the target.
skip[]Removes named assertion IDs from the deciding scope. The response records them in scope.skipped; a subsequent verdict covers that reduced scope.
parametersPack defaultsOverrides supported parameter names using the expected value types. Unknown names and incompatible types are rejected.

Complete example

This synthetic supplier invoice is for $24,800.00: 20 business laptops at $1,240.00 each from Northstar IT Supply. It supplies the active vendor and an explicitly empty comparison invoice list. No PO reference is supplied. Save the request as invoice.json.

Supplier invoice request JSON
{
  "use_case": "financial-audit",
  "item": {
    "type": "invoice",
    "id": "INV-2026-0841",
    "data": {
      "vendor_id": "V-1042",
      "invoice_number": "INV-2026-0841",
      "invoice_date": "2026-09-18",
      "amount": "24800.00",
      "currency": "USD",
      "description": "20 business laptops for the finance team equipment refresh.",
      "line_items": [
        {
          "quantity": "20",
          "unit_price": "1240.00",
          "description": "Business laptop, 16 GB RAM, 512 GB SSD"
        }
      ],
      "tax_amount": "0.00",
      "discount_amount": "0.00"
    }
  },
  "context": {
    "records": {
      "vendor": [
        {
          "id": "V-1042",
          "name": "Northstar IT Supply",
          "created_on": "2024-02-12",
          "status": "active"
        }
      ],
      "invoice": []
    },
    "engagement": {
      "entity": "Illustrative procurement audit",
      "period": {"start": "2026-07-01", "end": "2026-09-30"}
    }
  }
}
curl "https://openauditor.ai/api/v1/verify" \
  -H "Authorization: Bearer $OPENAUDITOR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @invoice.json

The local engine returns false because the invoice exceeds the financial-audit pack’s default $1,000.00 PO threshold and lacks a PO reference. The arithmetic, active-vendor and supplied-population duplicate checks hold. No model judgment is needed to establish that control exception.

Policy thresholds and audit materiality

options.parameters.po_thresholds is a procurement-control parameter: one amount per currency, such as {"USD": "1000.00", "EUR": "900.00"}, replacing the default whole. An invoice in a currency it does not list holds only with a PO reference and is otherwise insufficient_evidence. It is not an audit materiality threshold. The current context.engagement schema supports an entity and period, not a materiality field. Keep engagement materiality, qualitative significance and the auditor’s assessment in your review workflow; the API does not determine them.

Send uncompressed JSON with a known content length. Curl supplies that length when posting a local file. See the quickstart for complete Python and JavaScript clients.

Response and failure handling

An accepted verification returns 200 for true, false and uncertain verdicts alike. Read the verdict, assertions, undecided and scope fields before routing the result. HTTP errors are request or service failures, not findings about the business record.

A successful response also includes OpenAuditor-Configuration and OpenAuditor-Usage headers. The public gateway returns a Request-Id for troubleshooting. Preserve these identifiers alongside the response when your process needs a review trail.

Fix a schema problem before resubmitting. For temporary overload or rate limits, respect Retry-After and keep retries bounded. Consult limits before submitting a large context.

Continue reading