# Chart of accounts

> Chart of accounts templates, each entity's own accounts, and the global account library templates are built from.

Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer <API key or access token>`.

## List all chart of accounts templates

`GET /api/public/v1/charts`

SDK: `prosaic.charts.list()`

Returns all chart of accounts templates in the workspace. Requires API key authentication.

### Responses

- `200`: Successful response
  - `data` (array of objects, required)
    - `id` (string, required)
    - `name` (string, required)
    - `description` (string, nullable, required)
    - `accountCount` (number, required)
  - `meta` (object)
    - `count` (number, required)
- `401`: Unauthorized - Invalid or missing API key

### Example (Node SDK)

```ts
const { data } = await prosaic.charts.list();
```

### Example (curl)

```bash
curl https://app.prosaic.works/api/public/v1/charts \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## Get chart of accounts template accounts

`GET /api/public/v1/charts/{chartId}`

SDK: `prosaic.charts.listAccounts(chartId, params)`

Returns paginated accounts from a chart-of-accounts **template** (the read-only blueprint entities are provisioned from). When `includeHidden=true`, also returns global accounts not in the template with `isIncluded=false`. Requires API key authentication.

Each included account also exposes its nullable confirmed systemRole and saved reportGroup/reportCategory summaries. subtype remains the legacy compatibility value, independent of report placement. Hidden global suggestions have systemRole=null and no saved report assignment.

**Important**: The `id` values returned by this endpoint are *template account* IDs (`TemplateAccount.id`). They are **not** the IDs of an entity's actual GL accounts — do not use them to post journals or look up reconciliation activity.

To fetch the chart of accounts for a specific entity (including bank-account-linked accounts and any custom accounts), use `GET /api/public/v1/entities/{entityId}/charts`. The bank-account-to-GL linkage is also embedded on each entity's bank account at `bankAccounts[].entityAccount` in the `GET /api/public/v1/entities` response.

**Tax codes**: The `taxCode` field is returned as the human-readable tax *name* (e.g. `"15% GST on Income"`, or `"No GST"` when unset), not the machine code. When creating or updating a template you must pass the machine *code* instead (`NZ_GST_15_INC`, `NZ_GST_15_EXP`, `NZ_GST_0_NONE`, `NZ_GST_0_ZERO`), so convert the name back to its code before writing.

### Path parameters

- `chartId` (string, required)

### Query parameters

- `includeHidden` (boolean): When true, includes global accounts not in the template (with isIncluded=false). Disables pagination. Default: `false`.
- `page` (integer): Page number (starts at 1). Ignored when includeHidden=true. Default: `1`.
- `pageSize` (integer): Number of items per page. Ignored when includeHidden=true. Default: `20`.

### Responses

- `200`: Successful response
  - `templateUpdatedAt` (string, required)
  - `data` (array of objects, required)
    - `id` (string, required)
    - `updatedAt` (string)
    - `reportCategoryReviewedAt` (string, nullable)
    - `reportCategoryReviewVersion` (number)
    - `code` (string, required)
    - `name` (string, required)
    - `type` (string, required)
    - `subtype` (string, required)
    - `reportGroup` (object, nullable, required)
      - `id` (string, required)
      - `key` (string, required)
      - `name` (string, required)
      - `status` (string, required)
      - `accountType` (string, required)
    - `reportCategory` (object, nullable, required)
      - `id` (string, required)
      - `key` (string, required)
      - `name` (string, required)
      - `status` (string, required)
    - `taxCode` (string, required)
    - `description` (string, nullable, required)
    - `mappedCode` (string, nullable, required)
    - `isSystem` (boolean, required)
    - `systemRole` (string, nullable)
    - `parentId` (string, nullable)
    - `isExcluded` (boolean)
    - `isIncluded` (boolean)
    - `source` (string): One of: `template`, `overridden`, `custom`.
  - `pagination` (object, required)
    - `currentPage` (number, required)
    - `pageSize` (number, required)
    - `totalCount` (number, required)
    - `totalPages` (number, required)
    - `hasNextPage` (boolean, required)
    - `hasPreviousPage` (boolean, required)
- `400`: Bad request - missing or invalid parameters
- `401`: Unauthorized - Invalid or missing API key
- `403`: Forbidden - No access to the specified chart
- `404`: Chart not found

### Example (Node SDK)

```ts
const page = await prosaic.charts.listAccounts(chartId);
```

### Example (curl)

```bash
curl https://app.prosaic.works/api/public/v1/charts/$CHART_ID \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## List approved Xero report-code mappings

`GET /api/public/v1/xero-report-mappings`

SDK: `prosaic.charts.listXeroReportMappings()`

Look up Xero Report Code values in the authorised workspace's country. Each entry gives the Prosaic report group and optional category. Only approved NZ placements that are valid in the current taxonomy are returned. Other countries return an empty lookup. Missing codes require review.

### Responses

- `200`: Successful response
  - `data` (object, required)
    - `country` (string, required)
    - `mappings` (object, required)
  - `meta` (object)
    - `count` (number, required)
- `401`: Missing or invalid bearer authentication
- `403`: Workspace or API access denied
- `404`: Authorised workspace unavailable
- `500`: Unexpected failure loading mappings

### Example (Node SDK)

```ts
const { data } = await prosaic.charts.listXeroReportMappings();
```

### Example (curl)

```bash
curl https://app.prosaic.works/api/public/v1/xero-report-mappings \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## Create a chart of accounts template

`POST /api/public/v1/charts`

SDK: `prosaic.charts.create(params)`

Discover the current workspace contract at GET /api/public/v1/report-categories before writing. In activated workspaces, included accounts need groupKey and an explicit categoryKey (null is valid for eligible group-only accounts); type derives from the group. Parent-only and mixed classification writes are rejected. Nonactivated workspaces retain parent inputs and reject reporting inputs. Metadata-only updates preserve saved reporting. API writes do not confirm template review or approve propagation. Reporting edits require saved template and row versions; reload after 409, and never retry using an alternate request shape.
In nonactivated workspaces, creates a chart from global definitions. Every system global
account (see `GET /api/public/v1/global-accounts`, `isSystem: true`) must be present
in `accounts` with `isIncluded: true` — otherwise the request fails with
`SYSTEM_ACCOUNT_VALIDATION` listing all missing accounts. Set
`includeSystemAccounts: true` to have any omitted system accounts added
automatically from their global definitions. Requires API key authentication.

**Tax codes**: The `taxCode` field expects the machine code, not the human-readable tax name.
Passing a name (e.g. `"15% GST on Income"`) is stored verbatim and resolves to null wherever the
code is looked up. Valid codes are `NZ_GST_15_INC` (15% GST on Income), `NZ_GST_15_EXP`
(15% GST on Expenses), `NZ_GST_0_NONE` (No GST), and `NZ_GST_0_ZERO` (Zero-rated GST). Omit
`taxCode` or set it to null to default to `NZ_GST_0_NONE` (No GST).

**Description defaults**: `description` is optional per account; omitting it (or null) leaves
the account description empty.

### Request body

Content type: `application/json`

- `name` (string, required)
- `accounts` (array of objects, required)
  - `code` (string, required)
  - `name` (string, required)
  - `isIncluded` (boolean, required)
  - `type` (string)
  - `subtype` (string, nullable)
  - `taxCode` (string, nullable): One of: `NZ_GST_15_INC`, `NZ_GST_15_EXP`, `NZ_GST_0_NONE`, `NZ_GST_0_ZERO`, `AU_GST_10_INC`, `AU_GST_10_EXP`, `AU_GST_0_NONE`, `AU_GST_0_INPUT`, `AU_GST_0_EXPORT`.
  - `description` (string, nullable)
  - `mappedCode` (string, nullable)
  - `parentCode` (string, nullable)
  - `id` (string)
  - `clientKey` (string)
  - `groupKey` (string)
  - `categoryKey` (string, nullable)
  - `systemRole` (string, nullable)
  - `expectedUpdatedAt` (string)
- `description` (string)
- `includeSystemAccounts` (boolean)

### Responses

- `201`: Successful response
  - `data` (object, required)
    - `id` (string, required)
    - `name` (string, required)
    - `description` (string, nullable, required)
  - `meta` (object)
    - `count` (number, required)
- `400`: Validation error. `SYSTEM_ACCOUNT_VALIDATION` includes `details.missingAccounts` listing every required system account absent from the payload.
  - `error` (string, required)
  - `code` (string, required)
  - `details` (object)
    - `missingAccounts` (array of objects)
      - `code` (string)
      - `name` (string)
- `401`: Unauthorized

### Example (Node SDK)

```ts
const { data } = await prosaic.charts.create({
  name: 'Example Ltd',
  accounts: [
    {
      code: '200',
      name: 'Example Ltd',
      isIncluded: true,
    },
  ],
});
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/charts \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Ltd",
    "accounts": [
      {
        "code": "200",
        "name": "Example Ltd",
        "isIncluded": true
      }
    ]
  }'
```

## Add a single account to a chart of accounts template

`POST /api/public/v1/charts/{chartId}/accounts`

SDK: `prosaic.charts.createAccount(chartId, params)`

Discover the current workspace contract at GET /api/public/v1/report-categories before writing. In activated workspaces, included accounts need groupKey and an explicit categoryKey (null is valid for eligible group-only accounts); type derives from the group. Parent-only and mixed classification writes are rejected. Nonactivated workspaces retain parent inputs and reject reporting inputs. Metadata-only updates preserve saved reporting. API writes do not confirm template review or approve propagation. Reporting edits require saved template and row versions; reload after 409, and never retry using an alternate request shape.
Adds one account to a chart of accounts template without resending the full account list. To
add a legacy top-level account in a nonactivated workspace, provide its global account `code`; to add a legacy child
account, provide `code`, `name`, and `parentCode` (the child code must be `{parentCode}.{digits}`).
Activated rows use the explicit fields above and remain subject to review before reporting propagation. Requires bearer authentication.

### Path parameters

- `chartId` (string, required)

### Request body

Content type: `application/json`

- `code` (string, required)
- `name` (string, nullable)
- `parentCode` (string, nullable)
- `taxCode` (string, nullable): One of: `NZ_GST_15_INC`, `NZ_GST_15_EXP`, `NZ_GST_0_NONE`, `NZ_GST_0_ZERO`, `AU_GST_10_INC`, `AU_GST_10_EXP`, `AU_GST_0_NONE`, `AU_GST_0_INPUT`, `AU_GST_0_EXPORT`.
- `description` (string, nullable)
- `mappedCode` (string, nullable)
- `id` (string)
- `clientKey` (string)
- `groupKey` (string)
- `categoryKey` (string, nullable)
- `systemRole` (string, nullable)
- `expectedUpdatedAt` (string)

### Responses

- `200`: Successful response
  - `data` (object, required)
    - `id` (string, nullable, required)
    - `code` (string, required)
    - `entitiesUpdated` (number, required)
  - `meta` (object)
    - `count` (number, required)
- `400`: Validation error or business rule violation
- `401`: Unauthorized
- `404`: Chart not found
- `409`: An account with this code already exists, or the code conflicts with a custom entity account

### Example (Node SDK)

```ts
const { data } = await prosaic.charts.createAccount(chartId, {
  code: '200',
});
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/charts/$CHART_ID/accounts \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "200"
  }'
```

## Update a chart of accounts template

`POST /api/public/v1/charts/{chartId}/update`

SDK: `prosaic.charts.update(chartId, params)`

Discover the current workspace contract at GET /api/public/v1/report-categories before writing. In activated workspaces, included accounts need groupKey and an explicit categoryKey (null is valid for eligible group-only accounts); type derives from the group. Parent-only and mixed classification writes are rejected. Nonactivated workspaces retain parent inputs and reject reporting inputs. Metadata-only updates preserve saved reporting. API writes do not confirm template review or approve propagation. Reporting edits require saved template and row versions; reload after 409, and never retry using an alternate request shape.
Updates a chart of accounts template. When `accounts` is provided it fully replaces the
template's account list (delegates to updateAccountTemplateAccounts and propagates to all
entities). When `accounts` is omitted, only the provided template metadata (`name`,
`description`) is updated and accounts are left untouched. Omit a metadata field to preserve
its existing value, or send `description: null` to clear the description. A full replacement
list in a nonactivated workspace must still contain every
system account (`GET /api/public/v1/global-accounts`, `isSystem: true`) with
`isIncluded: true` — otherwise the request fails with `SYSTEM_ACCOUNT_VALIDATION` listing
all missing accounts. Set `includeSystemAccounts: true` to carry over any omitted system
accounts automatically. For surgical single-account changes use the
`/charts/{chartId}/accounts` endpoints instead. Requires API key authentication.

**Tax codes**: The `taxCode` field expects the machine code, not the human-readable tax name.
Passing a name (e.g. `"15% GST on Income"`) is stored verbatim and resolves to null wherever the
code is looked up. Valid codes are `NZ_GST_15_INC` (15% GST on Income), `NZ_GST_15_EXP`
(15% GST on Expenses), `NZ_GST_0_NONE` (No GST), and `NZ_GST_0_ZERO` (Zero-rated GST). Note that
`GET /api/public/v1/charts/{chartId}` returns the human-readable name on read — convert it back to
the machine code before writing.

**Field preserve/clear semantics**: For each account, omitting a field (`description`, `taxCode`,
`mappedCode`) preserves its existing value, while an explicit null clears it (taxCode clears to
`NZ_GST_0_NONE`).

### Path parameters

- `chartId` (string, required)

### Request body

Content type: `application/json`

- `name` (string)
- `description` (string, nullable)
- `includeSystemAccounts` (boolean)
- `expectedUpdatedAt` (string)
- `accounts` (array of objects)
  - `code` (string, required)
  - `isIncluded` (boolean, required)
  - `name` (string)
  - `description` (string, nullable)
  - `taxCode` (string, nullable): One of: `NZ_GST_15_INC`, `NZ_GST_15_EXP`, `NZ_GST_0_NONE`, `NZ_GST_0_ZERO`, `AU_GST_10_INC`, `AU_GST_10_EXP`, `AU_GST_0_NONE`, `AU_GST_0_INPUT`, `AU_GST_0_EXPORT`.
  - `mappedCode` (string, nullable)
  - `parentCode` (string, nullable)
  - `id` (string)
  - `clientKey` (string)
  - `groupKey` (string)
  - `categoryKey` (string, nullable)
  - `systemRole` (string, nullable)
  - `expectedUpdatedAt` (string)

### Responses

- `200`: Successful response
  - `data` (object, required)
    - `id` (string, required)
    - `name` (string, required)
    - `description` (string, nullable, required)
    - `entitiesUpdated` (number, required)
  - `meta` (object)
    - `count` (number, required)
- `400`: Validation error or business rule violation. `SYSTEM_ACCOUNT_VALIDATION` includes `details.missingAccounts` listing every required system account absent from the payload.
- `401`: Unauthorized
- `404`: Chart not found
- `409`: Account code conflict - new template account codes conflict with custom accounts in entities using this template
  - `error` (string, required)
  - `code` (string, required): One of: `ACCOUNT_CODE_CONFLICT`.
  - `details` (object)
    - `accountCode` (string): (deprecated) Use accountCodes[0] for backward compatibility.
    - `accountCodes` (array of strings): All new account codes that conflict with entity custom accounts.
    - `conflictingEntityIds` (array of strings): Entity IDs that have conflicting custom accounts.
    - `conflictingEntities` (array of objects)
      - `entityId` (string, uuid)
      - `entityName` (string)
      - `conflictingAccountCodes` (array of strings): Account codes in this entity that conflict.

### Example (Node SDK)

```ts
const { data } = await prosaic.charts.update(chartId, {
  name: 'Example Ltd',
  description: 'Office supplies',
  includeSystemAccounts: true,
  expectedUpdatedAt: '2026-04-01',
  accounts: [
    {
      code: '200',
      isIncluded: true,
    },
  ],
});
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/charts/$CHART_ID/update \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Ltd",
    "description": "Office supplies",
    "includeSystemAccounts": true,
    "expectedUpdatedAt": "2026-04-01",
    "accounts": [
      {
        "code": "200",
        "isIncluded": true
      }
    ]
  }'
```

## Update a single account in a chart of accounts template

`POST /api/public/v1/charts/{chartId}/accounts/{accountId}/update`

SDK: `prosaic.charts.updateAccount(chartId, accountId, params)`

Discover the current workspace contract at GET /api/public/v1/report-categories before writing. In activated workspaces, included accounts need groupKey and an explicit categoryKey (null is valid for eligible group-only accounts); type derives from the group. Parent-only and mixed classification writes are rejected. Nonactivated workspaces retain parent inputs and reject reporting inputs. Metadata-only updates preserve saved reporting. API writes do not confirm template review or approve propagation. Reporting edits require saved template and row versions; reload after 409, and never retry using an alternate request shape.
Updates one account in a chart of accounts template without resending the full account list.
Supports `name`, `description`, `taxCode`, `mappedCode` and `code` (rename, kept under the same
parent). A code rename cascades non-destructively to every entity account derived from this
template account (balances and customizations are preserved). Metadata changes follow existing propagation policy for entities
using the template. Omitted fields preserve their existing values; send `description: null` to
clear the description. `accountId` is the TemplateAccount ID from `GET /charts/{chartId}`.
Reporting changes remain subject to human review before propagation. Requires bearer authentication.

### Path parameters

- `chartId` (string, required)
- `accountId` (string, required)

### Request body

Content type: `application/json`

- `expectedTemplateUpdatedAt` (string)
- `name` (string)
- `description` (string, nullable)
- `taxCode` (string, nullable): One of: `NZ_GST_15_INC`, `NZ_GST_15_EXP`, `NZ_GST_0_NONE`, `NZ_GST_0_ZERO`, `AU_GST_10_INC`, `AU_GST_10_EXP`, `AU_GST_0_NONE`, `AU_GST_0_INPUT`, `AU_GST_0_EXPORT`.
- `mappedCode` (string, nullable)
- `code` (string)
- `id` (string)
- `clientKey` (string)
- `groupKey` (string)
- `categoryKey` (string, nullable)
- `systemRole` (string, nullable)
- `expectedUpdatedAt` (string)

### Responses

- `200`: Successful response
  - `data` (object, required)
    - `id` (string, required)
    - `entitiesUpdated` (number, required)
  - `meta` (object)
    - `count` (number, required)
- `400`: Validation error or business rule violation
- `401`: Unauthorized
- `404`: Chart or account not found
- `409`: The new code conflicts with an existing template or entity account

### Example (Node SDK)

```ts
const { data } = await prosaic.charts.updateAccount(chartId, accountId, {
  expectedTemplateUpdatedAt: '2026-04-01',
  name: 'Example Ltd',
  description: 'Office supplies',
  taxCode: 'NZ_GST_15_INC',
  mappedCode: 'MAPPED_CODE',
  code: '200',
  id: 'ID',
  clientKey: 'string',
  groupKey: 'string',
  categoryKey: 'string',
  systemRole: 'string',
  expectedUpdatedAt: '2026-04-01',
});
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/charts/$CHART_ID/accounts/$ACCOUNT_ID/update \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedTemplateUpdatedAt": "2026-04-01",
    "name": "Example Ltd",
    "description": "Office supplies",
    "taxCode": "NZ_GST_15_INC",
    "mappedCode": "MAPPED_CODE",
    "code": "200",
    "id": "ID",
    "clientKey": "string",
    "groupKey": "string",
    "categoryKey": "string",
    "systemRole": "string",
    "expectedUpdatedAt": "2026-04-01"
  }'
```

## Delete a chart of accounts template

`POST /api/public/v1/charts/{chartId}/delete`

SDK: `prosaic.charts.del(chartId)`

Deletes a chart of accounts template. Cannot delete templates with assigned entities. Requires API key authentication.

### Path parameters

- `chartId` (string, required)

### Responses

- `200`: Successful response
  - `data` (object, required)
    - `success` (boolean, required)
  - `meta` (object)
    - `count` (number, required)
- `401`: Unauthorized
- `404`: Chart not found
- `409`: Cannot delete template with assigned entities

### Example (Node SDK)

```ts
const { data } = await prosaic.charts.del(chartId);
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/charts/$CHART_ID/delete \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## Delete a single account from a chart of accounts template

`POST /api/public/v1/charts/{chartId}/accounts/{accountId}/delete`

SDK: `prosaic.charts.deleteAccount(chartId, accountId, params)`

Removes one account from a chart of accounts template without resending the full account list.
The removal propagates to every entity using the template. Accounts that have journal entries,
child accounts, or are system accounts cannot be removed. `accountId` is the TemplateAccount ID
from `GET /charts/{chartId}`. Requires API key authentication.

### Path parameters

- `chartId` (string, required)
- `accountId` (string, required)

### Request body

Content type: `application/json`

- `expectedUpdatedAt` (string)

### Responses

- `200`: Successful response
  - `data` (object, required)
    - `success` (boolean, required)
    - `entitiesUpdated` (number, required)
  - `meta` (object)
    - `count` (number, required)
- `400`: Account has journal entries, has children, or is a system account
- `401`: Unauthorized
- `404`: Chart or account not found

### Example (Node SDK)

```ts
const { data } = await prosaic.charts.deleteAccount(chartId, accountId, {
  expectedUpdatedAt: '2026-04-01',
});
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/charts/$CHART_ID/accounts/$ACCOUNT_ID/delete \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedUpdatedAt": "2026-04-01"
  }'
```

## List chart of accounts for an entity

`GET /api/public/v1/entities/{entityId}/charts`

SDK: `prosaic.entityAccounts.list(entityId, params)`

Returns chart account codes configured for the specified entity. Supports filtering by system accounts and excluded accounts. Requires API key authentication and entity access. reportGroup and reportCategory expose the saved reporting classification; subtype remains the legacy compatibility value and may differ from current report placement. Null category with a saved group is valid.

### Path parameters

- `entityId` (string, required)

### Query parameters

- `includeSystem` (string): Include system-generated accounts (GST, Rounding, Retained Earnings, etc.) in the response. Defaults to true so all account codes are available for mapping (e.g. importing a trial balance or journals). Pass includeSystem=false to exclude system accounts.
- `includeExcluded` (string): Include accounts that have been excluded from the entity's chart. When true, excluded accounts are returned with isExcluded=true flag, and their data comes from the template account.

### Responses

- `200`: Successful response
  - `data` (array of objects, required)
    - `id` (string, required)
    - `updatedAt` (string)
    - `reportCategoryReviewedAt` (string, nullable)
    - `reportCategoryReviewVersion` (number)
    - `code` (string, required)
    - `name` (string, required)
    - `type` (string, required)
    - `subtype` (string, required)
    - `reportGroup` (object, nullable, required)
      - `id` (string, required)
      - `key` (string, required)
      - `name` (string, required)
      - `status` (string, required)
      - `accountType` (string, required)
    - `reportCategory` (object, nullable, required)
      - `id` (string, required)
      - `key` (string, required)
      - `name` (string, required)
      - `status` (string, required)
    - `taxCode` (string, required)
    - `description` (string, nullable, required)
    - `mappedCode` (string, nullable, required)
    - `isSystem` (boolean, required)
    - `systemRole` (string, nullable)
    - `parentId` (string, nullable)
    - `isExcluded` (boolean)
    - `isIncluded` (boolean)
    - `source` (string): One of: `template`, `overridden`, `custom`.
  - `meta` (object)
    - `count` (number, required)
- `400`: Bad request - missing or invalid parameters
  - `error` (string)
  - `code` (string)
- `401`: Unauthorized - Invalid or missing API key
  - `error` (string)
- `403`: Forbidden - No access to the specified entity
  - `error` (string)
  - `code` (string)
- `500`: Internal server error
  - `error` (string)
  - `code` (string)

### Example (Node SDK)

```ts
const { data } = await prosaic.entityAccounts.list(entityId);
```

### Example (curl)

```bash
curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/charts \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## Create a child account in the chart of accounts

`POST /api/public/v1/entities/{entityId}/charts`

SDK: `prosaic.entityAccounts.create(entityId, params)`

Discover GET /api/public/v1/entities/{entityId}/report-categories before a write. In activated scope, create with reporting.groupKey and explicit reporting.categoryKey (null for eligible group-only accounts); omit legacy parent references. Metadata-only patches preserve reporting. Reporting updates require reporting.expected with the saved pair (or null for an unassigned account). All active workspaces must allow the write. Type derives from group. A contract mismatch or stale pair returns 409; reload and rediscover without automatically retrying a mutation. Stored subtype output remains a compatibility value.

### Path parameters

- `entityId` (string, required)

### Request body

Content type: `application/json`

- `code` (string, required)
- `name` (string, required)
- `taxCode` (string, required)
- `reporting` (object)
  - `groupKey` (string, required)
  - `categoryKey` (string, nullable, required)
- `parentAccountId` (string)
- `parentAccountCode` (string)
- `parentMappedCode` (string)
- `description` (string, nullable)
- `mappedCode` (string, nullable)

### Responses

- `201`: Successful response
  - `data` (object, required)
    - `id` (string, required)
    - `updatedAt` (string)
    - `reportCategoryReviewedAt` (string, nullable)
    - `reportCategoryReviewVersion` (number)
    - `code` (string, required)
    - `name` (string, required)
    - `type` (string, required)
    - `subtype` (string, required)
    - `reportGroup` (object, nullable, required)
      - `id` (string, required)
      - `key` (string, required)
      - `name` (string, required)
      - `status` (string, required)
      - `accountType` (string, required)
    - `reportCategory` (object, nullable, required)
      - `id` (string, required)
      - `key` (string, required)
      - `name` (string, required)
      - `status` (string, required)
    - `taxCode` (string, required)
    - `description` (string, nullable, required)
    - `mappedCode` (string, nullable, required)
    - `isSystem` (boolean, required)
    - `systemRole` (string, nullable)
    - `parentId` (string, nullable)
    - `isExcluded` (boolean)
    - `isIncluded` (boolean)
    - `source` (string): One of: `template`, `overridden`, `custom`.
  - `meta` (object)
    - `count` (number, required)
- `400`: Bad request - validation error or business rule violation
  - `error` (string): Error message.
  - `code` (string): Error code.
  - `details` (object): Additional error details (for template conflicts)
    - `templateAccountId` (string)
    - `isExcluded` (boolean)
- `403`: Forbidden - No access to the specified entity
  - `error` (string)
  - `code` (string)
- `404`: Parent account not found
  - `error` (string)
  - `code` (string)
- `409`: Conflict - account code already exists
  - `error` (string)
  - `code` (string)
- `500`: Internal server error
  - `error` (string)
  - `code` (string)

### Example (Node SDK)

```ts
const { data } = await prosaic.entityAccounts.create(entityId, {
  code: '4030.1',
  name: 'Software subscriptions',
  taxCode: 'NZ_GST_15_EXP',
  reporting: {
    groupKey: 'exp.operating',
    categoryKey: null,
  },
});
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/charts \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "4030.1",
    "name": "Software subscriptions",
    "taxCode": "NZ_GST_15_EXP",
    "reporting": {
      "groupKey": "exp.operating",
      "categoryKey": null
    }
  }'
```

## Update an entity account

`POST /api/public/v1/entities/{entityId}/charts/{accountId}/update`

SDK: `prosaic.entityAccounts.update(entityId, accountId, params)`

Discover GET /api/public/v1/entities/{entityId}/report-categories before a write. In activated scope, create with reporting.groupKey and explicit reporting.categoryKey (null for eligible group-only accounts); omit legacy parent references. Metadata-only patches preserve reporting. Reporting updates require reporting.expected with the saved pair (or null for an unassigned account). All active workspaces must allow the write. Type derives from group. A contract mismatch or stale pair returns 409; reload and rediscover without automatically retrying a mutation. Stored subtype output remains a compatibility value.

### Path parameters

- `entityId` (string, required)
- `accountId` (string, required)

### Request body

Content type: `application/json`

- `reporting` (object)
  - `groupKey` (string, required)
  - `categoryKey` (string, nullable, required)
  - `expected` (object, nullable, required)
    - `groupKey` (string, required)
    - `categoryKey` (string, nullable, required)
- `name` (string)
- `description` (string, nullable)
- `taxCode` (string)
- `mappedCode` (string, nullable)
- `code` (string)

### Responses

- `200`: Successful response
  - `data` (object, required)
    - `id` (string, required)
    - `updatedAt` (string)
    - `reportCategoryReviewedAt` (string, nullable)
    - `reportCategoryReviewVersion` (number)
    - `code` (string, required)
    - `name` (string, required)
    - `type` (string, required)
    - `subtype` (string, required)
    - `reportGroup` (object, nullable, required)
      - `id` (string, required)
      - `key` (string, required)
      - `name` (string, required)
      - `status` (string, required)
      - `accountType` (string, required)
    - `reportCategory` (object, nullable, required)
      - `id` (string, required)
      - `key` (string, required)
      - `name` (string, required)
      - `status` (string, required)
    - `taxCode` (string, required)
    - `description` (string, nullable, required)
    - `mappedCode` (string, nullable, required)
    - `isSystem` (boolean, required)
    - `systemRole` (string, nullable)
    - `parentId` (string, nullable)
    - `isExcluded` (boolean)
    - `isIncluded` (boolean)
    - `source` (string): One of: `template`, `overridden`, `custom`.
  - `meta` (object)
    - `count` (number, required)
- `400`: Validation error or business rule violation
- `404`: Account not found

### Example (Node SDK)

```ts
const { data } = await prosaic.entityAccounts.update(entityId, accountId, {
  reporting: {
    groupKey: 'exp.operating',
    categoryKey: null,
    expected: {
      groupKey: 'exp.operating',
      categoryKey: 'CATEGORY_KEY_FROM_LATEST_READ',
    },
  },
});
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/charts/$ACCOUNT_ID/update \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reporting": {
      "groupKey": "exp.operating",
      "categoryKey": null,
      "expected": {
        "groupKey": "exp.operating",
        "categoryKey": "CATEGORY_KEY_FROM_LATEST_READ"
      }
    }
  }'
```

## Restore a hidden/excluded template account

`POST /api/public/v1/entities/{entityId}/charts/excluded/{templateAccountId}/restore`

SDK: `prosaic.entityAccounts.restore(entityId, templateAccountId)`

Restores an excluded template account by removing the exclusion and recreating the entity account from the template. No request body required.

### Path parameters

- `entityId` (string, required)
- `templateAccountId` (string, required)

### Responses

- `200`: Successful response
  - `data` (object, required)
    - `success` (boolean, required)
  - `meta` (object)
    - `count` (number, required)
- `400`: Parent account must be restored first, or restoring would conflict with an assigned system role (SYSTEM_ACCOUNT_CONFLICT).
- `404`: Template account no longer exists (chart template may have been updated)
- `500`: Internal server error

### Example (Node SDK)

```ts
const { data } = await prosaic.entityAccounts.restore(entityId, templateAccountId);
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/charts/excluded/$TEMPLATE_ACCOUNT_ID/restore \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## Reset an entity account to template defaults

`POST /api/public/v1/entities/{entityId}/charts/{accountId}/reset`

SDK: `prosaic.entityAccounts.reset(entityId, accountId)`

Resets all customized fields on a template-based entity account back to the template values and clears customization flags. No request body required.

### Path parameters

- `entityId` (string, required)
- `accountId` (string, required)

### Responses

- `200`: Successful response
  - `data` (object, required)
    - `success` (boolean, required)
  - `meta` (object)
    - `count` (number, required)
- `404`: Account not found
- `500`: Internal server error

### Example (Node SDK)

```ts
const { data } = await prosaic.entityAccounts.reset(entityId, accountId);
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/charts/$ACCOUNT_ID/reset \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## Delete or hide an entity account

`POST /api/public/v1/entities/{entityId}/charts/{accountId}/delete`

SDK: `prosaic.entityAccounts.del(entityId, accountId)`

Deletes a custom child account or hides a template-based child account by creating an exclusion. Parent accounts cannot be deleted. Accounts assigned a system role or linked to bank accounts, fixed assets or inter-entity transfers cannot be deleted.

### Path parameters

- `entityId` (string, required)
- `accountId` (string, required)

### Responses

- `200`: Successful response
  - `data` (object, required)
    - `success` (boolean, required)
  - `meta` (object)
    - `count` (number, required)
- `400`: The account is a parent, has children or journal entries, or has an operational link that prevents deletion (DELETE_RESTRICTED).
- `404`: Account not found

### Example (Node SDK)

```ts
const { data } = await prosaic.entityAccounts.del(entityId, accountId);
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/charts/$ACCOUNT_ID/delete \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## List report groups and categories for the authorised workspace

`GET /api/public/v1/report-categories`

SDK: `prosaic.reportCategories.listForWorkspace()`

Returns the complete stored taxonomy for the authorised workspace's country. Parent IDs and sort order describe the group tree. Headings are structure only; isAssignable=false prevents their selection. An ordinary group may allow a null category, but bank and asset-account functions can still require one. Category placements are exact, not inherited.
Examples: Operating expenses (exp.operating) is assignable with no category; Retained earnings (equ.retainedearnings) also permits a null category. Expenses (exp) is a heading and cannot be assigned. This endpoint does not change accounts. No country parameter or pagination is required.

### Responses

- `200`: Successful response
  - `data` (object, required)
    - `country` (string, required)
    - `legacyDefaults` (array of objects)
      - `globalAccountId` (string, required)
      - `code` (string, required)
      - `groupKey` (string, required)
      - `categoryKey` (string, nullable, required)
    - `groups` (array of objects, required)
      - `id` (string, required)
      - `key` (string, required)
      - `name` (string, required)
      - `status` (string, required)
      - `accountType` (string, required)
      - `description` (string, nullable, required)
      - `parentId` (string, nullable, required)
      - `sortOrder` (number, required)
      - `isHeading` (boolean, required)
      - `isAssignable` (boolean, required)
      - `allowGroupOnly` (boolean, required)
    - `categories` (array of objects, required)
      - `id` (string, required)
      - `key` (string, required)
      - `name` (string, required)
      - `status` (string, required)
      - `description` (string, required)
      - `codingGuidance` (string, nullable, required)
      - `defaultGroupId` (string, required)
      - `allowedGroupIds` (array of strings, required)
    - `workspaceId` (string, required)
    - `reportingInputsEnabled` (boolean, required)
  - `meta` (object)
    - `count` (number, required)
- `400`: Invalid entity ID
- `401`: Missing or invalid bearer authentication
- `403`: Bearer token is pinned to another entity
- `404`: Entity not found or access denied
- `500`: Unexpected failure loading the taxonomy
- `503`: Permission service temporarily unavailable

### Example (Node SDK)

```ts
const { data } = await prosaic.reportCategories.listForWorkspace();
```

### Example (curl)

```bash
curl https://app.prosaic.works/api/public/v1/report-categories \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## List report groups and categories for an entity

`GET /api/public/v1/entities/{entityId}/report-categories`

SDK: `prosaic.reportCategories.list(entityId)`

Returns the complete stored taxonomy for the authorised entity's country. Parent IDs and sort order describe the group tree. Headings are structure only; isAssignable=false prevents their selection. An ordinary group may allow a null category, but bank and asset-account functions can still require one. Category placements are exact, not inherited.
Examples: Operating expenses (exp.operating) is assignable with no category; Retained earnings (equ.retainedearnings) also permits a null category. Expenses (exp) is a heading and cannot be assigned. This endpoint does not change accounts. No country parameter or pagination is required.

### Path parameters

- `entityId` (string, required)

### Responses

- `200`: Successful response
  - `data` (object, required)
    - `country` (string, required)
    - `legacyDefaults` (array of objects)
      - `globalAccountId` (string, required)
      - `code` (string, required)
      - `groupKey` (string, required)
      - `categoryKey` (string, nullable, required)
    - `groups` (array of objects, required)
      - `id` (string, required)
      - `key` (string, required)
      - `name` (string, required)
      - `status` (string, required)
      - `accountType` (string, required)
      - `description` (string, nullable, required)
      - `parentId` (string, nullable, required)
      - `sortOrder` (number, required)
      - `isHeading` (boolean, required)
      - `isAssignable` (boolean, required)
      - `allowGroupOnly` (boolean, required)
    - `categories` (array of objects, required)
      - `id` (string, required)
      - `key` (string, required)
      - `name` (string, required)
      - `status` (string, required)
      - `description` (string, required)
      - `codingGuidance` (string, nullable, required)
      - `defaultGroupId` (string, required)
      - `allowedGroupIds` (array of strings, required)
    - `reportingInputsEnabled` (boolean, required)
  - `meta` (object)
    - `count` (number, required)
- `400`: Invalid entity ID
- `401`: Missing or invalid bearer authentication
- `403`: Bearer token is pinned to another entity
- `404`: Entity not found or access denied
- `500`: Unexpected failure loading the taxonomy
- `503`: Permission service temporarily unavailable

### Example (Node SDK)

```ts
const { data } = await prosaic.reportCategories.list(entityId);
```

### Example (curl)

```bash
curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/report-categories \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## List all global accounts

`GET /api/public/v1/global-accounts`

SDK: `prosaic.globalAccounts.list()`

Returns the full system account library (global accounts). These are the master accounts from which templates are built. Requires API key authentication.

### Responses

- `200`: Successful response
  - `data` (array of objects, required)
    - `id` (string, required)
    - `code` (string, required)
    - `name` (string, required)
    - `description` (string, nullable, required)
    - `type` (string, required)
    - `subtype` (string, required)
    - `isSystem` (boolean, required)
    - `taxCode` (string, nullable, required)
    - `metadata` (any, required)
  - `meta` (object)
    - `count` (number, required)
- `401`: Unauthorized - Invalid or missing API key

### Example (Node SDK)

```ts
const { data } = await prosaic.globalAccounts.list();
```

### Example (curl)

```bash
curl https://app.prosaic.works/api/public/v1/global-accounts \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```