Available

Submit documents

Submit single files, multi-image documents, or email attachments for asynchronous extraction.

Updated 2026-07-28

POST https://app.docparser.dev/api/v1/documents

Validates a request, stores a document job, enqueues extraction, and returns an acceptance envelope without waiting for processing.

Authentication

Send x-client-id and x-client-secret headers plus content-type: application/json. See Authentication for failure behavior, IP restrictions, and rotation.

How the request mode is selected

The API infers exactly one mode from the body in this precedence order:

attachments[] — if attachments is an array, the request is parsed as email attachment mode.
documentUrls[] — otherwise, if documentUrls is an array, the request is parsed as multi-image mode.
Single document — otherwise, the request is parsed as single-document mode and must contain documentUrl.

Precedence is based on body shape, not typeId. If both arrays are present, attachments wins. An empty winning array still selects that mode and then fails its minimum-one-item validation.

Fields shared by every mode

Field	Type	Required	Description
`webhookUrl`	string	No; defaults to ""	Relative path joined to the API key’s registered base URL. Absolute and protocol-relative URLs are rejected.
`requireLineItems`	boolean	Yes	Whether the selected parser should return its line-item shape.
`documentId`	integer	Yes	Caller-supplied numeric document identifier. Returned as document_id in webhooks.
`consumerRefId`	non-empty string	Yes	Caller-supplied correlation reference. Scoped during retrieval, but not database-unique.

Single and multi-image requests also accept:

Field	Type	Required	Description
`typeId`	integer	No; defaults to 0	Live document type to parse. Email mode infers its internal mode and does not use this field.

Live public values are 0 (Invoice), 1 (Purchase Order), 2 (GRN), 3 (Debit Note), 4 (Credit Card Statement), 5 (Credit Card Statement (multi-account)), and 9 (PO number only).

Mode-specific fields

Single document

Field	Type	Required	Description
`documentUrl`	absolute URL string	Yes	Publicly fetchable source document.

Multi-image document

Field	Type	Required	Description
`documentUrls`	URL string[]	Yes; at least one	Ordered source image URLs for one combined invoice or individual invoices.
`processingMode`	"single_invoice" \| "multiple_invoices"	No; defaults to "single_invoice"	Combine all images as one invoice or extract each URL as a separate invoice.

Email attachments

Field	Type	Required	Description
`attachments`	URL string[]	Yes; at least one	Publicly fetchable attachment URLs. Their presence selects email mode.
`subject`	string	Yes	Email subject used by the invoice-intent classifier.
`body`	string	Yes	Email body used by the invoice-intent classifier.

Request examples

{
"documentUrl": "https://files.example.com/invoices/inv-4471.pdf",
"webhookUrl": "/hooks/docparser",
"requireLineItems": true,
"documentId": 4471,
"consumerRefId": "inv-4471",
"typeId": 0
}

{
"documentUrls": [
  "https://files.example.com/invoices/inv-4471-page-1.png",
  "https://files.example.com/invoices/inv-4471-page-2.png"
],
"processingMode": "single_invoice",
"webhookUrl": "/hooks/docparser",
"requireLineItems": true,
"documentId": 4471,
"consumerRefId": "inv-4471-images",
"typeId": 0
}

{
"attachments": [
  "https://files.example.com/mail/invoice-4471.pdf"
],
"subject": "Invoice INV-4471",
"body": "Please find the invoice attached.",
"webhookUrl": "/hooks/docparser",
"requireLineItems": true,
"documentId": 4471,
"consumerRefId": "inv-4471-email"
}

Accepted response

The endpoint returns 202 Accepted after persistence and queueing:

{
"jobId": "5ca1ab1e-314d-4b2d-b9d6-8e68870b840f",
"consumerRefId": "inv-4471"
}

jobId is the persisted row UUID. consumerRefId echoes the request value; it is not a globally unique key and the database does not enforce uniqueness for it.

Request and webhook names

Requests use camelCase, including consumerRefId, documentId, typeId, requireLineItems, and webhookUrl. Webhook payloads use snake_case for corresponding identifiers, including consumer_ref_id and document_id.

Extraction fields follow their documented response schema; for example, invoice payloads contain processed_data.summary_data and processed_data.lineItems.

Errors

400 — invalid request shape, an absolute webhookUrl, an unknown typeId, or an internal/archived type.
401 — missing or invalid authentication headers.
403 — valid credentials used outside the key’s configured IP allowlist.
500 with Failed to create document job. — the job could not be persisted.

After acceptance, receive the webhook or retrieve the persisted job.