API reference

Create document

Create a document and get a signed URL for uploading the invoice. Upload your file to that URL in private storage, not to this endpoint.

On this page

POST/v1/documents

Headers

Idempotency-Keystringoptional

Optional but strongly recommended. One stable key per logical invoice, 1-255 characters. Retries must reuse the exact key and body; changing the body under a live key returns idempotency_conflict.

Body parameters

filenamestringrequired

The original filename, 1-255 characters. Storage paths never contain it; it is retained as document metadata only.

content_typestringrequired

One of application/pdf, image/jpeg, or image/png. Must match the uploaded bytes.

file_size_bytesintegerrequired

Exact source size in bytes, 1 through 20971520 (20 MiB). The confirmation step verifies the stored object against it.

external_idstringoptional

Your own reference ID, up to 255 characters. Returned on every document response so you can match it to records in your system.

accounting_entity_idstringoptional

Opaque, case-sensitive caller namespace (up to 255 characters). Duplicate detection is isolated within it and usage can be attributed to it; it is not an authorization boundary.

policyobjectoptional

Acceptance controls, echoed canonically on every response. line_items is advisory (default), review_on_failure, or required, required_fields is an array of unique allowlisted JSON Pointer paths, defaulting to []. See supported field paths.

checks.duplicate_detection is a boolean, defaulting to true. Omitted policy members receive server defaults; null, unknown members and unsupported values are rejected. See all review policy settings for acceptance behavior and limits.

callback_urlstring · HTTPS URLoptional

Optional per-document callback wakeup. HTTPS only, port 443, no credentials or fragment. The callback is an untrusted hint - fetch the document to act on it. Avoid sensitive values in the URL; hosting platform logs may retain it.

metadataobjectoptional

Up to 10 key/value pairs preserved exactly: keys are 1-64 ASCII letters, digits, _, ., or -; values are single-line strings up to 500 characters.

Responses

201 - created: the document is awaiting_upload and the body carries the upload capability plus upload.expires_at.
200 - exact idempotent replay. It may refresh the signed upload capability while the reservation is alive; a 200 awaiting_upload replay must probe upload-complete before re-uploading.
4xx/5xx - typed error envelope with stable code, request_id, and retryable.

The signed upload URL and returned headers are secret capability material: never log or cache them, and never forward Invoice API credentials to the upload origin.

[data-code-tabs-interactive] { display: none !important; }

cURLBash / Zsh syntax (macOS, Linux, or WSL).

curl --fail-with-body --no-location \
  https://api.temlavo.com/v1/documents \
  -H "Authorization: Bearer inv_live_your_key" \
  -H "Idempotency-Key: invoice-2026-0842" \
  -H "Content-Type: application/json" \
  --data '{
    "filename": "invoice.pdf",
    "content_type": "application/pdf",
    "file_size_bytes": 84213
  }'

SDK: full lifecycle

import { readFile } from 'node:fs/promises';
import { InvoiceClient } from '@temlavo/sdk';

const client = new InvoiceClient({
  apiKey: process.env.INVOICE_API_KEY!,
});

// documents.process() performs create → upload →
// confirm → poll with this same endpoint underneath.
const file = await readFile('./invoice.pdf');
const result = await client.documents.process({
  file,
  filename: 'invoice.pdf',
  contentType: 'application/pdf',
});

TerminalBash / Zsh syntax (macOS, Linux, or WSL).

curl --fail-with-body --no-location \
  https://api.temlavo.com/v1/documents \
  -H "Authorization: Bearer inv_live_your_key" \
  -H "Idempotency-Key: invoice-2026-0842" \
  -H "Content-Type: application/json" \
  --data '{
    "filename": "invoice.pdf",
    "content_type": "application/pdf",
    "file_size_bytes": 84213
  }'

The SDK's process() waits for completed, needs_review, or failed. The response below belongs to this HTTP endpoint.

HTTP endpoint response

201 Created
{
  "id": "doc_9f3kc28d",
  "object": "document",
  "status": "awaiting_upload",
  "document_type": "invoice",
  "schema_version": "invoice.v1",
  "policy": { "required_fields": [], "line_items": "advisory", "checks": { "duplicate_detection": true } },
  "upload": {
    "method": "PUT",
    "url": "https://<private-storage>/...",
    "headers": { "…": "…" },
    "expires_at": "2026-09-16T15:30:00.000Z"
  }
}