Onboard

WIP

This page is a work in progress — onboarding and offboarding are expected to change before the Management API ships.

Until the Management API ships, Docbooks is how you create the Organisation and Workspace that booking needs. This is setup, not the daily job — the daily job is Propose a booking.

Create Organisations, then POST Workspaces under one. Workspaces are not nested in the organisation body. Scope: docbooks.onboarding and docmind.onboarding — setup only; the runtime scope for booking is docbooks.bookings and docmind.capture.

Both endpoints are batch endpoints: the body is actor plus an array, 1–100 items. There is no single-item form.

POST/api/docbooks/v1/onboarding/organisations

actorobjectbodyrequired

extRef required; email and name optional.

organisationsOrganisationOnboardingItem[]bodyrequired

1–100 organisations.

Each item requires name (1–140), uid (^CHE\d{9}$), and extRef (your stable id, unique per Partner). Optional: address, legalForm, vatRegistrationNumber, and — worth setting now — chartOfAccounts and settings.

Warning

Booking needs an effective chart of accounts — without one it answers 400 MISSING_CHART_OF_ACCOUNTS. You can supply chartOfAccounts here and it is persisted, but in this phase Docpier seeds it for you: agree the client's chart with us as part of onboarding. Chart of accounts and settings.

Then, per organisation:

POST/api/docbooks/v1/onboarding/organisations/{organisation_id}/workspaces

Body is actor plus workspaces (1–100). A workspace item requires only name and extRef; uid is optional here, and chartOfAccounts / settings override the organisation's. Docbooks provisions each workspace in Docmind with your token, which is why the token needs docmind.onboarding.

Reading the outcome

Wait for ONBOARDING_FINALISED, then:

GET/api/docbooks/v1/onboarding/{onboarding_id}

Job status is IN_PROGRESS, COMPLETED, COMPLETED_WITH_ERRORS, or FAILED. Per-item outcomes are in results[], keyed by your extRef, each CREATED, ALREADY_EXISTS, or FAILED (with an error). COMPLETED_WITH_ERRORS is the one to handle — read every item rather than trusting the job status alone.

Re-sending an existing extRef or uid is a no-op, recorded as ALREADY_EXISTS, so a retried batch is safe. Synchronous rejections are 400: BATCH_TOO_LARGE over 100 items, DUPLICATE_IN_BATCH when extRef or uid repeats inside one batch.

Offboard

Same scope. Organisation offboarding cascades to its workspaces; workspace offboarding does not.

POST/api/docbooks/v1/offboarding/organisations

Body: actor, organisationIds (1–100 ULIDs), optional reason (≤500).

POST/api/docbooks/v1/offboarding/workspaces

Body: actor, workspaceIds (1–100 Docbooks ULIDs), optional reason.

Then GET the offboarding job after OFFBOARDING_FINALISED. Per-item status is OFFBOARDED, ALREADY_OFFBOARDED, or FAILED.

Tip

Full bodies: Docbooks OpenAPI.

Request
Onboard org
Onboard workspace
Offboard org
curl -X POST 'https://stage.docpier.io/api/docbooks/v1/onboarding/organisations' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "actor": {
      "extRef": "partner-user-01HXYZ",
      "email": "admin@partner.example",
      "name": "Operations"
    },
    "organisations": [
      {
        "name": "Acme AG",
        "uid": "CHE123456789",
        "extRef": "org-acme",
        "chartOfAccounts": {
          "version": "acme-2025-01",
          "accounts": [
            { "number": 1020, "name": "Bank", "type": "ASSET" },
            { "number": 2000, "name": "Kreditoren", "type": "LIABILITY" },
            { "number": 6500, "name": "Büromaterial", "type": "EXPENSE" }
          ]
        }
      }
    ]
  }'
curl -X POST "https://stage.docpier.io/api/docbooks/v1/onboarding/organisations/$ORG_ID/workspaces" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "actor": { "extRef": "partner-user-01HXYZ" },
    "workspaces": [
      { "name": "Acme AG — Hauptbuch", "extRef": "ws-acme-main" }
    ]
  }'
curl -X POST 'https://stage.docpier.io/api/docbooks/v1/offboarding/organisations' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "actor": { "extRef": "partner-user-01HXYZ" },
    "organisationIds": ["01HXYZORG000000000000001"],
    "reason": "Client left the mandate"
  }'

Response

202
GET report
401

{
    "onboardingId": "01HXYZONBOARDING00000001",
    "status": "IN_PROGRESS",
    "createdAt": "2025-01-15T10:30:00.000Z"
}

Workspace onboarding echoes the parent as organisationId. Offboarding returns offboardingId instead of onboardingId.

{
    "onboardingId": "01HXYZONBOARDING00000001",
    "status": "COMPLETED_WITH_ERRORS",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "finalisedAt": "2025-01-15T10:30:12.000Z",
    "results": [
        {
            "extRef": "org-acme",
            "status": "CREATED",
            "organisationId": "01HXYZORG000000000000001"
        },
        {
            "extRef": "org-duplicate",
            "status": "ALREADY_EXISTS",
            "organisationId": "01HXYZORG000000000000002"
        },
        {
            "extRef": "org-broken",
            "status": "FAILED",
            "error": { "code": "VALIDATION_ERROR", "message": "Invalid UID." }
        }
    ]
}

Reading the outcome​

Offboard​

Reading the outcome

Offboard