A useful batch review ends with traceable decisions, not a downloaded list of verdicts. Define the population, preserve its context, retrieve every result and give exceptions and unresolved checks an owner.
Define what the population represents
Imagine Meridian Distribution preparing a fictional month-end review of 2,400 supplier invoices. The objective is to investigate supported invoice-control exceptions before the payment team completes its review. The population is a dated export of recorded invoices for specified business units, with documented exclusions and a reconciliation to the source system.
That definition matters. Processing every uploaded row establishes coverage of the upload; it does not establish that the export contains every invoice or unrecorded liability. Keep the source query, cutoff, row count and extraction date in your workpapers. The audit-concepts guide explains how population coverage, assertions and audit conclusions relate.
Prepare related records together
An audit request contains one use_case, an items array, shared context and optional options. Each item needs a unique type/id pair. Retain stable business identifiers so a finding can be joined back to its invoice, claim, extracted field or agent action.
The current engine accepts up to 10,000 items and 50,000 context records per audit, subject to request-size and account limits. Related items in a batch are available to population checks. Include additional history in context.records, such as vendor records or comparison invoices. Read the limits guide before choosing batch size.
Partition deliberately when a population needs several requests. A duplicate invoice in another partition will not become visible simply because both jobs belong to the same account. Preserve the relevant comparison context. For agent actions, keep the session history needed for rate checks; for extracted fields, preserve the components needed for declared totals.
Do not assume that a one-item audit behaves like single verification when history is absent. The audit's items establish their own comparison population types. With only one invoice, the duplicate check can have an available population but no peers. Our batch-boundary experiment records that distinction and shows how splitting related payments changed an overall verdict.
Make a small trial before submitting the full population
Choose reviewed cases that exercise the intended controls: a complete invoice, a missing purchase-order reference, a duplicate candidate and a record without its vendor context. Confirm the field mapping, policy parameters and routing for each finding. These cases test your integration’s behavior; they are not a measurement of accuracy across all suppliers.
Follow the single-item quickstart, then the batch API reference. Keep the trial’s source data and returned configuration so later differences can be investigated. A rule change, different comparison population or changed source mapping may explain a changed result.
Record acceptance and completion separately
Submit to POST /api/v1/audits. HTTP 202 means the job was accepted; save its audit id immediately. Poll GET /api/v1/audits/{id} at a modest interval while respecting account request limits.
| Status | Meaning | Next action |
|---|---|---|
queued | The service accepted the job. | Retain the id and check again later. |
running | Verification is in progress. | Read the items-done and items-total progress fields. |
completed | Results are available. | Stop status polling and retrieve all result pages. |
failed | The job did not complete successfully. | Inspect the error before deciding whether another submission is appropriate. |
A submission timeout can leave acceptance unknown. Send an Idempotency-Key with each submission so a repeat returns the job the first attempt created; without one, a blind repeat may create another job. Preserve request and response identifiers where available, and make ambiguous submission a distinct recovery state. The error guide distinguishes this problem from a completed false or uncertain verdict.
Retrieve every page before reconciling the review
After completion, retrieve GET /api/v1/audits/{id}/items. Results arrive in a data array with next_cursor. Follow that cursor until it is null. Keep the same filters across pages; use an unfiltered retrieval when reconciling the full population.
Compare the returned item identities with the submitted population. An exception-only view is useful for work allocation, but it is not a complete results export. Keep the summary and full verification objects, including assertions, evidence pointers, configuration and input_sha256. A count alone cannot explain why a particular invoice was flagged.
Create separate queues for exceptions and unresolved work
A false verdict identifies an applicable failed assertion. For the supplier-invoice example, a missing PO reference above its threshold goes to the procurement or accounts-payable control owner. Preserve the original result while the owner obtains evidence or documents the control exception.
An uncertain verdict needs a different route. Missing vendor context belongs with the data owner; an unqualified semantic question may require human judgment. A true result covers the checked assertions and supplied evidence; caller-skipped assertions remain outside that conclusion. It does not instruct the payment system to release funds.
Prioritize work using the nature of the finding and your review objective. The API does not calculate audit materiality or aggregate monetary misstatements against it. An invoice amount associated with a control exception is not automatically a loss or a misstated balance.
Record review feedback without erasing the original result
The review-marks endpoint records whether a reviewer judged an item’s returned verdict correct. A mark of correct: true can therefore confirm a false verdict after the reviewer verifies the missing PO. It does not approve the invoice.
A later mark replaces the stored assessment for that item. Marks do not change the original verdict, rerun checks, retrain a model or maintain a complete reviewer history. Keep assignments, supporting documents, reviewer identity, timestamps and final disposition in your own workflow. If source data changes, retain the correction and rerun reference alongside the earlier finding.
Close the review with an evidence package
Export the information you need before the audit’s returned expires_at; hosted batch retention is seven days after completion unless deleted sooner. Deleting an audit removes its stored inputs, results and marks. Apply your organization’s retention requirements to the records you keep; see data handling and retention.
A review package should connect the original population, submitted context, complete results and resolved work queue. Use the same structure for extracted-data verification or agent-action review, adapting the evidence and ownership to the business decision being tested.