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-Keystring

Strongly recommended: one key per invoice, in printable ASCII without spaces or commas. Retries must send the same key and the same body; changing the body under a key that is still active returns idempotency_conflict.

Length
1–255 characters

Temlavo-Upload-Recoverystring

Lets a retry recover a file that already uploaded: an exact retry of a document still waiting for its file returns upload: null once the file exists. Call Confirm upload before uploading again. Creating a document never starts processing.

Valueconfirm-existing

Body parameters

application/json3 required5 optional

filenamestringRequired

The original filename, without surrounding spaces or control characters. It is kept as document metadata only; storage paths never contain it.

Length
1–255 characters

content_typestringRequired

Must match the bytes you upload.

One ofapplication/pdfimage/jpegimage/png

file_size_bytesintegerRequired

Exact size of the file you will upload, up to 20 MiB. Confirm upload checks the stored file against it.

Range
1–20,971,520

external_idstring

Your own reference. It is returned on every document response so you can match the document to records in your system.

Length
1–255 characters

accounting_entity_idstring

An opaque, case-sensitive namespace of your own, such as a client ID. Duplicate detection is isolated within it and usage can be attributed to it; it is not an authorization boundary.

Length
1–255 characters

policyobject

How findings affect this document's review outcome. Omitted members get their defaults; null, unknown members and unsupported values are rejected. The accepted policy is returned on every response. See review policy for how each setting works.

3 child fields

required_fieldsarray of stringsDefault []

Invoice fields that must be present, as JSON Pointer paths such as /data/invoice/purchase_order_number. A required field that comes back null makes the document need review. See the fields you can require.

Items
up to 17, unique

Each one of17 supported values

line_itemsstringDefault advisory

How line-item findings affect review, and whether usable line items are required.

advisoryDefault
Eligible row findings stay warnings and don't block completion.
review_on_failure
Row calculation failures, conflicting row values, and rows that add up to neither the subtotal nor the total require review. Missing rows alone don't.
required
Row failures block, and the result also needs complete line items: at least one row, each with a line total and a description or product code.

checksobject

Checks for this document.

1 child field

duplicate_detectionbooleanDefault true

Whether this document takes part in duplicate checks. false skips both duplicate checks and adds nothing to your duplicate history.

callback_urlURL

Notified when this document finishes. HTTPS on port 443, with no credentials or fragment. The callback is a notification, not the result: fetch the document before acting on it. Keep sensitive values out of the URL; hosting platform logs may retain it.

Length
1–2,048 characters

metadataobjectDefault {}

Your own key/value pairs, preserved exactly. Keys use ASCII letters, digits, _, . or -; values are single-line strings.

Keys
up to 10
Key length
1–64 characters
Value length
up to 500 characters

Responses

200

A retry with the same key and body. It returns the existing document, which may include a fresh upload URL while it still waits for its file. If it returns awaiting_upload, call upload-complete before uploading again: the file may already have arrived.

201

The document is awaiting_upload, and upload says where and how to send the file.

Both return the document resource. While the document waits for its file, it also carries its upload authorization:

uploadobject · nullable

Where and how to upload the file to private storage. It is null only on an exact retry sent with Temlavo-Upload-Recovery once the file exists.

Present when
status is awaiting_upload
4 child fields

methodstring

The HTTP method for the upload.

ValuePUT

urlURL

The signed upload URL.

headersobject

Headers to send with the upload, exactly as given.

expires_atdate-time

When the signed URL stops accepting the upload.

Treat the signed upload URL and its headers like a password: anyone who has them can upload to this document. Never log or cache them, and never send your API key to the upload URL.

Errors

Every error uses the typed error envelope.

ErrorMeaningRetryable
400 invalid_request

The request body, headers, query parameters or path did not validate. What to do

No
400 invalid_callback_url

The optional callback URL was rejected. Returned when the callback URL is the only invalid body field; an oversized file or unsupported content type is reported first, and any other invalid field makes the request fail with invalid_request. What to do

No
401 invalid_api_key

The API key was not accepted. What to do

No
402 billing_required

No active plan or allowance covers processing. A rejected upload-complete can be retried after you fix billing; a document that has already failed with this code cannot. What to do

No
404 document_not_found

The document does not exist in this account or was deleted. Never treat this as a successful DELETE. What to do

No
409 idempotency_conflict

The same key was sent with a different create request body. What to do

No
410 upload_expired

The upload window for this document is closed. This is more than an expired signed URL. What to do

No
410 document_expired

The document passed its deadline: its retained result expired, or its upload window closed without a confirmed upload. It cannot be retrieved again. What to do

No
413 document_too_large

The declared or uploaded file is larger than 20 MiB. What to do

No
415 unsupported_content_type

The declared content type is not supported, or the uploaded file does not match it. What to do

No
429 rate_limit_exceeded

Too many requests. Wait at least Retry-After, then retry a limited number of times. Create and upload-complete enforce rate limits today; the other operations reserve this response. What to do

Yes, after Retry-After
500 internal_error

Something failed on our side. An HTTP 500 alone does not mean you may retry; check retryable and keep the request ID. What to do

No
503 service_unavailable

The service is temporarily unavailable. Retry the same request a limited number of times when retryable is true. What to do

Yes, with backoff; honor Retry-After if sent