Back to Docs

Chart of accounts

Templates, an entity's own accounts, system accounts, and adding or changing accounts.

Every entity has its own chart of accounts. It is copied from a template when the entity is created, and journal lines name its accounts by code.

In the new chart architecture, each account has its own code and an explicit reporting placement. The placement consists of a report group and, where applicable, a report category.

There are two levels, and their IDs are not interchangeable:

LevelWhat it isRead with
TemplateA workspace-level blueprint that entities are created from.charts.list, charts.listAccounts
EntityThe accounts one entity actually posts to.entityAccounts.list

Post journals against the entity's accounts. Template account IDs are never valid on a journal.

An entity's accounts

ts
const accounts = await prosaic.entityAccounts
  .list(entityId)
  .autoPagingToArray({ limit: 1000 });
bash
curl https://app.prosaic.works/api/public/v1/entities/YOUR_ENTITY_ID/charts \
  -H "Authorization: Bearer $PROSAIC_API_KEY"

Each account has:

FieldNotes
idThe entity account's ID.
codeWhat journal lines send as entityAccountCode, for example 4030.
nameFor example Office Expense.
typeAsset, Liability, Equity, Revenue or Expense.
subtypeStored legacy compatibility data; use the saved reporting pair for classification.
taxCodeThe account's default tax code, such as NZ_GST_15_EXP.
mappedCodeOptional alternate code for a workflow that uses different codes.
isSystemtrue for accounts Prosaic relies on, such as GST, Rounding and Retained Earnings.
parentIdA legacy hierarchy reference. Use the saved reporting pair for placement.
sourcetemplate, overridden (a template account changed for this entity) or custom.

Query options:

  • includeSystem=false leaves out system accounts (it defaults to true).
  • includeExcluded=true adds template accounts that have been hidden from this entity, flagged isExcluded: true.

In the SDK these are strings: { includeSystem: 'false' }.

An account's taxCode is a default, not a rule: each journal line names its own tax rate. If an entity is created without isGstRegistered: true, every account defaults to its country's "No GST" code.

Bank accounts linked to an entity get their own account in the chart. You can find it at bankAccounts[].entityAccount on the entity in GET /entities.

Changing an entity's chart

All of these are on entityAccounts, under /entities/{entityId}/charts:

MethodWhat it does
create(entityId, params)Adds an account with reporting choices when inputs are enabled; uses a parent otherwise.
update(entityId, accountId, params)Updates eligible account metadata or reporting. Parent account fields have additional restrictions in earlier workspaces.
del(entityId, accountId)Deletes an eligible custom account or excludes a template-linked account so restore can bring it back.
restore(entityId, templateAccountId)Brings back a hidden template account.
reset(entityId, accountId)Returns a changed template account to the template's values.

Adding an account:

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

Call reportCategories.list(entityId) first. In enabled workspaces, choose an active assignable group and an eligible category or explicit null. Account type derives from the group. Bank and other verified functions can require a category. Do not send a parent with the pair. Nonactivated workspaces retain the legacy parent-based write shape and reject explicit assignment writes.

Codes contain only digits and dots. Use the firm's own account code for posting, and keep the account ID when renaming it. A report group places the account in a report section. A category adds detail within that section. Each account has one saved pair even when discovery lists the same category under several groups. Compare the selected group's ID with the category's allowedGroupIds and send the keys in the write.

If the firm recodes an account, reread the chart and refresh any rules, imports or integrations that reference the old code. Use the entity editor or pass code to the SDK’s entityAccounts.update to change an eligible account code. The MCP update_chart_account tool currently exposes other account fields.

Discovery and conflict handling

Before an entity exists, call reportCategories.listForWorkspace() (GET /api/public/v1/report-categories). It uses the authorised workspace, returns workspaceId, country, groups, categories and reportingInputsEnabled, and accepts no country override. Entity discovery uses all active connected workspaces. The capability is observational; writes recheck policy and permissions.

ts
const { data: taxonomy } = await prosaic.reportCategories.listForWorkspace();
const group = taxonomy.groups.find((g) => g.key === 'exp.operating');
if (!group?.isAssignable) throw new Error('Assignable group unavailable');

A metadata-only patch preserves classification:

ts
await prosaic.entityAccounts.update(entityId, accountId, {
  description: 'Monthly subscriptions',
});

Read current assignments before editing. Include the saved pair in expected; explicit null means it was unassigned. A valid group-only edit has categoryKey: null:

ts
await prosaic.entityAccounts.update(entityId, accountId, {
  reporting: {
    groupKey: 'exp.operating',
    categoryKey: null,
    expected: {
      groupKey: current.reportGroup.key,
      categoryKey: current.reportCategory?.key ?? null,
    },
  },
});

Missing, mixed or invalid choices return 400 VALIDATION_ERROR. 409 CHART_INPUT_CONTRACT_MISMATCH requires rediscovery. Other stale-state conflicts require rereading and reviewing current data before another save. Policy evaluation failure returns 503 CHART_INPUT_POLICY_UNAVAILABLE. Never retry a mutation automatically with a different shape. Read-only subtype compatibility and trial-balance groupBy=subtype remain available; their retirement is separate.

Templates

Templates live in the workspace. A new workspace starts with five: a standard chart for its country (Standard NZ Business Template or Standard AU Business Template) and the Company, Trust, Sole Trader and Partnership charts. The standard chart carries the workspace's own GST codes.

MethodWhat it does
charts.list()The workspace's templates, with an account count for each.
charts.listAccounts(chartId)A template's accounts. includeHidden: true adds global accounts not in it.
charts.create(params)Creates a template from a list of accounts.
charts.update(chartId, params)Renames it, or replaces its whole account list.
charts.createAccount, updateAccount, deleteAccountChanges one account in a template.
charts.del(chartId)Deletes a template no entity uses.
globalAccounts.list()Standard accounts for the earlier chart contract.

Template metadata propagation respects entity overrides. Reporting changes require human review and propagation approval. API and OAuth credentials cannot confirm template review, approve propagation or bypass role locks.

In enabled workspaces, included template rows carry groupKey, explicit categoryKey (nullable), and required system-role mappings. A full replacement includes stable existing row id values and row expectedUpdatedAt values, plus the template expectedUpdatedAt. Keep IDs when codes change. API-created or changed pairs remain unreviewed. A person must confirm them in the chart editor before application. First-use role locks remain permanent. Nonactivated workspaces keep the legacy global-library/system-account flow.

Before replacing the account list, read every page with charts.listAccounts(chartId) and check that each response has the same templateUpdatedAt. Send that version as the template's expectedUpdatedAt. If the version changes between pages, discard the partial list and start again.

Two details catch people out:

  • Template reads show tax names, writes take tax codes. charts.listAccounts returns a tax name such as 15% GST on Income in taxCode. When you write a template, send the machine code (NZ_GST_15_INC) instead. Entity accounts return the machine code.
  • Template IDs are not entity IDs. An entity's currentTemplateId names the template it was created from, not its chart. Read the chart with entityAccounts.list.