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
call POST /v1/documents/{id}/dispatch
let Numora resolve the active delivery route
observe push_* delivery status

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

3. Start Route-Based Delivery

Use:

POST /v1/documents/{id}/dispatch

Example:

curl -X POST "https://api.numora.example/v1/documents/doc_123/dispatch" \
  -H "Authorization: Bearer $NUMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-request-id: first-crm-delivery-001" \
  -d '{
    "provider": "dynamics365"
  }'

Numora uses the active delivery route to decide whether the document should run through an internal workflow or notify the shared n8n executor.

4. Choose a Delivery Mode

Recommended: Numora-managed dispatch

Call POST /v1/documents/{id}/dispatch.
Let Numora resolve the active route.
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.

Call POST /v1/documents/{id}/dispatch.
Let Numora notify the shared n8n executor.
Call GET /v1/documents/{id}/result if your worker needs the latest structured payload.
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 dispatch and the active delivery route.