finov.ioDocumentationHome

Get, update, or archive a dimension element

API Documentation / Resources / Dimensions

Finovio Edit element form populated with the Finance dimension element
Update an element's code or name without breaking its historical references.

Get a dimension element

GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/dimensions/{dimension_id}/elements/{element_id}

Required OAuth scope: dimensions:read

Returns one element from the identified dimension. The dimension and element must both be visible in the granted 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.
element_id path Yes string (uuid) UUID of an element within the identified dimension.

Request

GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/dimensions/{dimension_id}/elements/{element_id} HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}

Responses

Status Description
200 Dimension element 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": "587698ca-3266-4ec6-aa13-a8b3c34b6513",
    "dimension_id": "4c447a9e-e823-41bf-88c9-98b7015d228c",
    "code": "CNSLT",
    "name": "Consulting",
    "active": true,
    "created_at": "2026-08-10T15:00:00Z",
    "updated_at": "2026-08-10T15:00:00Z"
  }
}

Update a dimension element

PATCH /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/dimensions/{dimension_id}/elements/{element_id}

Required OAuth scope: dimensions:write

Updates an element's code, display name, or active state. Omitted fields remain unchanged.

Deactivating an element prevents new assignments but does not remove it from historical journals or documents. Inherited elements must be edited in their source subsidiary.

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.
element_id path Yes string (uuid) UUID of an element within the identified dimension.

Request

PATCH /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/dimensions/{dimension_id}/elements/{element_id} HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "name": "Advisory"
}

Required body fields: None.

Responses

Status Description
200 Updated dimension element.
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": "587698ca-3266-4ec6-aa13-a8b3c34b6513",
    "dimension_id": "4c447a9e-e823-41bf-88c9-98b7015d228c",
    "code": "CNSLT",
    "name": "Consulting",
    "active": true,
    "created_at": "2026-08-10T15:00:00Z",
    "updated_at": "2026-08-10T15:00:00Z"
  }
}

Archive a dimension element

DELETE /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/dimensions/{dimension_id}/elements/{element_id}

Required OAuth scope: dimensions:write

Retires an element from future selection while preserving classifications already recorded on accounting data.

State Result
Locally owned element 204 No Content
Inherited dimension 409 dimension_inherited
Accounting dependency prevents retirement 409 dimension_element_in_use

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.
element_id path Yes string (uuid) UUID of an element within the identified dimension.

Request

DELETE /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/dimensions/{dimension_id}/elements/{element_id} HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}

Responses

Status Description
204 Dimension element 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.