Initialize Chart of Accounts
/extensions/roboledger/{graph_id}/operations/initialize-chart-of-accountsPart of Extensions: RoboLedger.
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 graph's primary entity). One-time: 409 once a chart exists — 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.
Authentication
Authenticate in any one of these ways — not all of them:
- API key in the
X-API-Keyheader. - Bearer token in the
Authorizationheader.
Path parameters
| Name | Type | Description |
|---|---|---|
graph_idrequired | string | Graph Id |
Header parameters
| Name | Type | Description |
|---|---|---|
Idempotency-Keyoptional | string | Idempotency-Key |
Request body
Required, application/json.
| Field | Type | Description |
|---|---|---|
templaterequired | string | 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). One of: |
entity_typeoptional | string | Legal form for the equity mapping: `corporation`, `llc` or `partnership`. Defaults to the graph's primary entity, then to corporation. |
nameoptional | string | Chart display name. Defaults to 'Chart of Accounts'. |
Example request
curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/initialize-chart-of-accounts" \
-H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
-H "Idempotency-Key: <Idempotency-Key>" \
-H "Content-Type: application/json" \
-d '{
"template": "saas"
}'Responses
200 Successful Response
| Field | Type | Description | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
operationrequired | string | Kebab-case operation name | |||||||||||||||||||||||||||
operationIdrequired | string | op_-prefixed ULID for audit and SSE correlation | |||||||||||||||||||||||||||
statusrequired | string | Operation lifecycle state One of: | |||||||||||||||||||||||||||
resultoptional | InitializeChartOfAccountsResponse | Command-specific result payload InitializeChartOfAccountsResponse fields
| |||||||||||||||||||||||||||
atrequired | string | ISO-8601 UTC timestamp | |||||||||||||||||||||||||||
createdByoptional | string | User ID that initiated the operation (null for legacy callers) | |||||||||||||||||||||||||||
idempotentReplayoptional | boolean | True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions. Default: |
| Status | Meaning |
|---|---|
| 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 |