Available

Retrieve a document job

Poll by consumer reference and inspect the complete persisted document job row.

Updated 2026-07-28

GET https://app.docparser.dev/api/v1/documents/:consumerRefId

Returns the persisted document_jobs row selected for the authenticated organization and consumer reference.

Request

Send both authentication headers. URL-encode the consumerRefId when constructing the path.

curl --request GET 'https://app.docparser.dev/api/v1/documents/inv-4471' \
--header "x-client-id: $DOCPARSER_CLIENT_ID" \
--header "x-client-secret: $DOCPARSER_CLIENT_SECRET"

Response fields

The response is the database row serialized with camelCase property names:

Field	Type	Nullability	Description
`id`	UUID	Never null	Docparser job identifier returned as jobId by POST.
`clientId`	UUID	Never null	Organization identifier used to scope the lookup.
`apiKeyId`	UUID \| null	Nullable	API key used for submission; null on legacy rows that predate key tracking.
`consumerRefId`	string	Never null	Caller-supplied correlation value used by this retrieval path.
`documentId`	integer \| null	Nullable in storage	Caller-supplied numeric document identifier; current submit requests require it.
`typeId`	integer	Never null	Selected parser type; email attachment jobs persist internal mode type 8.
`mode`	"single" \| "multi" \| "email"	Never null	Mode inferred from the submitted body shape.
`requireLineItems`	boolean	Never null	Whether the requested output shape includes line items.
`status`	string	Never null	Current processing status, initially initiated.
`payload`	JSON	Never null	Validated submission body persisted for asynchronous processing.
`extractedData`	JSON \| null	Nullable	Persisted structured result after successful extraction.
`extractionTimeMs`	integer \| null	Nullable	Measured extraction duration in milliseconds.
`geminiCost`	decimal string \| null	Nullable	Persisted model cost with six decimal places.
`webhookUrl`	string	Never null	Resolved absolute delivery URL after joining the request path to the key base URL.
`webhookStatus`	string \| null	Nullable	webhook_posted or webhook_failed after a delivery attempt.
`webhookAttempts`	integer	Never null	Delivery attempt count, initially 0.
`webhookResponseCode`	integer \| null	Nullable	HTTP status returned by the receiver on the latest delivery attempt.
`webhookResponseBody`	string \| null	Nullable	Truncated response body from the latest receiver attempt.
`error`	string \| null	Nullable	Human-readable processing failure.
`errorStage`	string \| null	Nullable	Classified failure stage such as download, extraction, parsing, or delivery.
`errorCode`	string \| null	Nullable	Machine-oriented classified failure code when available.
`errorDetail`	JSON \| null	Nullable	Structured diagnostic details for a classified failure.
`parserVersionId`	UUID \| null	Nullable	Registry parser version UUID, or null for the code-default fallback and older jobs.
`parserVersion`	integer \| null	Nullable	Registry parser version number when one was resolved.
`archivedS3Key`	string \| null	Nullable	Archived source key for eligible single-mode jobs when ingest archiving succeeded.
`createdAt`	ISO 8601 timestamp	Never null	Time the job row was accepted.
`updatedAt`	ISO 8601 timestamp	Never null	Time the row was last updated.

Immediately after 202 Accepted, extractedData, extractionTimeMs, geminiCost, webhookStatus, webhookResponseCode, webhookResponseBody, error, errorStage, errorCode, errorDetail, parserVersionId, parserVersion, and archivedS3Key can be null before completion. webhookAttempts starts at 0; status starts as initiated.

Some nullable fields stay null on successful jobs. For example, the error fields remain null, and archivedS3Key can remain null when archiving was skipped, failed, or does not apply.

Initial response example

{
"id": "5ca1ab1e-314d-4b2d-b9d6-8e68870b840f",
"clientId": "3ca8d191-29a4-4495-b629-d6ec0972bca5",
"apiKeyId": "b264a170-f125-4dd6-91d6-41f237b70b75",
"consumerRefId": "inv-4471",
"documentId": 4471,
"typeId": 0,
"mode": "single",
"requireLineItems": true,
"status": "initiated",
"payload": {
  "documentUrl": "https://files.example.com/invoices/inv-4471.pdf",
  "webhookUrl": "/hooks/docparser",
  "requireLineItems": true,
  "documentId": 4471,
  "consumerRefId": "inv-4471",
  "typeId": 0
},
"extractedData": null,
"extractionTimeMs": null,
"geminiCost": null,
"webhookUrl": "https://api.example.com/hooks/docparser",
"webhookStatus": null,
"webhookAttempts": 0,
"webhookResponseCode": null,
"webhookResponseBody": null,
"error": null,
"errorStage": null,
"errorCode": null,
"errorDetail": null,
"parserVersionId": null,
"parserVersion": null,
"archivedS3Key": null,
"createdAt": "2026-07-28T08:30:00.000Z",
"updatedAt": "2026-07-28T08:30:00.000Z"
}

Status and errors

A successful lookup returns 200. Processing statuses include initiated, extracting, classifying_email_content, extracting_from_attachments, processed, error. A missing match returns 404 with Document job not found.

Authentication failures use the same 401 and 403 behavior as submission. See Authentication.