StabisoDocs

API reference

Dimensions

Cost centres, profit centres and projects: the values postings are analysed by, the accounts that require them, and the results by value.

Operation Summary Scope Idempotency-Key
GET /v1/dimensions List dimensions read
POST /v1/dimensions Add a dimension admin
PATCH /v1/dimensions/{code} Change a dimension admin
PUT /v1/dimensions/{code}/required-accounts Set the accounts that require a dimension admin
POST /v1/dimensions/{code}/values Add a value admin
PATCH /v1/dimensions/{code}/values/{value} Change a value admin
GET /v1/entities/{entity}/reports/dimension-balances Results by cost centre, profit centre or project read
GET /v1/entities/{entity}/reports/dimension-lines The postings of a cost centre, profit centre or project read

GET /v1/dimensions

List dimensions

What the organization analyses its postings by (every organization starts with cost_centre, profit_centre and project), each with its values and the accounts that require it. A journal line or a document line names values as dimensions: {"cost_centre": "CC-100", "project": "P-17"}.
Required scope read (admin implies every scope)
Operation id list_dimensions_v1_dimensions_get

Example request

curl "$ERP_URL/v1/dimensions" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Status Meaning Body
200 OK array of DimensionOut
401 Missing or invalid API key (unauthorized). ErrorEnvelope
403 The caller lacks the required scope (missing_right, with scope), the key belongs to no person where a person is needed (forbidden), or the approval policy denies the action (policy_denied, with action and rule_id). ErrorEnvelope
422 Validation failed: the error envelope (validation_failed). For a malformed body or parameter its message is in sentences ("Line 2: the quantity must be above zero") and fields lists each error with pydantic's loc, type and msg beside its sentence (message) and its parts, to word it in another language: items (name and number from 1: line 2), field (its name as sent) and the rule it breaks with its limit, count and choices (none for a validator's own sentence); FastAPI's own detail list stays beside the envelope. HTTPValidationError

Example response (shape)

[
  {
    "code": "string",
    "name": "string",
    "active": true,
    "values": [
      {
        "code": "string",
        "name": "string",
        "entity": null,
        "valid_from": null,
        "valid_to": null,
        "active": true
      }
    ],
    "required_accounts": [
      {
        "entity": "string",
        "account": "string",
        "name": "string"
      }
    ]
  }
]

POST /v1/dimensions

Add a dimension

Add a dimension, up to five per organization. Refused with 409 dimension_exists for a code that is taken and dimension_limit (max) beyond five. Audited as dimension.create. Every change of dimensions, values and required accounts is refused with 403 when the approval policy denies the action manage_accounts (always for agents).
Required scope admin (admin implies every scope)
Idempotency-Key not used
Operation id create_dimension_v1_dimensions_post

Request body

application/json (required): DimensionInput

Field Type Required Description
code string or null Lower-case letters, digits and _, from 2 to 31 characters, starting with a letter; never changes. Omitted: made from the name (Cost centre is cost_centre). (pattern ^[a-z][a-z0-9_]{1,30}$)
name string yes The name shown on screens, at most 60 characters. (min length 1; max length 60)

Example request

curl -X POST "$ERP_URL/v1/dimensions" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "region",
  "name": "Region"
}'

Responses

Status Meaning Body
201 Created DimensionOut
401 Missing or invalid API key (unauthorized). ErrorEnvelope
403 The caller lacks the required scope (missing_right, with scope), the key belongs to no person where a person is needed (forbidden), or the approval policy denies the action (policy_denied, with action and rule_id). ErrorEnvelope
409 The request conflicts with the data: an Idempotency-Key reused with a different request, a closed period, or an integrity rule of the database (conflict, integrity_violation). ErrorEnvelope
422 Validation failed: the error envelope (validation_failed). For a malformed body or parameter its message is in sentences ("Line 2: the quantity must be above zero") and fields lists each error with pydantic's loc, type and msg beside its sentence (message) and its parts, to word it in another language: items (name and number from 1: line 2), field (its name as sent) and the rule it breaks with its limit, count and choices (none for a validator's own sentence); FastAPI's own detail list stays beside the envelope. HTTPValidationError

Example response (shape)

{
  "code": "string",
  "name": "string",
  "active": true,
  "values": [
    {
      "code": "string",
      "name": "string",
      "entity": "string",
      "valid_from": "2026-09-21",
      "valid_to": "2026-09-21",
      "active": true
    }
  ],
  "required_accounts": [
    {
      "entity": "string",
      "account": "string",
      "name": "string"
    }
  ]
}

PATCH /v1/dimensions/{code}

Change a dimension

Rename a dimension or deactivate it: lines posted with it keep it, new lines may not name it. The code never changes. Audited as dimension.update with the previous values.
Required scope admin (admin implies every scope)
Idempotency-Key not used
Operation id update_dimension_v1_dimensions__code__patch

Parameters

In Name Type Required Description
path code string yes The dimension's code, e.g. cost_centre.

Request body

application/json (required): DimensionUpdate

Field Type Required Description
name string or null A new name; omitted: unchanged. (min length 1; max length 60)
active boolean or null false stops new lines naming it (lines posted with it stay as they are); omitted: unchanged.

Example request

curl -X PATCH "$ERP_URL/v1/dimensions/cost_centre" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Cost centre"
}'

Responses

Status Meaning Body
200 OK DimensionOut
401 Missing or invalid API key (unauthorized). ErrorEnvelope
403 The caller lacks the required scope (missing_right, with scope), the key belongs to no person where a person is needed (forbidden), or the approval policy denies the action (policy_denied, with action and rule_id). ErrorEnvelope
404 The resource does not exist, or belongs to another organization (not_found). ErrorEnvelope
409 The request conflicts with the data: an Idempotency-Key reused with a different request, a closed period, or an integrity rule of the database (conflict, integrity_violation). ErrorEnvelope
422 Validation failed: the error envelope (validation_failed). For a malformed body or parameter its message is in sentences ("Line 2: the quantity must be above zero") and fields lists each error with pydantic's loc, type and msg beside its sentence (message) and its parts, to word it in another language: items (name and number from 1: line 2), field (its name as sent) and the rule it breaks with its limit, count and choices (none for a validator's own sentence); FastAPI's own detail list stays beside the envelope. HTTPValidationError

Example response (shape)

{
  "code": "string",
  "name": "string",
  "active": true,
  "values": [
    {
      "code": "string",
      "name": "string",
      "entity": "string",
      "valid_from": "2026-09-21",
      "valid_to": "2026-09-21",
      "active": true
    }
  ],
  "required_accounts": [
    {
      "entity": "string",
      "account": "string",
      "name": "string"
    }
  ]
}

PUT /v1/dimensions/{code}/required-accounts

Set the accounts that require a dimension

Replace the accounts of one company on which a manual entry, or a document when it is submitted, must give the dimension (422 dimension_required otherwise). Entries made by the system (depreciation, revaluation, bank and payment postings) are never refused for lacking it. Postings made before are not touched. Audited as account_dimension_rule.set with the previous and new accounts.
Required scope admin (admin implies every scope)
Idempotency-Key not used
Operation id set_required_accounts_v1_dimensions__code__required_accounts_put

Parameters

In Name Type Required Description
path code string yes The dimension's code, e.g. cost_centre.

Request body

application/json (required): RequiredAccountsInput

Field Type Required Description
entity string yes Code of the company whose accounts these are.
accounts array of string yes Every account of the company that requires the dimension, by code: the list replaces the one before; empty: none.

Example request

curl -X PUT "$ERP_URL/v1/dimensions/cost_centre/required-accounts" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "accounts": [
    "6000",
    "6500"
  ],
  "entity": "CH01"
}'

Responses

Status Meaning Body
200 OK DimensionOut
401 Missing or invalid API key (unauthorized). ErrorEnvelope
403 The caller lacks the required scope (missing_right, with scope), the key belongs to no person where a person is needed (forbidden), or the approval policy denies the action (policy_denied, with action and rule_id). ErrorEnvelope
404 The resource does not exist, or belongs to another organization (not_found). ErrorEnvelope
409 The request conflicts with the data: an Idempotency-Key reused with a different request, a closed period, or an integrity rule of the database (conflict, integrity_violation). ErrorEnvelope
422 Validation failed: the error envelope (validation_failed). For a malformed body or parameter its message is in sentences ("Line 2: the quantity must be above zero") and fields lists each error with pydantic's loc, type and msg beside its sentence (message) and its parts, to word it in another language: items (name and number from 1: line 2), field (its name as sent) and the rule it breaks with its limit, count and choices (none for a validator's own sentence); FastAPI's own detail list stays beside the envelope. HTTPValidationError

Example response (shape)

{
  "code": "string",
  "name": "string",
  "active": true,
  "values": [
    {
      "code": "string",
      "name": "string",
      "entity": "string",
      "valid_from": "2026-09-21",
      "valid_to": "2026-09-21",
      "active": true
    }
  ],
  "required_accounts": [
    {
      "entity": "string",
      "account": "string",
      "name": "string"
    }
  ]
}

POST /v1/dimensions/{code}/values

Add a value

Add a value to a dimension (a cost centre, a profit centre, a project), for every company or one (entity), and from and until when lines may name it. Refused with 409 dimension_value_exists for a code that is taken. Audited as dimension_value.create.
Required scope admin (admin implies every scope)
Idempotency-Key not used
Operation id add_value_v1_dimensions__code__values_post

Parameters

In Name Type Required Description
path code string yes The dimension's code, e.g. cost_centre.

Request body

application/json (required): ValueInput

Field Type Required Description
code string or null Letters, digits, ., _ and -, at most 31 characters; never changes. Omitted: made from the name (Sales Zurich is SALES-ZURICH). (pattern ^[A-Za-z0-9][A-Za-z0-9._-]{0,30}$)
name string yes The name shown on screens and reports. (min length 1; max length 120)
entity string or null Code of the only company that may use it; omitted: every one.
valid_from string (date) or null First day lines may name it.
valid_to string (date) or null Last day lines may name it.

Example request

curl -X POST "$ERP_URL/v1/dimensions/cost_centre/values" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "CC-100",
  "name": "Sales Zurich"
}'

Responses

Status Meaning Body
201 Created DimensionOut
401 Missing or invalid API key (unauthorized). ErrorEnvelope
403 The caller lacks the required scope (missing_right, with scope), the key belongs to no person where a person is needed (forbidden), or the approval policy denies the action (policy_denied, with action and rule_id). ErrorEnvelope
404 The resource does not exist, or belongs to another organization (not_found). ErrorEnvelope
409 The request conflicts with the data: an Idempotency-Key reused with a different request, a closed period, or an integrity rule of the database (conflict, integrity_violation). ErrorEnvelope
422 Validation failed: the error envelope (validation_failed). For a malformed body or parameter its message is in sentences ("Line 2: the quantity must be above zero") and fields lists each error with pydantic's loc, type and msg beside its sentence (message) and its parts, to word it in another language: items (name and number from 1: line 2), field (its name as sent) and the rule it breaks with its limit, count and choices (none for a validator's own sentence); FastAPI's own detail list stays beside the envelope. HTTPValidationError

Example response (shape)

{
  "code": "string",
  "name": "string",
  "active": true,
  "values": [
    {
      "code": "string",
      "name": "string",
      "entity": "string",
      "valid_from": "2026-09-21",
      "valid_to": "2026-09-21",
      "active": true
    }
  ],
  "required_accounts": [
    {
      "entity": "string",
      "account": "string",
      "name": "string"
    }
  ]
}

PATCH /v1/dimensions/{code}/values/{value}

Change a value

Rename a value, change the days lines may name it, or deactivate it. Lines posted with it keep it; its code, dimension and company never change, and it is never deleted. Refused with 422 end_before_start. Audited as dimension_value.update with the previous values.
Required scope admin (admin implies every scope)
Idempotency-Key not used
Operation id update_value_v1_dimensions__code__values__value__patch

Parameters

In Name Type Required Description
path code string yes The dimension's code, e.g. cost_centre.
path value string yes The value's code, e.g. CC-100.

Request body

application/json (required): ValueUpdate

Field Type Required Description
name string or null A new name; omitted: unchanged. (min length 1; max length 120)
valid_from string (date) or null A new first day; omitted: unchanged.
valid_to string (date) or null A new last day; omitted: unchanged.
active boolean or null false stops new lines naming it; lines posted with it stay as they are.

Example request

curl -X PATCH "$ERP_URL/v1/dimensions/cost_centre/values/CC-100" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "valid_to": "2026-12-31"
}'

Responses

Status Meaning Body
200 OK DimensionOut
401 Missing or invalid API key (unauthorized). ErrorEnvelope
403 The caller lacks the required scope (missing_right, with scope), the key belongs to no person where a person is needed (forbidden), or the approval policy denies the action (policy_denied, with action and rule_id). ErrorEnvelope
404 The resource does not exist, or belongs to another organization (not_found). ErrorEnvelope
409 The request conflicts with the data: an Idempotency-Key reused with a different request, a closed period, or an integrity rule of the database (conflict, integrity_violation). ErrorEnvelope
422 Validation failed: the error envelope (validation_failed). For a malformed body or parameter its message is in sentences ("Line 2: the quantity must be above zero") and fields lists each error with pydantic's loc, type and msg beside its sentence (message) and its parts, to word it in another language: items (name and number from 1: line 2), field (its name as sent) and the rule it breaks with its limit, count and choices (none for a validator's own sentence); FastAPI's own detail list stays beside the envelope. HTTPValidationError

Example response (shape)

{
  "code": "string",
  "name": "string",
  "active": true,
  "values": [
    {
      "code": "string",
      "name": "string",
      "entity": "string",
      "valid_from": "2026-09-21",
      "valid_to": "2026-09-21",
      "active": true
    }
  ],
  "required_accounts": [
    {
      "entity": "string",
      "account": "string",
      "name": "string"
    }
  ]
}

GET /v1/entities/{entity}/reports/dimension-balances

Results by cost centre, profit centre or project

Revenue, expenses and result of the posted entries dated from start to end, per value of the dimension, with the accounts behind each, in the company's functional currency. Lines that name no value are a row of their own, so the rows add up to the profit and loss report of the range; year-end closing entries are left out as there.
Required scope read (admin implies every scope)
Operation id dimension_report_v1_entities__entity__reports_dimension_balances_get

Parameters

In Name Type Required Description
path entity string yes Entity code, e.g. CH01 (GET /v1/entities).
query dimension string yes The dimension's code, e.g. cost_centre.
query start string (date) yes First day of the range, ISO 8601.
query end string (date) yes Last day of the range, ISO 8601, included.

Example request

curl "$ERP_URL/v1/entities/CH01/reports/dimension-balances?dimension=cost_centre&start=2026-09-01&end=2026-09-30" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Status Meaning Body
200 OK DimensionReport
401 Missing or invalid API key (unauthorized). ErrorEnvelope
403 The caller lacks the required scope (missing_right, with scope), the key belongs to no person where a person is needed (forbidden), or the approval policy denies the action (policy_denied, with action and rule_id). ErrorEnvelope
404 The resource does not exist, or belongs to another organization (not_found). ErrorEnvelope
422 Validation failed: the error envelope (validation_failed). For a malformed body or parameter its message is in sentences ("Line 2: the quantity must be above zero") and fields lists each error with pydantic's loc, type and msg beside its sentence (message) and its parts, to word it in another language: items (name and number from 1: line 2), field (its name as sent) and the rule it breaks with its limit, count and choices (none for a validator's own sentence); FastAPI's own detail list stays beside the envelope. HTTPValidationError

Example response (shape)

{
  "entity": "string",
  "currency": "string",
  "dimension": "string",
  "start": "2026-09-21",
  "end": "2026-09-21",
  "rows": [
    {
      "value": "string",
      "name": "string",
      "revenue": "string",
      "expenses": "string",
      "result": "string",
      "accounts": [
        null
      ]
    }
  ],
  "revenue": "string",
  "expenses": "string",
  "result": "string"
}

GET /v1/entities/{entity}/reports/dimension-lines

The postings of a cost centre, profit centre or project

The posted profit and loss lines behind a row of the results by dimension: those that name the value (or none), of one account or every one, by date and posting order.
Required scope read (admin implies every scope)
Operation id dimension_lines_v1_entities__entity__reports_dimension_lines_get

Parameters

In Name Type Required Description
path entity string yes Entity code, e.g. CH01 (GET /v1/entities).
query dimension string yes The dimension's code, e.g. cost_centre.
query value string or null The value's code, e.g. CC-100; omitted: the lines that name none.
query account string or null Only this account, e.g. 6000.
query start string (date) yes First day of the range, ISO 8601.
query end string (date) yes Last day of the range, ISO 8601, included.

Example request

curl "$ERP_URL/v1/entities/CH01/reports/dimension-lines?dimension=cost_centre&start=2026-09-01&end=2026-09-30" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Status Meaning Body
200 OK DimensionLines
401 Missing or invalid API key (unauthorized). ErrorEnvelope
403 The caller lacks the required scope (missing_right, with scope), the key belongs to no person where a person is needed (forbidden), or the approval policy denies the action (policy_denied, with action and rule_id). ErrorEnvelope
404 The resource does not exist, or belongs to another organization (not_found). ErrorEnvelope
422 Validation failed: the error envelope (validation_failed). For a malformed body or parameter its message is in sentences ("Line 2: the quantity must be above zero") and fields lists each error with pydantic's loc, type and msg beside its sentence (message) and its parts, to word it in another language: items (name and number from 1: line 2), field (its name as sent) and the rule it breaks with its limit, count and choices (none for a validator's own sentence); FastAPI's own detail list stays beside the envelope. HTTPValidationError

Example response (shape)

{
  "entity": "string",
  "currency": "string",
  "dimension": "string",
  "value": "string",
  "start": "2026-09-21",
  "end": "2026-09-21",
  "lines": [
    {
      "entry_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "number": "string",
      "entry_date": "2026-09-21",
      "description": "string",
      "line_description": "string",
      "account": "string",
      "account_name": "string",
      "currency": "string",
      "amount": "string",
      "debit": "string",
      "credit": "string",
      "dimensions": {}
    }
  ]
}

Schemas

DimensionAccount

Field Type Required Description
code string yes Account code.
name string yes Account name in the user's language.
type string yes revenue or expense.
debit string yes Debits in the range, functional currency.
credit string yes Credits in the range, functional currency.
balance string yes The movement in the account's normal direction (credit for revenue, debit for expenses).

DimensionInput

Field Type Required Description
code string or null Lower-case letters, digits and _, from 2 to 31 characters, starting with a letter; never changes. Omitted: made from the name (Cost centre is cost_centre). (pattern ^[a-z][a-z0-9_]{1,30}$)
name string yes The name shown on screens, at most 60 characters. (min length 1; max length 60)

DimensionLine

Field Type Required Description
entry_id string (uuid) yes The journal entry (GET /v1/journal-entries/{id}).
number string or null yes The entry's number.
entry_date string (date) yes The entry's date.
description string yes The entry's description.
line_description string or null yes The line's own text; null when none.
account string yes The line's account code.
account_name string yes The account's name in the user's language.
currency string yes The currency the line was booked in.
amount string yes Debit less credit in that currency.
debit string yes Debit in the functional currency.
credit string yes Credit in the functional currency.
dimensions map of string yes Every dimension the line names.

DimensionLines

Field Type Required Description
entity string yes Code of the company.
currency string yes Its functional currency.
dimension string yes The dimension.
value string or null yes The value; null: the lines that name none.
start string (date) yes First day of the range.
end string (date) yes Last day of the range, included.
lines array of DimensionLine yes The posted profit and loss lines, by date and posting order.

DimensionOut

Field Type Required Description
code string yes The dimension's code, as lines name it: cost_centre, profit_centre, project, or one the organization added.
name string yes The dimension's name.
active boolean yes Whether new lines may name it.
values array of ValueOut yes Its values, by code, the inactive ones too.
required_accounts array of RequiredAccount yes The accounts on which a manual entry or a document must give it.

DimensionReport

Field Type Required Description
entity string yes Code of the company.
currency string yes Its functional currency, which every amount is in.
dimension string yes The dimension reported by.
start string (date) yes First day of the range.
end string (date) yes Last day of the range, included.
rows array of DimensionRow yes One row per value with postings in the range, by code, then the row of lines that name no value (value null).
revenue string yes Total revenue: that of the profit and loss report.
expenses string yes Total expenses: that of the profit and loss report.
result string yes Revenue less expenses: the net income of the range.

DimensionRow

Field Type Required Description
value string or null yes The value's code; null for lines that name none.
name string or null yes The value's name; null for lines that name none.
revenue string yes Revenue of the lines that name it.
expenses string yes Expenses of the lines that name it.
result string yes Revenue less expenses.
accounts array of DimensionAccount yes The accounts it moved, by code.

DimensionUpdate

Field Type Required Description
name string or null A new name; omitted: unchanged. (min length 1; max length 60)
active boolean or null false stops new lines naming it (lines posted with it stay as they are); omitted: unchanged.

RequiredAccount

Field Type Required Description
entity string yes Code of the company the account belongs to.
account string yes Code of the account, e.g. 6000.
name string yes The account's name in the user's language.

RequiredAccountsInput

Field Type Required Description
entity string yes Code of the company whose accounts these are.
accounts array of string yes Every account of the company that requires the dimension, by code: the list replaces the one before; empty: none.

ValueInput

Field Type Required Description
code string or null Letters, digits, ., _ and -, at most 31 characters; never changes. Omitted: made from the name (Sales Zurich is SALES-ZURICH). (pattern ^[A-Za-z0-9][A-Za-z0-9._-]{0,30}$)
name string yes The name shown on screens and reports. (min length 1; max length 120)
entity string or null Code of the only company that may use it; omitted: every one.
valid_from string (date) or null First day lines may name it.
valid_to string (date) or null Last day lines may name it.

ValueOut

Field Type Required Description
code string yes The value's code, as lines name it, e.g. CC-100.
name string yes The value's name, e.g. Sales Zurich.
entity string or null yes Code of the only company that may use it; null: every company.
valid_from string (date) or null yes First day lines may name it; null: no limit.
valid_to string (date) or null yes Last day lines may name it; null: no limit.
active boolean yes Whether new lines may name it.

ValueUpdate

Field Type Required Description
name string or null A new name; omitted: unchanged. (min length 1; max length 120)
valid_from string (date) or null A new first day; omitted: unchanged.
valid_to string (date) or null A new last day; omitted: unchanged.
active boolean or null false stops new lines naming it; lines posted with it stay as they are.
Stabiso, the Enterprise System of Record · generated from the code and its guides · release 20b7dd5b0c4d