finov.ioDocumentationHome

List or create dimension elements

API Documentation / Resources / Dimensions

Finovio New element form with Code and Name fields
Add a unique code and name within the selected dimension.

List dimension elements

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

Required OAuth scope: dimensions:read

Lists coded values belonging to one dimension.

Filtering and ordering

Parameter Meaning Default
active Filter active or inactive elements All
search Match code or name No search
updated_since Updated at or after an RFC 3339 timestamp Unbounded
sort code, name, or updated_at code
order asc or desc asc

Equal sort values use stable resource order for deterministic pages.

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.
active query No boolean Filter by active state.
search query No string Case-insensitive code or name search.
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
sort query No string: code, name, updated_at
order query No string: asc, desc

Request

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

Responses

Status Description
200 A page of dimension elements.
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.
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"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 30,
    "last_page": 1,
    "total": 1
  }
}

Create a dimension element

POST /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/dimensions/{dimension_id}/elements

Required OAuth scope: dimensions:write

Adds a coded classification value to a locally owned dimension.

Constraint Result when violated
Code is 2 to 6 alphanumeric characters 422 validation_error
Code and name are unique in the dimension 409 dimension_element_duplicate
Dimension is locally owned 409 dimension_inherited

Element codes are stable integration values. Prefer concise uppercase codes and use name for the human-readable label.

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

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

{
  "code": "CNSLT",
  "name": "Consulting"
}

Required body fields: code, name.

Responses

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

201 example

HTTP/1.1 201 Created
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"
  }
}