API reference
Retrieve document
Retrieve a document and, once it has finished, its result. Poll this endpoint until the status is completed, needs_review, or failed. If you set a callback, fetch here when it arrives.
On this page
GET/v1/documents/{document_id}
Path parameters
document_idstringRequired
The doc_… ID that create document returned.
Responses
The document. Which fields it has depends on its status.
Response body
Fields marked Present when appear only for those statuses, and fields marked Optional may be left out; every other field is always present. data validates against the standalone invoice.v1 JSON Schema.
idstring
The document's ID.
created_atdate-time
When the document was created.
accounting_entity_idstring · nullable
Your accounting entity from create document, or null.
- Length
- 1–255 characters
policyobject
The accepted review policy, with every member filled in.
3 child fields
required_fieldsarray of strings
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_itemsstring
How line-item findings affect review, and whether usable line items are required.
advisory- 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_detectionboolean
Whether this document takes part in duplicate checks. false skips both duplicate checks and adds nothing to your duplicate history.
callbackobject · nullable
Callback delivery, or null when no callback URL was set. See callbacks.
8 child fields
event_idstring · nullable
The document.finished event's ID, or null before there is one. Check that it matches the callback you received.
statusstring
Where delivery stands.
pending- Delivery is underway or will be retried.
delivered- Your callback URL accepted the event.
failed- A permanent failure, or attempts or time ran out. The document itself is unaffected.
attempt_countinteger
Delivery attempts so far.
last_attempt_atdate-time · nullable
When the last attempt was made.
next_attempt_atdate-time · nullable
When the next attempt is due, while delivery is pending.
last_http_statusinteger · nullable
The HTTP status your URL returned on the last attempt.
- Range
- 100–599
last_error_codestring · nullable
Why the last attempt failed. See callback delivery errors.
delivered_atdate-time · nullable
When delivery succeeded.
metadataobject
Your key/value pairs from create document, unchanged.
- Keys
- up to 10
- Key length
- 1–64 characters
- Value length
- up to 500 characters
statusstring
Where the document is in processing.
awaiting_upload- Waiting for the file. Processing has not been admitted yet.
queued- The file passed admission; processing is waiting to begin.
processing- Processing is underway.
completed- A usable result with no blocking check. Warnings may remain.
needs_review- A usable result with at least one blocking check.
failed- No usable result was produced. This status is final.
completed_atdate-time
When processing finished.
- Present when
- status is completed, needs_review, or failed
documentobject
The uploaded file.
- Present when
- status is completed, needs_review, or failed
3 child fields
page_countinteger · nullable
The file's page count. It is null only when a failed file could not be counted.
- Range
- at least 1
datainvoice.v1
The extracted invoice. See the invoice.v1 reference for every field.
- Present when
- status is completed or needs_review
validationobject
The checks run on the result.
- Present when
- status is completed or needs_review
2 child fields
review_requiredboolean
true when at least one check blocks, which makes the status needs_review.
checksarray of objects
Every check that ran, with its outcome. See checks.
Fields of each item
codestring
The check that ran, such as total_consistency. New codes may be added; see every check.
statusstring
The outcome.
pass- The check passed.
fail- The check found a problem.
not_evaluable- The inputs were missing or unclear, so the check could not decide.
severitystring
How much a failed check matters. A check blocks when its severity is review and its status is not pass.
info- Informational only.
warning- Worth a look; the result can still be completed.
review- Needs a person when the check fails or can't decide.
messagestring · nullable
An explanation for people, or null. Never branch on it.
pathsarray of JSON Pointers
The invoice fields the finding is about, such as /data/totals/total, so you can highlight them in your own review screen.
detailsJSON value · nullableOptional
Check-specific data, such as the equation, calculated value and difference of an arithmetic check.
processingobject
How the result was produced and how long it is kept.
- Present when
- status is completed or needs_review
4 child fields
pipeline_versionstring
The processing pipeline's version.
duration_msinteger
Processing time in milliseconds, from the start of processing until the result was stored. Upload, queue wait and callback delivery are not included.
result_expires_atdate-time
When the retained result expires. After that, fetching the document returns 410 document_expired.
errorobject
Why the document failed.
- Present when
- status is failed
4 child fields
codestring
A stable code. See errors and recovery.
messagestring
An explanation for people. Never branch on it.
retryableboolean
Whether retrying could succeed. A failed document is final, so retrying it never restarts processing.
docs_urlURLOptional
The code's entry in the error reference. Show it to developers; never branch on it.
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 |
401 invalid_api_key | The API key was not accepted. 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 |
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 |
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 |
Documents in other accounts also return 404 document_not_found.
Polling and retention
While queued or processing, responses may include a Retry-After header - treat it as a minimum delay. Terminal structured results are retained 7 days by default; persist what your workflow needs before processing.result_expires_at.