Extract a document

This is the Docmind core: send a business document, get structured data back. Product-wise it is capture (classify + 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

Authorizationstringrequired

Bearer token. Scope docmind.capture (today request idp.capture).

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 (INVALID_FILE on the original POST is different).

Dedupe on webhookId. Envelope: Webhooks.

Request
cURL
Python
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'
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

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

{
    "code": "INVALID_FILE",
    "message": "The uploaded file is not a valid PDF."
}

Authentication​

Path parameters​

Body​

Response​

When processing fails​

Authentication

Path parameters

Body

Response

When processing fails