Polling Reviewed Documents

Recommended polling pattern for listing reviewed and finalized Numora documents that are ready for downstream delivery.

Scope

This page explains how external workers such as n8n should poll Numora for reviewed documents that are ready for downstream delivery.

Use this guide when:

documents are already processed and reviewed inside Numora
your worker needs a stable polling surface
delivery should start only after review is complete

For the full outbox -> dispatch integration pattern, see n8n Outbound Delivery.

Recommended Endpoint

GET /v1/delivery/outbox?provider=dynamics365&limit=100

This is the recommended polling surface for the first public integration model.

It returns reviewed and finalized documents that are eligible for downstream delivery.

Why Poll the Outbox Instead of Listing All Documents

Polling delivery/outbox is safer than scanning all documents because the outbox already applies delivery-specific filtering.

The current model excludes documents that are already:

push_pending
push_succeeded

That means the worker can focus on reviewed documents that still need delivery handling.

Recommended Polling Loop

Schedule polling every 5 to 10 minutes.
Call GET /v1/delivery/outbox.
Read the returned data array.
For each item, either call dispatch_url or perform the destination write externally.
If the response includes meta.next_cursor, pass it back unchanged in the next request.

Example Request

curl "https://api.numora.example/v1/delivery/outbox?provider=dynamics365&limit=100" \
  -H "Authorization: Bearer $NUMORA_API_KEY" \
  -H "x-request-id: reviewed-poll-001"

Example Response

{
  "data": [
    {
      "document_id": "4be38121-3791-4856-80d5-c57dbec2cf78",
      "schema": "invoice_v2",
      "status": "reviewed",
      "external_id": null,
      "metadata": {},
      "result_url": "/v1/documents/4be38121-3791-4856-80d5-c57dbec2cf78/result",
      "dispatch_url": "/v1/documents/4be38121-3791-4856-80d5-c57dbec2cf78/dispatch",
      "updated_at": "2026-03-24T02:36:37.684Z"
    }
  ],
  "meta": {
    "provider": "dynamics365",
    "next_cursor": null
  }
}

Cursor Handling

meta.next_cursor is opaque.

Do not parse it.
Do not modify it.
Pass it back exactly as returned.

If next_cursor is null, the current scan window is complete.

Two Delivery Modes After Polling

After a document appears in the outbox, there are two supported paths.

1. Numora-managed dispatch

Recommended for the first multi-tenant integration model.

Poll the outbox.
Call POST /v1/documents/{id}/dispatch.
Poll GET /v1/documents/{id} until the status leaves push_pending.

2. External executor callback

Use this only when the destination write happens outside Numora.

Poll the outbox.
Call GET /v1/documents/{id}/result.
Write to the destination system externally.
Call POST /v1/documents/{id}/delivery.

Operational Notes

Treat polling as eventually consistent background work.
Use conservative concurrency during first rollout.
Store document_id, x-request-id, and any returned run identifiers for troubleshooting.
If a document later becomes push_failed, it may reappear for future polling depending on the delivery path.

Polling Reviewed Documents

On this page