List or create dimensions
API Documentation / Resources / Dimensions
List dimensions
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/dimensions
Required OAuth scope: dimensions:read
Lists the analytical dimensions available to the subsidiary, including definitions inherited from parent subsidiaries.
Query behavior
| Parameter | Meaning | Default |
|---|---|---|
active |
Filter active or inactive definitions | All |
updated_since |
Return records updated at or after an RFC 3339 timestamp | Unbounded |
page |
Positive page number | 1 |
per_page |
Records per page from 1 to 100 | 30 |
Dimensions are ordered by index ASC, then stable resource order.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | UUID of the authorized company group. |
subsidiary_id |
path | Yes | string (uuid) | UUID of the subsidiary whose books contain the bank account. |
active |
query | No | boolean | Filter by active state. |
updated_since |
query | No | string (date-time) | Return resources updated at or after this RFC 3339 timestamp. |
page |
query | No | integer | |
per_page |
query | No | integer |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/dimensions HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
A page of dimensions. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks the required scope or granted accounting context. |
422 |
One or more supplied values failed validation. |
200 example
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"id": "4c447a9e-e823-41bf-88c9-98b7015d228c",
"name": "Department",
"index": 1,
"active": true,
"inherited": false,
"created_at": "2026-08-10T14:30:00Z",
"updated_at": "2026-08-10T14:30:00Z"
}
],
"meta": {
"current_page": 1,
"per_page": 30,
"last_page": 1,
"total": 1
}
}
Create a dimension
POST /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/dimensions
Required OAuth scope: dimensions:write
Creates a dimension in one of the subsidiary's ten analytical slots.
| Constraint | Conflict behavior |
|---|---|
index is unique from 1 to 10 |
Returns 409 dimension_slot_occupied |
| Subsidiary owns the selected slot | Inherited slots return 409 dimension_inherited |
| At most ten dimensions exist | Returns 409 dimension_limit_reached |
The public API assigns any internal code needed by the accounting service; callers identify the dimension by UUID and display name.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | UUID of the authorized company group. |
subsidiary_id |
path | Yes | string (uuid) | UUID of the subsidiary whose books contain the bank account. |
Request
POST /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/dimensions HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Content-Type: application/json
{
"name": "Department",
"index": 1
}
Required body fields: name, index.
Responses
| Status | Description |
|---|---|
201 |
Dimension created. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks the required scope or granted accounting context. |
409 |
Request conflicts with inheritance, uniqueness, or accounting state. |
422 |
One or more supplied values failed validation. |
201 example
HTTP/1.1 201 Created
Content-Type: application/json
{
"data": {
"id": "4c447a9e-e823-41bf-88c9-98b7015d228c",
"name": "Department",
"index": 1,
"active": true,
"inherited": false,
"created_at": "2026-08-10T14:30:00Z",
"updated_at": "2026-08-10T14:30:00Z"
}
}