Book a document

This is the Docbooks core. Product-wise: the customer hands you a receipt; you want a posting proposal, not a pile of OCR fields. You POST the file to Docbooks only. Architecturally Docbooks calls Docpier extraction behind the scenes (forwards your Bearer token — must include capture) and then books.

You get 202 with a bookingJobId in QUEUED status. Wait for BOOKING_FINALISED, then GET. Do not POST the file to Docmind first.

POST/api/docbooks/v1/workspaces/{workspace_id}/bookings

Warning

Use the Docbooks workspace id from onboarding, not the Docmind workspaceId from capture. Unprovisioned → 409. Enable capture and booking.

Keep the original file bytes. Booking is always a multipart file POST to Docbooks — never a Docmind documentId.

Authentication

Authorizationstringheaderrequired

Bearer token with scopes docbooks.bookings and capture (docmind.capture / deprecated idp.capture).

Path

workspace_idstring (ULID)pathrequired

Docbooks workspace.

Multipart

filefilebodyrequired

PDF or image to book.

metadatastring (JSON)bodyrequired

JSON object: required actor.extRef; optional extRef; optional processingInstruction (split.enabled, capture forwarded to Docmind as options, optional settings override).

After 202

Wait for BOOKING_FINALISED, then:

GET/api/docbooks/v1/bookings/{booking_job_id}

Optional query include=extraction embeds extraction data when available.

Tip

List bookings: GET /api/docbooks/v1/workspaces/{workspace_id}/bookings (pagination envelope).

Note

If split is enabled on the booking metadata, only the parent job fires the webhook. Children appear on the GET report.

Request

cURL

curl -X POST "https://stage.docpier.io/api/docbooks/v1/workspaces/$DOCBOOKS_WORKSPACE_ID/bookings" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F 'file=@./invoice.pdf;type=application/pdf' \
  -F 'metadata={"actor":{"extRef":"partner-user-01HXYZ"},"extRef":"INV-2025-001"}'

Python

import json
import requests

resp = requests.post(
    f"https://stage.docpier.io/api/docbooks/v1/workspaces/{docbooks_workspace_id}/bookings",
    headers={"Authorization": f"Bearer {access_token}"},
    files={"file": ("invoice.pdf", open("invoice.pdf", "rb"), "application/pdf")},
    data={
        "metadata": json.dumps(
            {
                "actor": {"extRef": "partner-user-01HXYZ"},
                "extRef": "INV-2025-001",
            }
        )
    },
)
print(resp.status_code, resp.json())

Response

202

{
    "bookingJobId": "01HXYZBOOKING0000000001",
    "workspaceId": "01HXYZDOCBOOKSWS0000001",
    "status": "QUEUED",
    "createdAt": "2025-01-15T10:40:00.000Z",
    "extRef": "INV-2025-001"
}

409

Workspace is not provisioned against an extraction workspace. Do not retry with a different id from Docmind unless support has completed provisioning.

{
    "code": "CONFLICT",
    "message": "Workspace is not provisioned for extraction."
}

Exact code / message may vary; treat HTTP 409 as “not provisioned.”

401

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