finov.ioDocumentationHome

Get, update, or archive an account

API Documentation / Resources / Accounts and settings

Get an account

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

Required OAuth scope: accounting:read

Returns one account by UUID. Accounts outside the granted tenant and subsidiary context are not disclosed.

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.
account_id path Yes string (uuid) UUID of an account in the subsidiary chart.

Request

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

Responses

Status Description
200 Account 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": "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"
  }
}

Update an account

PATCH /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/accounts/{account_id}

Required OAuth scope: accounting:write

Updates mutable presentation and posting fields. The account category is intentionally immutable through this operation because changing category can alter financial statement classification.

Existing journals retain the account UUID. Setting active=false or mappable=false prevents future selection but does not rewrite history.

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.
account_id path Yes string (uuid) UUID of an account in the subsidiary chart.

Request

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

{
  "name": "Advisory revenue",
  "mappable": false
}

Required body fields: None.

Responses

Status Description
200 Updated account.
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 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": "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"
  }
}

Archive an account

DELETE /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/accounts/{account_id}

Required OAuth scope: accounting:write

Archives an account instead of physically deleting it.

Dependency Behavior
Posted accounting activity History retains the account reference.
Active child accounts Returns 409 account_has_children.
Protected system purpose Returns 409 account_protected.
Inherited chart Returns 409 chart_inherited.

An archived account cannot be selected for new postings.

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.
account_id path Yes string (uuid) UUID of an account in the subsidiary chart.

Request

DELETE /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/accounts/{account_id} HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}

Responses

Status Description
204 Account 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 uniqueness or accounting state.