Authentication and First CRM Delivery

Recommended first integration path for authenticating with Numora and delivering already-reviewed documents into a CRM workflow.

Scope

This guide is the recommended first path for teams that want to connect Numora to a CRM or downstream operations system.

It assumes:

documents are already processed inside Numora
review happens inside Numora before delivery
an external worker such as n8n coordinates the delivery flow

If you need file ingestion first, see Authentication and Documents.

1. Get an API Key

The public API uses bearer token authentication.

Example header:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxx

Use the API base URL assigned to your workspace or environment.

2. Understand the First CRM Delivery Path

For the first CRM-oriented integration, the main path is not:

POST /v1/documents

Instead, the recommended path is:

review documents inside Numora
poll GET /v1/delivery/outbox
call dispatch or perform the external write
observe push_* delivery status

This is the fastest way to connect already-reviewed Numora documents to a downstream CRM process.

3. Poll Reviewed Documents

Use:

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

Example:

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

The outbox returns reviewed and finalized documents that are ready for downstream delivery handling.

4. Choose a Delivery Mode

Recommended: Numora-managed dispatch

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

Fallback: external executor callback

Use this only when your worker writes to the destination system directly.

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

5. Read Delivery Status

The document resource is the primary status surface for the dispatch-based path.

Typical meanings:

reviewed: confirmed and ready for delivery
push_pending: delivery is queued or running
push_succeeded: delivery completed successfully
push_failed: the latest delivery attempt failed

6. Know When `POST /v1/documents` Is Optional

POST /v1/documents remains a valid ingest entrypoint.

But for the first CRM delivery story, it is optional rather than required.

If your documents already live in Numora and are reviewed there, you can start directly from the delivery outbox.