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
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
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
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.
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
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.
| Error | Meaning | Retryable |
|---|---|---|
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 | 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 |