---
title: "Initialize Chart of Accounts"
method: POST
path: "/extensions/roboledger/{graph_id}/operations/initialize-chart-of-accounts"
tags: ["RoboLedger: Setup"]
---

# Initialize Chart of Accounts

`POST /extensions/roboledger/{graph_id}/operations/initialize-chart-of-accounts`

## Request

- Base URL: `https://api.robosystems.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/initialize-chart-of-accounts`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Create the graph's chart of accounts from a shipped template — the fresh-company path to native books. Use when the graph has NO chart (a QuickBooks-synced tenant never needs this: its chart arrives with the sync and stays after a sever) and before connecting a bank feed, which needs a chart to resolve against. Templates: `saas` (subscription software), `services` (professional services), `product` (inventory and COGS) — the `chartTemplates` GraphQL field lists them with names and account counts. Creates the chart, its `coa_mapping` structure and the template's CoA → rs-gaap mapping associations in one transaction, with the equity rows mapped by the entity's legal form (`entity_type`, defaulting to the entity's). Each entity of the group keeps its own chart: `entity_id` names a subsidiary, omitted means the group parent. One-time per entity: 409 once that entity has a chart — a chart is never replaced. Customize afterwards with update-taxonomy-block; accounts that carry activity are never deleted.

**Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.

## Path parameters

- `graph_id` string, required

## Headers

- `Idempotency-Key` string, nullable

## Request body

- InitializeChartOfAccountsRequest: Create the graph's chart of accounts from a shipped template. Refused (409) when the entity already has an active `chart_of_accounts` taxonomy — a QuickBooks-synced tenant never needs this, and a chart is never replaced. Each entity of the group keeps its own chart; omit `entity_id` for the group parent. The template's equity rows are mapped by the entity's legal form (`entity_type`: corporation / llc / partnership); omit it to use the graph's primary entity, falling back to corporation.
  - `entity_id` string, nullable: The entity to give a chart to, by id. Omit for the group parent. A sibling already having one is no bar.
  - `template` 'saas' | 'services' | 'product' | 'consolidation', required: Template key: `saas` (subscription software — deferred revenue, cost of revenue, R&D / S&M / G&A), `services` (professional services — no inventory, no COGS), `product` (inventory and cost of goods sold, direct + wholesale + subscription revenue), `consolidation` (a group's consolidation entity: the eliminated investment, intercompany and subsidiary-equity rows, noncontrolling interest and its share of income — the adjustments column, never an operating company's chart).
  - `entity_type` string, nullable: Legal form for the equity mapping: `corporation`, `llc` or `partnership`. Defaults to the graph's primary entity, then to corporation.
  - `name` string, nullable: Chart display name. Defaults to 'Chart of Accounts'.

## Response `200`

Successful Response

- OperationEnvelopeInitializeChartOfAccountsResponse
  - `operation` string, required: Kebab-case operation name
  - `operationId` string, required: op_-prefixed ULID for audit and SSE correlation
  - `status` 'completed' | 'pending' | 'failed', required: Operation lifecycle state
  - `result` InitializeChartOfAccountsResponse
    - `taxonomy_id` string, required: The new chart's taxonomy id.
    - `name` string, required
    - `template` 'saas' | 'services' | 'product' | 'consolidation', required
    - `entity_type` string, required: Legal form the equity rows were mapped for.
    - `elements_created` integer, required
    - `mappings_created` integer, required
    - `frameworks` string[]: Frameworks the chart was mapped into — each template mapping set whose framework this graph's library carries (rs-gaap today; every framework in the graph's pin once it is plural).
    - `unresolved` string[]: What could not be mapped, never fatal — the accounts exist and can be mapped by hand: a target qname the framework's library copy did not resolve, `<framework>: not in this graph's library` for a template mapping set whose framework this graph does not carry, or a template row naming an account it does not declare.
  - `at` string, required: ISO-8601 UTC timestamp
  - `createdBy` string, nullable: User ID that initiated the operation
  - `idempotentReplay` boolean: True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.

## Other responses

- `400`: Invalid request
- `401`: Authentication required
- `403`: Access denied
- `404`: Resource not found
- `409`: Idempotency-Key conflict — key reused with different body
- `422`: Validation error
- `429`: Rate limit exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/robosystems/apis/robosystems-api.md) · [All operations](https://skmtc.dev/robosystems/apis/robosystems-api/llms.txt) · [OpenAPI document](https://skmtc.dev/robosystems/apis/robosystems-api/revisions/e661e2d5ca6a?raw)