Dimensions

Retrieves all dimension categories and their values for your company.

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": [] }
        ]
      }
    ]
  }
]

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

Request Body

Field	Type	Required	Description
name	string	Yes	Display name (2-100 characters, must be unique)
isUnique	boolean	Yes	Whether only one value can be assigned per journal entry

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
}

Retrieves a specific dimension category and all its values.

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

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

Field	Type	Required	Description
name	string	No	New display name (2-100 characters, must be unique)
isUnique	boolean	No	New uniqueness constraint

Example

Code
{
  "name": "Business Unit"
}

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

Creates a new dimension value within an existing dimension category.

Request Body

Field	Type	Required	Description
dimensionId	string (UUID)	Yes	The dimension category ID this value belongs to
name	string	Yes	Display name (2-120 characters, must be unique within category)
parentId	string (UUID)	No	Parent value ID for hierarchical structures

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"
}

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

Field	Type	Required	Description
name	string	No	New display name (2-120 characters, must be unique within category)
parentId	string (UUID) or null	No	New parent value ID, or null for root level

Example - Rename

Code
{
  "name": "Northern Europe"
}

Example - Move to Root

Code
{
  "parentId": null
}

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