Dimensions

Retrieves all dimension categories and their values for your company.

Tip: for dimensions with many values (e.g. imported charts), the paginated GET /dimensions/{id}/values returns the same values as a flat set with parentId for rebuilding the hierarchy, without shipping every dimension's full tree in one payload.

Response Structure

Each dimension includes:

• id: Unique identifier for the dimension category
• name: Display name (e.g., "Department", "Project")
• isUnique: Whether only one value can be assigned per journal entry
• values: Tree of dimension values with hierarchical structure

Value Hierarchy

Values are returned as a nested tree structure:

• Root values have parentId: null
• Nested values reference their parent via parentId
• children array contains nested values

Performance

Results are cached for 5 seconds to improve performance. Changes via POST/PUT/DELETE endpoints automatically invalidate the cache.

Example Response

Code
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Department",
    "isUnique": true,
    "values": [
      {
        "id": "...",
        "name": "Sales",
        "parentId": null,
        "children": [
          { "id": "...", "name": "Sales Europe", "parentId": "...", "children": [] }
        ]
      }
    ]
  }
]

Required Scope

• dimensions-read

Creates a new dimension category (e.g., "Department", "Project", "Cost Center").

Request Body

Uniqueness Flag

Choose the isUnique setting based on your use case:

• isUnique: true - Mutually exclusive categories

  • Example: "Department" - a transaction belongs to exactly one department
  • Journal entry validation will reject multiple values from this category

• isUnique: false - Additive tags

  • Example: "Tags" - a transaction can have multiple descriptive tags
  • Multiple values can be freely assigned

Note: You can change this setting later, but changing from false to true will fail if any journal entries already have multiple values assigned from this category.

Example

Code
{
  "name": "Cost Center",
  "isUnique": true
}

Required Scope

• dimensions-write

Retrieves a specific dimension category and all its values.

Tip: for a dimension with many values, the paginated GET /dimensions/{id}/values returns the same values as a flat set with parentId for rebuilding the hierarchy.

Useful when you need to refresh data for a single dimension after making changes, without fetching all dimensions.

Required Scope

• dimensions-read

Updates an existing dimension category. All fields are optional - only provide fields you want to change.

Updating the Name

Provide a new name to rename the dimension category. The new name must be unique within your company.

Changing the Uniqueness Constraint

From false to true:

• Will fail if any journal entries currently have multiple values from this category
• Before making this change, ensure all journal entries have at most one value assigned
• Error code if failed: JOURNAL_TAG_CATEGORY_UNIQUENESS_CONFLICT

From true to false:

• Always succeeds
• Existing journal entries are unaffected
• Future journal entries can have multiple values

Request Body

Example

Code
{
  "name": "Business Unit"
}

Required Scope

• dimensions-write

Deletes a dimension category. The category must be empty (have no values) before deletion.

Prerequisites

Before deleting a dimension category:

1. Delete all dimension values within the category
2. For hierarchical values, delete children before parents

Cascade Behavior

• Dimension values are NOT automatically deleted
• You must explicitly delete all values first
• This prevents accidental data loss

Error Handling

• If the category has values, returns error code: JOURNAL_TAG_CATEGORY_HAS_TAGS
• If the category doesn't exist, returns error code: JOURNAL_TAG_CATEGORY_NOT_FOUND

Required Scope

• dimensions-write

Lists the distribution keys of a dimension — reusable percentage splits over its values. A document booked with a distribution key on a dimension expands its amount across the key's target values at the stored percentages (six decimal places, largest-remainder rounding: the pieces always sum exactly to the booked amount).

Ad-hoc (one-document) keys are excluded by default — they are transient and system-managed, so they are noise in a catalog sync. Pass includeAdHoc=true to see them; a specific ad-hoc key is always readable by id.

Required Scope

• dimensions-read

Creates a distribution key over this dimension's values. Allocations must reference at least two distinct values of this dimension and their percentages must sum to exactly 100 (up to six decimal places per share).

Reusable vs ad-hoc

• Reusable (default): requires a name; appears in listings and can be applied to any document.
• Ad-hoc (isAdHoc: true): a one-document split. The name is optional — when omitted, the key names itself from its allocations (e.g. 60% Marketing / 40% Sales). Ad-hoc keys are hidden from listings by default and their lifecycle is system-managed: apply the returned id to a draft's tagIds; the key archives when that document posts, is deleted with the draft, and is swept if left orphaned.

Required Scope

• dimensions-write

Retrieves one distribution key with its allocations. Works for ad-hoc keys too — the id returned at creation stays readable while the key exists.

Required Scope

• dimensions-read

Lists a dimension's values as a flat, paginated set, ordered by name. Each value carries its parentId, so hierarchical dimensions can be rebuilt client-side. Prefer this over the embedded values trees on GET /dimensions and GET /dimensions/{id} when a dimension holds many values — the trees ship every value in one payload.

Distribution keys never appear here — a key is a distribution over values, not a value. Manage them via GET /dimensions/{id}/distribution-keys.

Required Scope

• dimensions-read

Creates a new dimension value within an existing dimension category.

Request Body

Creating Hierarchical Values

Dimension values can be nested to create hierarchies like "Europe > Denmark > Copenhagen":

1. Create "Europe" without a parentId (root level)
2. Create "Denmark" with parentId = Europe's ID
3. Create "Copenhagen" with parentId = Denmark's ID

Rules:

• Parent must exist within the same dimension category
• No circular references allowed

Example - Root Value

Code
{
  "dimensionId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Europe"
}

Example - Nested Value

Code
{
  "dimensionId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Denmark",
  "parentId": "550e8400-e29b-41d4-a716-446655440001"
}

Required Scope

• dimensions-write

Updates an existing dimension value. All fields are optional - only provide fields you want to change.

Updating the Name

Provide a new name to rename the value. The new name must be unique within the dimension category.

Changing the Parent (Moving in Hierarchy)

Set parentId to move the value within the hierarchy:

• Move to root level: Set parentId: null
• Move under another value: Set parentId to the new parent's ID

Rules:

• New parent must exist within the same dimension category
• Cannot create circular references (A cannot be parent of B if B is already an ancestor of A)
• Moving a value also moves all its children

Request Body

Example - Rename

Code
{
  "name": "Northern Europe"
}

Example - Move to Root

Code
{
  "parentId": null
}

Required Scope

• dimensions-write

Deletes a dimension value. The value must have no children before deletion.

Prerequisites

Before deleting a dimension value:

1. Delete all child values first (if hierarchical)
2. Consider the impact on reporting - historical journal entries keep their assignments

Cascade Behavior

• Child values are NOT automatically deleted
• You must explicitly delete children first (bottom-up deletion)
• Journal entry assignments are automatically removed when the value is deleted

Deletion Order for Hierarchies

For a hierarchy like "Europe > Denmark > Copenhagen":

1. Delete "Copenhagen" first
2. Then delete "Denmark"
3. Finally delete "Europe"

Error Handling

• If the value has children, returns error code: JOURNAL_TAG_HAS_CHILDREN
• If the value doesn't exist, returns error code: JOURNAL_TAG_NOT_FOUND

Required Scope

• dimensions-write