finov.ioDocumentationHome

List or create dimensions

API Documentation / Resources / Dimensions

List dimensions

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

Required OAuth scope: dimensions:read

Lists the analytical dimensions available to the subsidiary, including definitions inherited from parent subsidiaries.

Query behavior

Parameter Meaning Default
active Filter active or inactive definitions All
updated_since Return records updated at or after an RFC 3339 timestamp Unbounded
page Positive page number 1
per_page Records per page from 1 to 100 30

Dimensions are ordered by index ASC, then stable resource order.

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.
active query No boolean Filter by active state.
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

Request

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

Responses

Status Description
200 A page of dimensions.
401 Access token is missing, expired, revoked, or invalid.
403 Token lacks the required scope or granted accounting context.
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"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 30,
    "last_page": 1,
    "total": 1
  }
}

Create a dimension

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

Required OAuth scope: dimensions:write

Creates a dimension in one of the subsidiary's ten analytical slots.

Constraint Conflict behavior
index is unique from 1 to 10 Returns 409 dimension_slot_occupied
Subsidiary owns the selected slot Inherited slots return 409 dimension_inherited
At most ten dimensions exist Returns 409 dimension_limit_reached

The public API assigns any internal code needed by the accounting service; callers identify the dimension by UUID and display name.

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.

Request

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

{
  "name": "Department",
  "index": 1
}

Required body fields: name, index.

Responses

Status Description
201 Dimension created.
401 Access token is missing, expired, revoked, or invalid.
403 Token lacks the required scope or 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": "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"
  }
}