Propose a booking

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 runs the analysis behind the scenes — it forwards your Bearer token, which must carry docmind.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

Two things must be true before the first booking. The workspace must be provisioned against an extraction workspace (unprovisioned → 409), and it must have an effective chart of accounts, its own or its organisation's (none → 400). Use the Docbooks workspace id from onboarding, not a Docmind workspaceId. Chart of accounts and settings · Combine analysis and booking.

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

Authentication

Authorizationstringrequired

Bearer token with scopes docbooks.bookings and capture (docmind.capture / deprecated idp.capture). Submit requires both on either path, even the pre-extracted one; the token is only forwarded to the extractor on the file path.

Path

workspace_idstring (ULID)pathrequired

Docbooks workspace.

Multipart

Send exactly one of file or extraction.

filefilebody

PDF or image to book. Docbooks forwards it to the extractor for OCR and extraction. Over the upload limit (200 MB) is 413 FILE_TOO_LARGE; anything other than a PDF or image is 415 UNSUPPORTED_MEDIA_TYPE.

extractionstring (JSON)body

A Docmind DocumentResponse you already hold, as JSON. Docbooks parses it and skips docmind entirely — no upload, no OCR wait. An invalid or unbookable extraction is a 400. Sending both parts, or neither, is 400 INVALID_SUBMISSION.

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}

The GET needs the same two scopes as submit — Docbooks reads the extraction from Docmind with your token. Optional query include=extraction embeds the raw extraction on each record.

The report carries a job-level status and one BookingRecord per document in data — one for a single upload, several when the upload was split.

`status`	What it means	What you do
`QUEUED`	Accepted, not started.	Wait for the webhook.
`RUNNING`	Extraction or generation in flight.	Wait for the webhook.
`COMPLETED`	Balanced booking, no open questions.	Post it, or show it for a one-click confirm.
`REVIEW_REQUIRED`	A booking exists but something needs a human — see `reviewReasons`.	Route to review.
`FAILED`	No booking was produced — see `error`.	Do not retry blindly; fix the input or the chart.

Each record also carries the same states in its own status, plus reviewReasons (empty when COMPLETED) and reasoning (confidence 0–1, explanation, appliedRules). Postings get a status and vatAccountable of their own, so one weak posting does not hold back its siblings.

A posting's bookingText reads [document type] [sender] [MM.YY] [largest line item] — the document type in German (Rechnung, Gutschrift, Beleg), the line item cut at its first ( — and leaves out any part the document lacks. Its vatCode comes from the revenue and expense accounts it books, plus the VAT leg under vatPosting: EXTRA; a Kreditoren or bank counter leg never decides it. The code is UNKNOWN when those accounts carry no code, when they carry conflicting codes, or when a NONE account books a document that carries VAT — in the last two cases the posting's reasoning.explanation says why.

discarded lists the posting groups that did not make it into postings — empty when nothing was dropped. Each entry has a reason (AMOUNT_UNDETERMINED, VAT_LEG_SHAPE_INVALID, LEGS_UNRESOLVED, LOW_CONFIDENCE) and either the proposedLegs that never resolved to an account on your chart, or the posting that scored below the confidence floor. Show it in the review lane so no part of the document disappears silently. A non-empty discarded always holds the booking at REVIEW_REQUIRED — even when the remaining postings balance and reconcile — with error.code POSTING_GROUP_DISCARDED unless a stronger reason already applies.

Every booking is reconciled against the document's own total. When that total cannot be read, the record is REVIEW_REQUIRED with error.code TOTAL_UNVERIFIABLE; when the postings do not add up to it, AGGREGATE_MISMATCH.

Tip

List bookings: GET /api/docbooks/v1/workspaces/{workspace_id}/bookings (pagination envelope; each item is a full job report).

Note

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

Request

cURL
Pre-extracted
Python

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"}'

Already hold a Docmind DocumentResponse? Send it instead of the file and Docbooks skips the analysis step.

curl -X POST "https://stage.docpier.io/api/docbooks/v1/workspaces/$DOCBOOKS_WORKSPACE_ID/bookings" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "extraction=$(cat ./document-response.json)" \
  -F 'metadata={"actor":{"extRef":"partner-user-01HXYZ"},"extRef":"INV-2025-001"}'

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
GET report
400
409
401

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

{
    "bookingJobId": "01HXYZBOOKING0000000001",
    "workspaceId": "01HXYZDOCBOOKSWS0000001",
    "status": "COMPLETED",
    "createdAt": "2025-01-15T10:40:00.000Z",
    "extRef": "INV-2025-001",
    "data": [
        {
            "bookingId": "01HXYZRECORD00000000001",
            "status": "COMPLETED",
            "reviewReasons": [],
            "discarded": [],
            "document": {
                "documentType": "INVOICE",
                "documentDate": "2025-01-12",
                "sender": { "name": "Muster AG" }
            },
            "postings": [
                {
                    "status": "COMPLETED",
                    "bookingText": "Rechnung Muster AG 01.25 Büromaterial",
                    "isBalanced": true,
                    "vatAccountable": true,
                    "vatCode": "UNKNOWN",
                    "debit": [
                        {
                            "number": 6500,
                            "amount": { "currency": "CHF", "value": 1000.0 },
                            "vatAmount": { "currency": "CHF", "value": 81.0 }
                        }
                    ],
                    "credit": [
                        {
                            "number": 2000,
                            "amount": { "currency": "CHF", "value": 1081.0 }
                        }
                    ],
                    "reasoning": { "confidence": 0.94 }
                }
            ],
            "reasoning": {
                "confidence": 0.94,
                "explanation": "Supplier invoice for office supplies."
            },
            "versions": { "chartVersion": "acme-2025-01" }
        }
    ]
}

Field-by-field: Docbooks OpenAPI under Schemas → BookingJobReport.

Validation error with a stable code to branch on:

`code`	Cause
`MISSING_CHART_OF_ACCOUNTS`	No effective chart on the workspace or its organisation
`INVALID_SUBMISSION`	Both `file` and `extraction` sent, or neither

An invalid or unbookable extraction is rejected here too.

{
    "code": "MISSING_CHART_OF_ACCOUNTS",
    "message": "workspace 01HXYZDOCBOOKSWS0000001 has no effective chart of accounts"
}

Fix the input — a retry of the same request will fail the same way. Chart of accounts and settings.

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

{
    "code": "WORKSPACE_NOT_LINKED",
    "message": "workspace is not provisioned against an extraction workspace"
}

Treat HTTP 409 as “not provisioned” — retrying will not change it.

Authentication​

Path​

Multipart​

After 202​

Authentication

Path

Multipart

After 202