finov.ioDocumentationHome

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.