Published

A finance application submits six invoice files. Two are ready for review, one fails input validation, one targets a workspace the caller cannot use, one is still undergoing OCR and one loses its response during creation. A banner saying “Upload complete” leaves the operator guessing which files to correct, wait for or investigate.
A batch document API should identify the batch and each submitted item, explain the outcome of each operation, and provide a way to retrieve later results. Separate acceptance, document creation, processing and business readiness. Keep an uncertain result visible until evidence resolves it.
State whether items can succeed independently or must be accepted as a complete group. For a best-effort import, valid files can proceed while other items remain rejected or unresolved. If the business needs a complete package, gate its release on the package rule even when some underlying documents already exist. Do not imply a cross-document rollback unless the implementation actually provides it.
Agree maximum item count and payload size, supported content, ordering, concurrency, timeout behaviour and the point at which an item is considered ready. For this example, ready means that the document and required processing results are available for accounts-payable review. It does not mean the invoice has been approved, posted or paid.
Validate the request, check permitted scope and retain stable item identities.
Connect each item to its document, attempts and required processing evidence.
Report ready items, explicit rejections, ongoing work and unresolved outcomes.
| Layer | Evidence to return | What remains separate |
|---|---|---|
| Batch acceptance | Batch identity, submitted item count, accepted scope and result location. | Acceptance does not establish that individual documents were created or processed. |
| Item admission | Client item key, validation outcome and a safe reason for rejection. | A valid item still needs authorised execution and an observed result. |
| Document operation | Permitted document reference, intended source and creation or update evidence. | A timeout can leave the operation uncertain; a document identity alone does not prove every required effect. |
| Processing | Required action statuses, observation time and relevant output references. | OCR completion does not establish approval or a successful external business update. |
| Business readiness | The configured readiness result, remaining exception, owner and next action. | A reconciled batch may contain explicit failures or exclusions as well as successful items. |
Reject a malformed or unauthorised batch request according to the API contract before admitting its work. For a valid asynchronous request, HTTP 202 Accepted describes acceptance for processing rather than completed processing. Return a durable batch reference and a protected way to inspect progress. An immediate best-effort result can instead describe all observed item outcomes in its response body.
A successful request to retrieve a batch result says the retrieval succeeded. The body still needs to explain mixed outcomes. Include the time of the observation and consistent summary counts; if results need pagination, keep the item set and count basis stable while their states evolve. Retain rejected items so a later page does not silently omit them.
Keep the batch identity separate from the client item key, source-file identity, FormKiQ documentId and processing attempt. Scope duplicate protection to the authorised caller, destination and intended operation. A department intake, business use case or SaaS tenant can provide part of that context; a client-supplied label is not sufficient authority to choose it.
Persist the intended work before execution. The integration can reserve an identifier and record its source and parameters before calling a document operation. Define concurrent-duplicate handling, recovery after an interrupted claim and how long prior outcomes remain available. Reusing a key with changed intent needs an explicit conflict or new-operation rule.
A retry of the batch should not automatically replay every successful item. Reconcile uncertain creates and external effects, then recover only the work whose evidence and policy permit it. FormKiQ's document-level retry operation can retry multiple failed actions in scope; the document-action retry guide explains that recovery decision in detail.
This illustrative finance integration uses a durable batch record and individual FormKiQ document operations. Its intake rules require an invoice reference and permitted destination. Selected OCR processing is part of this deployment's readiness check.
The application records one batch and six client item keys before dispatching work. Each accepted item retains its source reference, destination, intended document identifier and processing requirements. Access to the batch result is restricted to its authorised users.
One file lacks the invoice reference required by this application's intake contract. Another requests a workspace outside the caller's authorised department. Both remain in the result with safe reasons and next steps; neither is counted as a created document.
Two documents meet the readiness check. A third document exists with OCR still pending. The fourth create loses its response, leaving the outcome uncertain. The summary accounts for all six: two ready, one rejected input, one access refusal, one processing and one unresolved.
The integration uses its recorded document identifier and attempt evidence to investigate the uncertain create. It verifies the intended source and operation before accepting an existing result. It also observes the outstanding OCR result through the document's actions. If evidence cannot establish an outcome, the item remains assigned for review.
Suppose the uncertain create is verified and required processing finishes. Four items are now ready for accounts-payable review; two remain rejected with owners and next actions. The operator can close reconciliation with those explicit exceptions, or correct them under a recorded new submission. The batch never becomes “six successful invoices.”
Check access when retrieving progress and item details, as well as during execution. A batch identifier is a reference, not a permission grant. Return stable error categories and useful correction guidance without revealing another department's document names, contents or existence. Keep detailed diagnostics behind the appropriate support access.
Record when a status was observed and which source and attempt it describes. Define cancellation as a request with an observed outcome: some items may already have completed. Expired result history or a missing callback should lead to a defined recovery route rather than an invented success. The ingestion and backpressure guide covers controlling the rate of work admitted downstream.
A useful batch result tells the caller which documents are ready, which were rejected and which still need work or evidence. Connect each result to its intended source, document and processing history. Then a mixed outcome becomes a recoverable work list rather than a reason to resubmit the whole batch.
The open-source foundation — API-first, deployable into your own AWS account, and free to use. Right for architecture validation and early implementation.
Production-ready editions for departments and complex workflows. Start with a Proof-of-Value deployment or go straight to production.
For governance-heavy environments with residency, sovereignty, assurance, and multi-jurisdiction requirements. Talk to us about the right deployment model.