Documents

Request and response model for Numora document ingestion, status retrieval, and review actions.

Scope

This page defines the document resource used by the Numora Public API developer preview.

The API is asynchronous by default. Clients submit a document, store the returned id, and then use polling or webhooks to observe state changes.

Resource Model

Each submitted file creates one document resource.

Core fields:

id
schema
status
external_id
metadata
created_at
updated_at
review_state
duplicate_of

The review_state field should be null or a structured object that records confirmed fields and confirmed line items. For the detailed review model, see Review and Approval.

Create a Document

POST /v1/documents

Example request:

{
  "schema": "invoice_v2",
  "file_url": "https://example.com/invoice-001.pdf",
  "external_id": "ap-100024",
  "metadata": {
    "source": "email-import",
    "vendor_code": "ACME"
  }
}

Example response:

{
  "id": "doc_01jpwq4q9m7q4q2k8dax1x1q5n",
  "status": "processing",
  "schema": "invoice_v2",
  "status_url": "/v1/documents/doc_01jpwq4q9m7q4q2k8dax1x1q5n",
  "result_url": "/v1/documents/doc_01jpwq4q9m7q4q2k8dax1x1q5n/result"
}

The server returns 202 Accepted for asynchronous creation.

Retrieve Document Status

GET /v1/documents/{id}

Document lifecycle values:

processing
review_required
reviewed
push_pending
push_succeeded
push_failed
failed

For the exact mapping between the current internal OCR states and the future public document.status model, see Document Lifecycle.

Retrieve Document Result

GET /v1/documents/{id}/result

Example response:

{
  "id": "doc_01jpwq4q9m7q4q2k8dax1x1q5n",
  "schema": "invoice_v2",
  "status": "review_required",
  "review_state": {
    "version": 1,
    "confirmed_general_field_names": ["invoice_number"],
    "confirmed_line_item_ids": []
  },
  "confidence": 0.93,
  "fields": {
    "vendor_name": {
      "value": "ACME Supplies",
      "confidence": 0.98
    },
    "invoice_number": {
      "value": "INV-2026-001",
      "confidence": 0.97
    }
  },
  "line_items": [],
  "duplicate_of": null
}

Review Actions

Review is modeled as an explicit action rather than an implicit side effect.

POST /v1/documents/{id}/actions/approve
POST /v1/documents/{id}/actions/reject
POST /v1/documents/{id}/actions/retry-push

For action semantics, review-state shape, and approval conflict handling, see Review and Approval.

Notes

POST /v1/documents is a valid ingest entrypoint, but it is not the required first step for the initial CRM delivery path.
external_id should be optional but strongly recommended for idempotent client reconciliation.
In the current preview, retrying the same logical document submission should reuse the same external_id.
Result schemas must be versioned explicitly with values such as invoice_v2.
Large or expensive operations should remain asynchronous.
The public response body should not leak provider-specific internal fields unless they are intentionally part of the external contract.

Documents

On this page