Skip to main content

​
Definition

A folder represents a single legal entity within an accounting system. It is the top-level container for all accounting data of a specific business — its chart of accounts, journals, bookyears, and transactions.

​
Purpose

Folders provide the highest level of data segregation. They let you manage multiple companies or business units through a single API integration.

​
Relationships

  • Each folder contains one or more bookyears.
  • Serves as the root container for all accounting data of a specific business entity.

​
Endpoints

​
Multi-folder support

The multi-folder feature allows a single consumer connection to access and manage multiple folders/entities. This is typically useful for accountants managing several clients.

​
How it works

  1. Regular mode (single-folder)
    • Enabled by default. No setup needed.
    • A connection is linked to one folder (selected during connector activation).
    • The folder_id query parameter is ignored.
    • All API calls operate on this single folder.
  2. Multi-folder mode
    • Allows a consumer to manage multiple legal entities.
    • Each API request MUST include a folder_id query parameter to specify the target folder (except for the GET folders endpoint).
    • This ensures full data segregation and prevents cross-entity issues.

​
Activation & configuration

To enable multi-folder mode in a connector (if supported): SCR 20251002 Jbhj Pn
  1. Uncheck the first checkbox, usually labeled “Let the user specify the folder during activation”. Once unchecked:
    • The connection is automatically granted access to all folders the end-user has permission to access.
    • You fully control folder switching from your interface, rather than relying on Chift to enforce folder restrictions.
  2. The second checkbox (if present) is optional and used only by certain connectors (e.g., MyUnisoft) to allow end-users to select folders during activation.
    • This selection is purely UI-level; it does not actually restrict access if multi-folder is enabled.
    • However, Chift automatically blocks API calls to folders that were not selected.

​
Important notes

  • Not all connectors support multi-folder. Check the connector’s documentation page to confirm compatibility.
  • Your implementation must support both modes (single and multi-folder) for full compatibility.
  • Additional dev work is required to integrate multi-folder support.

​
Implementation guide

  • Retrieve available folders — Use GET /folders to list all folders linked to the connection. Each one represents a legal entity.
  • Map folder IDs internally — Create a mapping between each folder_id and its corresponding legal entity in your system. When an end-user selects “Company X,” your API calls should use its folder_id.
  • One folder = one legal entity — Do not merge data between folders or assume shared context. Each folder is fully isolated (chart of accounts, transactions, etc.).