List or create dimension elements
API Documentation / Resources / Dimensions

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"
}
}