finov.ioDocumentationHome

List or create accounts

API Documentation / Resources / Accounts and settings

List accounts

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

Required OAuth scope: accounting:read

Lists undeleted accounts in the subsidiary's effective chart.

Filter Meaning
active Active or inactive accounts
mappable Accounts available for direct posting
category Exact public category code
code Exact account code
search Code or name search

Sort using code, name, or updated_at; the default is code ASC followed by 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
mappable query No boolean
category query No string
code query No string
search query No string
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}/accounts HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}

Responses

Status Description
200 A page of accounts.
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": "a110c7ae-3208-4f93-a64c-d2ba9dd82c31",
      "code": "4100",
      "name": "Consulting revenue",
      "description": null,
      "category": "REVENUE",
      "mappable": true,
      "active": true,
      "created_at": "2026-08-10T11:00:00Z",
      "updated_at": "2026-08-10T11:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 30,
    "last_page": 1,
    "total": 1
  }
}

Create an account

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

Required OAuth scope: accounting:write

Creates an account in a locally managed chart of accounts.

Rule Result
Code is unique within the subsidiary Duplicate returns 409 account_code_duplicate
Category is a supported public category Unknown category returns 422 validation_error
Chart is not inherited Inherited chart returns 409 chart_inherited

mappable=false identifies a grouping or control account that cannot be selected for ordinary journal and document lines.

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}/accounts HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "code": "4100",
  "name": "Consulting revenue",
  "category": "REVENUE",
  "mappable": true
}

Required body fields: code, name, category.

Responses

Status Description
201 Account created.
401 Access token is missing, expired, revoked, or invalid.
403 Token lacks the required scope or granted accounting context.
409 Request conflicts with 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": "a110c7ae-3208-4f93-a64c-d2ba9dd82c31",
    "code": "4100",
    "name": "Consulting revenue",
    "description": null,
    "category": "REVENUE",
    "mappable": true,
    "active": true,
    "created_at": "2026-08-10T11:00:00Z",
    "updated_at": "2026-08-10T11:00:00Z"
  }
}