Get, update, or archive a dimension
API Documentation / Resources / Dimensions
Get a dimension
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/dimensions/{dimension_id}
Required OAuth scope: dimensions:read
Returns one dimension visible in the subsidiary's effective dimension
configuration. For inherited dimensions, inherited is true.
Resources outside the granted tenant and subsidiary context are never
disclosed and return 404 Not Found.
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. |
dimension_id |
path | Yes | string (uuid) | UUID of the owning dimension. |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/dimensions/{dimension_id} HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
Dimension details. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks the required scope or granted accounting context. |
404 |
Resource does not exist in the granted accounting context. |
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"
}
}
Update a dimension
PATCH /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/dimensions/{dimension_id}
Required OAuth scope: dimensions:write
Updates one or more mutable fields. Omitted fields retain their values.
| Field | Effect |
|---|---|
name |
Changes the display label. |
index |
Moves the definition to an unoccupied owned slot. |
active |
Controls availability for new classifications. |
Inherited dimensions cannot be modified from the child subsidiary and
return 409 dimension_inherited with the source subsidiary context.
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. |
dimension_id |
path | Yes | string (uuid) | UUID of the owning dimension. |
Request
PATCH /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/dimensions/{dimension_id} HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Content-Type: application/json
{
"name": "Business unit"
}
Required body fields: None.
Responses
| Status | Description |
|---|---|
200 |
Updated dimension. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks the required scope or granted accounting context. |
404 |
Resource does not exist in the granted accounting context. |
409 |
Request conflicts with inheritance, uniqueness, or accounting state. |
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"
}
}
Archive a dimension
DELETE /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/dimensions/{dimension_id}
Required OAuth scope: dimensions:write
Archives a dimension for future use without rewriting historical accounting records.
| State | Result |
|---|---|
| Locally owned and archivable | 204 No Content |
| Inherited from a parent | 409 dimension_inherited |
| Blocked by an accounting dependency | 409 dimension_in_use |
Archival also retires the dimension's available elements according to accounting dependency rules.
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. |
dimension_id |
path | Yes | string (uuid) | UUID of the owning dimension. |
Request
DELETE /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/dimensions/{dimension_id} HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
204 |
Dimension archived. The response has no body. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks the required scope or granted accounting context. |
404 |
Resource does not exist in the granted accounting context. |
409 |
Request conflicts with inheritance, uniqueness, or accounting state. |