Extract a document

This is the Docmind core: send a business document, get structured data back. Product-wise it is document analysis — classify, then extract. Architecturally it is an asynchronous job, not a synchronous OCR RPC.

POST a PDF or image. The API returns 202 with a documentId. Wait for PROCESSING_FINALISED, then GET. Do not poll.

POST/v1/workspaces/{workspaceId}/documents

Tip

Use stage (idp-stage.docpier.com) while integrating. Keep the Stage server selected in Try It.

Authentication

Authorizationstringheaderrequired

Bearer token. Scope docmind.capture (deprecated idp.capture still accepted).

Path parameters

workspaceIdstringpathrequired

Your Docpier workspace ULID.

Body

multipart/form-data

filefilebodyrequired

PDF, JPEG, PNG, or TIFF. Maximum 200 MB.

extRefstring | nullbody

Partner-supplied stable id for the file (max 70 characters). Echoed in webhooks.

optionsstring | nullbody

JSON string of processing options (ProcessingInstruction). Split, OCR, retention, and related keys: OpenAPI models.

Response

202 returns a documentId used to retrieve results and correlate webhooks.

Then:

GET/v1/workspaces/{workspaceId}/documents/{documentId}

Each extracted document in data[] is typed (INVOICE, RECEIPT, …). See document types.

When processing fails

202 means accepted, not extracted. PROCESSING_FAILED is a domain outcome. GET the document if you need stored status. Do not replay the multipart until you know the file was the problem (a 400 on the original POST is different).

When the file is refused

Docmind judges the file by its bytes, not by its declared content type or extension. A file it cannot process is refused with 400 before anything is stored, and code says why: UNSUPPORTED_FILE_TYPE, PDF_UNREADABLE, PDF_NO_PAGES, PDF_PASSWORD_PROTECTED, PDF_TEXT_TRANSCODED or PDF_CONTENT_UNDECODABLE. The full list is on Errors.

A PDF that arrives with extra bytes in front of its header, for example a wrapped HTTP response, is accepted without those bytes. The document then carries the warning PDF_PREFIX_STRIPPED in process.warnings, whose meta holds the hash and size of the file as it was sent.

Dedupe on webhookId. Envelope: Webhooks.

Request

cURL

curl -X POST 'https://idp-stage.docpier.com/api/v1/workspaces/$WORKSPACE_ID/documents' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F 'file=@./invoice_123.pdf;type=application/pdf' \
  -F 'extRef=INV-2025-001'

Python

import requests

resp = requests.post(
    f"https://idp-stage.docpier.com/api/v1/workspaces/{workspace_id}/documents",
    headers={"Authorization": f"Bearer {access_token}"},
    files={"file": ("invoice_123.pdf", open("invoice_123.pdf", "rb"), "application/pdf")},
    data={"extRef": "INV-2025-001"},
)
print(resp.json())

Response

202

{
    "documentId": "01HXYZ987654321FEDCBA",
    "workspaceId": "04HXYZ123456789ABCDEF",
    "status": "PROCESSING"
}

400

{
    "code": "PDF_PASSWORD_PROTECTED",
    "message": "The PDF is password protected."
}

401

Empty body. Refresh the token; do not parse JSON.