Authentication

How to authenticate with the Numora Public API developer preview and submit your first document request.

Scope

This page explains how to authenticate with the Numora Public API developer preview and send the first request against the document resource.

Authentication

The public API uses API keys and the Authorization header.

Base URL

Use the API base URL provided for your workspace or environment.

The host shown in the examples on this page, https://api.numora.example, is a placeholder.

Example header:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxx

Required Headers

For JSON requests, send:

Authorization: Bearer <api_key>
Content-Type: application/json

You should also send x-request-id for request correlation when possible.

First Request

Create a document:

curl -X POST "https://api.numora.example/v1/documents" \
  -H "Authorization: Bearer $NUMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-request-id: create-document-001" \
  -d '{
    "schema": "invoice_v2",
    "file_url": "https://example.com/invoice-001.pdf",
    "external_id": "ap-100024",
    "metadata": {
      "source": "email-import"
    }
  }'

Example response:

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

Poll for Status

After document creation, retrieve status until the resource leaves processing.

curl "https://api.numora.example/v1/documents/doc_01jpwq4q9m7q4q2k8dax1x1q5n" \
  -H "Authorization: Bearer $NUMORA_API_KEY"

When the document is ready, retrieve the result:

curl "https://api.numora.example/v1/documents/doc_01jpwq4q9m7q4q2k8dax1x1q5n/result" \
  -H "Authorization: Bearer $NUMORA_API_KEY"

Suggested Integration Flow

Create the document.
Store the returned id.
Poll the document status or subscribe to webhooks.
Retrieve the final result.
Approve, reject, or retry downstream push actions as needed.

For current preview idempotency semantics, use external_id for document creation reconciliation rather than assuming a generic Idempotency-Key contract across all routes.

Authentication

On this page