SIGN IT - How to add an additional level to your structure – fiskaly-support (EN)

Which SIGN IT API version are you on?

From SIGN IT 2026-02-03 onwards, the structure is: Organization::ACCOUNT → Organization::GROUP (required) → Organization::UNIT.

Up to SIGN IT 2025-08-12, the structure is: Asset::TENANT → Asset::GROUP (optional) → Asset::UNIT.

Scroll to the section that matches your integration below.

From SIGN IT 2026-02-03 onwards

By default, your integration needs your Organization::ACCOUNT and an Organization::GROUP (required) — both created via the fiskaly HUB — and Organization::UNITs representing each of your clients, created via the SIGN IT API.

In most cases, a single Group per country is sufficient (e.g. if you intend to support fiscalization in Italy and France, you may create one Organization::GROUP for Italy and one for France).

However, if your internal organization needs a further level of structuring within a country — for example, to separate taxpayers by brand, region, etc. — you can add an additional level by creating a sub-group (a Group nested inside another Group).

Account (main organization)
  |
  +-- Group ("France")
  |     |
  |     +-- Unit ("taxpayer 1")
  |
  +-- Group ("Italy")
        |
        +-- Sub-group ("Brand A")
        |     |
        |     +-- Unit ("taxpayer 2")
        |     +-- Unit ("taxpayer 3")
        |
        +-- Sub-group ("Brand B")
              |
              +-- Unit ("taxpayer 4")

Note: Currently, sub-groups can only be created via API. Support for creating sub-groups directly from the fiskaly HUB may be introduced in future releases. However, once created, sub-groups are already visible in the HUB.

Important: Once an Organization has been created, its placement in the structure cannot be changed. For example, a Unit created directly under the parent Group cannot later be moved under a Sub-group, and vice versa.

Step-by-step guide

Call createOrganization with type: GROUP, authenticating with the bearer token of the parent Group (the one created via the fiskaly HUB). The Group ID is returned in content.id
```
{
 "content": {
   "type": "GROUP",
   "name": "name-your-sub-group-here"
 }
}
```
Call createOrganization with type: UNIT, making sure to set the sub-group's ID (from step 1) as the X-Scope-Identifier header. This ensures the Unit is created directly under the Sub-group.

Note: If X-Scope-Identifier is not provided, the Organization::UNIT is created directly under the parent Group (the one created via the fiskaly HUB) by default, via the bearer token used.

Up to SIGN IT 2025-08-12

By default, your integration only needs your main organization (created via the fiskaly dashboard) and Asset::UNITs representing each of your clients (created via the SIGN IT API).

If your structure requires more flexibility, you can introduce an optional intermediate layer, Asset::GROUP, to organize multiple Asset::UNITs into logical groupings.

Tenant (main organization)
  |
  +-- Group (optional layer)
  |     |
  |     +-- Unit ("taxpayer 1")
  |     +-- Unit ("taxpayer 2")
  |
  +-- Unit ("taxpayer 3")
  |     
  +-- Unit ("taxpayer 4")

Important: Once an Asset has been created, its placement in the structure cannot be changed. For example, a Unit created directly under the main organization (Tenant) cannot later be moved under a Group, and vice versa.

Step-by-step guide

Call createAsset with type: GROUP, authenticating with the bearer token of the main organization (the one created via the fiskaly Dashboard). The Group ID is returned in content.id
```
{
 "content": {
   "type": "GROUP",
   "name": "name-your-asset-group-here"
 }
}
```
Call createAsset with type: UNIT, making sure to set the Asset::GROUP ID (from step 1) as the X-Scope-Identifier header. This ensures the Unit is created directly under the Group.

Note: If X-Scope-Identifier is not provided, the Asset::UNIT is nested directly under the main organization (Asset::TENANT) by default, via the bearer token used.

To learn more about the terminology and structure changes between versions, see: SIGN IT: New Resource Terminology.