Skip to main content

Conventions

Shared rules for Docmind and Docbooks. Product pages add only what is unique.

Versioning​

Public HTTP paths use /v1 (Docmind) and /api/docbooks/v1 (Docbooks). Additive, backwards-compatible changes land in the same major. Breaking changes get a new major and a new OpenAPI file under docs/api/openapi/released/.

Ids​

Docpier ids are 26-character ULIDs. Treat them as opaque strings (do not parse timestamp from them in production logic).

Your stable ids go in extRef (idempotent create where documented). Docmind extract extRef max 70 characters. Docbooks organisation uid is ^CHE\d{9}$ in addition to extRef.

Docbooks writes require actor (extRef, email, name) — that is your user, not a Docpier login.

Async jobs​

Writes that start processing return 202 and an id. Completion is a webhook, then GET. Do not poll. 202 means accepted, not succeeded.

Idempotency​

Reuse extRef when you retry a create after a network timeout. If the job already exists, you get the existing id rather than a second document or organisation (where the operation is documented as idempotent).

Dedupe inbound webhooks on webhookId. Retries reuse the same business event with a new attempt id.

Lists​

page (0-based, default 0), size (default 20, max 100), optional sort=field,asc.

{
    "data": [],
    "pagination": {
        "pageNumber": 0,
        "pageSize": 10,
        "totalElements": 123,
        "totalPages": 13,
        "first": true,
        "last": false,
        "numberOfElements": 10
    }
}

There is no cursor pagination on the released contracts.

JSON, XML, files​

Default is application/json; charset=utf-8. Docmind GET document also accepts Accept: application/xml.

Uploads: PDF, JPEG, PNG, TIFF. Docmind extract max 200 MB. Multipart fields that carry structured options (options, Docbooks metadata) are JSON strings, not nested multipart parts.

Missing option blocks default to off.

Time and numbers​

Timestamps are ISO 8601 with timezone (usually Z). Calendar dates on documents (documentDate, dueDate) are YYYY-MM-DD in the document’s own calendar — not converted to the caller’s TZ.

Amounts are decimal numbers plus an ISO currency code. Confidence, where present, is 0.0–1.0.

Errors​

See Errors. 401 and 403 have an empty body. Branch on code for other 4xx/5xx JSON.

Rate limits​

Stage 20 req/min, production 100 req/min. 429 + RATE_LIMITED; honour Retry-After. Remaining budget: X-Rate-Limit-Remaining.

Security​

TLS 1.2+ on production. Tokens in Authorization: Bearer. Secrets never in query strings. Processing and storage: Switzerland (see product site). You are the controller of your customer relationship; Docpier is the processor of the files you send.