Idempotency and External Identifiers

Current idempotency model for document creation and delivery callbacks in the Numora Public API developer preview.

Scope

This page explains the current idempotency model used by the Numora Public API developer preview.

The important distinction is:

In the current preview, Numora uses resource-specific identifiers for retry safety.

POST /v1/documents

Use external_id when your system needs to create or retry the same logical document submission safely.

Current behavior:

external_id is scoped to the same user and schema
resubmitting the same external_id for the same schema returns the existing document resource instead of creating a new logical document

Practical meaning:

POST /v1/documents/{id}/delivery

Use execution_id when your external worker needs to retry the same delivery callback safely.

Current behavior:

the callback is idempotent by execution_id
replaying the same execution_id with the same delivery data is accepted
replaying the same execution_id with different delivery data returns 409 conflict

Some API ecosystems use a generic Idempotency-Key header for all mutating requests.

That is not the main current contract for Numora public API preview routes.

For the current preview, prefer:

Do not assume that sending Idempotency-Key alone gives retry safety across all /v1 mutating routes.

When your ERP, email ingestion service, or document queue submits a document:

Example:

{
  "schema": "invoice_v2",
  "file_url": "https://example.com/invoice-001.pdf",
  "external_id": "ap-100024"
}

When your worker writes to a destination system outside Numora:

document.id: Numora-assigned resource identifier
external_id: client-assigned business identifier for document creation reconciliation
execution_id: client-assigned attempt identifier for delivery callback reconciliation