Chart of accounts and settings

Docbooks proposes postings against the customer's own accounts, so the chart of accounts is not decoration — it is the prerequisite. A workspace with no effective chart cannot book, and Propose a booking answers 400.

Settings shape how the proposal is formed: VAT method, whether VAT rides as a code or its own leg, summary vs. line-item granularity, currency, language.

Warning

Booking resolves the chart workspace first, then organisation. Set it at onboarding, or with the PUT below, before the first booking.

Who sets it up today

This phase

Docpier currently seeds and maintains the chart of accounts for you, directly against the database, as part of onboarding. Both contract paths below are implemented and work — but coordinate with Docpier rather than assuming a chart is already in place before your first booking.

Two ways in on the contract, and the second replaces the first wholesale:

1. At onboarding — send chartOfAccounts (and optionally settings) on the organisation or workspace item; it is persisted with the item. See Onboard.
2. Later — PUT the whole chart at either level.

PUT/api/docbooks/v1/organisations/{organisation_id}/chart-of-accounts

PUT/api/docbooks/v1/workspaces/{workspace_id}/chart-of-accounts

Both take actor plus a complete chartOfAccounts and answer 200 with the accepted version and updatedAt. There is no partial chart update — send the full set every time.

actorobjectbodyrequired

extRef required; email and name optional.

chartOfAccounts.versionstring (1–64)bodyrequired

Your label for this revision. Stamped on every booking produced against it, as versions.chartVersion on the record — that is how a booking stays reproducible.

chartOfAccounts.accountsAccount[]bodyrequired

At least one account.

An account

numberintegerbodyrequired

Account number, as your ledger knows it.

namestring (1–140)bodyrequired

Display name.

typeenumbodyrequired

ASSET, LIABILITY, EXPENSE, or REVENUE.

vatCodeenumbody

NONE for an account that never carries VAT — the only value accepted until the fixed Swiss VAT-code set is available; any other value is rejected with CHART_OF_ACCOUNTS_INVALID. A posting takes the code of the revenue and expense accounts it books — see Propose a booking. Omit it for an account with no VAT code assigned yet.

currencystring (ISO 4217)body

Per-account currency. Omit to inherit the effective defaultCurrency.

Settings

PATCH/api/docbooks/v1/organisations/{organisation_id}/settings

PATCH/api/docbooks/v1/workspaces/{workspace_id}/settings

Body is actor plus settings. Only the keys you send are written; everything else keeps inheriting Partner → Organisation → Workspace, and falls back to the product default when nothing is set anywhere.

Key	Values	Product default
vatMethod	NONE, EFFECTIVE, FLAT_RATE, EXEMPT	EFFECTIVE
vatPosting	CODE, EXTRA	CODE
vatSettlement	AGREED (vereinbart), COLLECTED (vereinnahmt)	AGREED
bookingLevel	SUMMARY (aggregate by VAT code), LINE_ITEMS	SUMMARY
accountingStandard	OR, SWISS_GAAP_FER, IFRS	OR
accountingType	SUBLEDGER_FULL, SUBLEDGER_CREDIT, SUBLEDGER_DEBIT, OPEN_ITEM	SUBLEDGER_FULL
defaultCurrency	ISO 4217 alpha-3	CHF
language	DE, FR, IT, EN	DE
timezone	IANA name	Europe/Zurich
fiscalYearStart	ISO 8601 date — only month and day matter	1 January
periodAssignment	manual, automatic	automatic
aggregatedDataEnabled	boolean	true

Tip

vatPosting: CODE puts the booked account's vatCode on the posting and leaves the VAT inside the leg amounts. EXTRA gives VAT its own posting leg instead. Pick the one your ledger expects — changing it changes the shape of every later proposal.

Reading it back

GET/api/docbooks/v1/organisations/{organisation_id}

GET/api/docbooks/v1/workspaces/{workspace_id}

Both echo the chartOfAccounts and settings stored at that level. Inheritance is resolved when a booking is submitted, not on these reads — so an empty settings here means "inherits", not "no settings apply".

Request

Replace chart

curl -X PUT "https://stage.docpier.io/api/docbooks/v1/workspaces/$DOCBOOKS_WORKSPACE_ID/chart-of-accounts" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "actor": { "extRef": "partner-user-01HXYZ" },
    "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" },
        { "number": 3000, "name": "Erlöse", "type": "REVENUE" }
      ]
    }
  }'

Patch settings

curl -X PATCH "https://stage.docpier.io/api/docbooks/v1/workspaces/$DOCBOOKS_WORKSPACE_ID/settings" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "actor": { "extRef": "partner-user-01HXYZ" },
    "settings": {
      "vatMethod": "EFFECTIVE",
      "vatPosting": "CODE",
      "bookingLevel": "SUMMARY",
      "defaultCurrency": "CHF"
    }
  }'

Keys you leave out keep inheriting — this is not a wholesale replace.

Response

200

{
    "workspaceId": "01HXYZDOCBOOKSWS0000001",
    "version": "acme-2025-01",
    "updatedAt": "2025-01-15T10:35:00.000Z"
}

401

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