---
title: "Create Entity"
method: POST
path: "/extensions/roboledger/{graph_id}/operations/create-entity"
tags: ["RoboLedger: Setup"]
---

# Create Entity

`POST /extensions/roboledger/{graph_id}/operations/create-entity`

## 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/create-entity`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Add an entity to the graph's reporting group: a subsidiary under `parent_entity_id` (default the group parent) that keeps its own books, chart of accounts and close, on the group's fiscal cadence. A graph created without an entity gets this one as its group parent. Creates the entity row only — give it a chart next (initialize-chart-of-accounts with `entity_id`) and a calendar (initialize with `entity_id`); from then on every ledger operation takes `entity_id` to act in its books, and omitting it means the group parent. The Reporting Style follows `entity_type` unless `reporting_style_id` names one. `ticker` prefixes the entity's account names and must be unique in the graph (409). There is no cap on entities: a graph is one reporting group, and everyone with access to it sees every entity. `ownership_pct` implies the `consolidation_method` (50 and above full, 20 to 50 equity, below 20 cost) unless one is given; `entity_role: consolidation` makes this the group's entity for consolidating entries, read by the consolidated statements only; `joined_on` dates an acquired subsidiary's membership.

**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

- CreateEntityRequest: Add an entity to the graph's reporting group. The new entity is a subsidiary of `parent_entity_id`, default the group parent, and keeps its own books: give it a chart next (`initialize-chart-of-accounts` with `entity_id`) and a calendar (`initialize`), then name it with `entity_id` on any ledger operation. A graph created without an entity gets this one as its group parent. There is no cap on entities in a graph; capacity is the tier's.
  - `name` string, required: Display name.
  - `legal_name` string, nullable: Registered legal name. Defaults to `name`.
  - `entity_type` string, nullable: Legal form: `corporation`, `llc`, `partnership`, `sole_proprietorship`, `non_profit`. Picks the default Reporting Style (partnership and llc have equity-form Styles of their own; anything else is corporate) and the equity rows of a chart template.
  - `reporting_style_id` string, nullable: Structure id of the Reporting Style to present under, validated in the graph like change-reporting-style. Omit to derive it from `entity_type`.
  - `parent_entity_id` string, nullable: The entity this one is held under. Omit for the group parent; name a subsidiary to nest a sub-group under it.
  - `ownership_pct` number, nullable: The parent's share of this entity, as a percent (100 = wholly owned). Omit when not recorded. Refused on a graph's first entity, which becomes the group parent.
  - `consolidation_method` 'full' | 'equity' | 'cost' | 'none', nullable: How the group's consolidated statements treat this entity: `full` (its books are summed and an outside owner's share is carried as noncontrolling interest), `equity` (one investment line and one income line), `cost` (an investment at cost) or `none` (the group parent, the consolidation entity, a linked counterparty). Derived from `ownership_pct` when not given — 50 and above `full`, 20 to 50 `equity`, below 20 `cost`, unrecorded `full` — and set by a person where control is not the percentage: a managing member with a minority stake consolidates in full, a majority without control takes the equity method. Omit to derive it; a graph's first entity and a `consolidation` entity take `none`.
  - `entity_role` 'operating' | 'consolidation', nullable: `operating` keeps a company's books. `consolidation` is the group's one entity for the consolidating entries — eliminations, noncontrolling interest, the equity-method pick-up — the adjustments column of a consolidation worksheet, which only the consolidated statements read and no operating company's statements ever include. Its method is `none`. Default `operating`; a graph's first entity, its group parent, is always operating. Start a consolidation entity's chart from the `consolidation` template.
  - `joined_on` string, date, nullable: The month this entity became a member of the group, as any date in it; null is a member since the beginning. The consolidated statements include it from that month. Membership is by month: a period column wider than a month that overlaps the interval is summed whole, so a member's books in this graph should hold only the months it belonged. Omit for a subsidiary formed by the parent; give the acquisition month for one acquired, whose books in this graph then hold only what follows it. Refused on the consolidation entity.
  - `ticker` string, nullable: Short symbol, unique in the graph; it prefixes the entity's account names (`coa-<ticker>:1000`). Derived from the name's initials when omitted.
  - `uri` string, nullable: Canonical URL / external identifier.
  - `cik` string, nullable
  - `sic` string, nullable
  - `sic_description` string, nullable
  - `category` string, nullable
  - `state_of_incorporation` string, nullable
  - `fiscal_year_end` string, nullable: Fiscal year-end as MM-DD. Defaults to the parent's: a graph has one fiscal cadence, and every entity's calendar follows it.
  - `tax_id` string, nullable
  - `lei` string, nullable
  - `industry` string, nullable
  - `phone` string, nullable
  - `website` string, nullable
  - `address_line1` string, nullable
  - `address_city` string, nullable
  - `address_state` string, nullable
  - `address_postal_code` string, nullable
  - `address_country` string, nullable

## Response `200`

Successful Response

- OperationEnvelopeLedgerEntityResponse
  - `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` LedgerEntityResponse: Entity details from the extensions OLTP database. Returned by entity reads and `update-entity`. Identifiers (CIK / ticker / SIC / LEI / tax_id) are present when sourced from SEC or registry data; many are null for private companies. The address fields are flattened (no nested object) to make them easy to project into reporting forms.
    - `id` string, required: Entity identifier (ULID).
    - `name` string, required: Display name shown in UI.
    - `legal_name` string, nullable: Full registered legal name (when different from `name`).
    - `uri` string, nullable: Canonical URL / external identifier.
    - `cik` string, nullable: SEC CIK (Central Index Key).
    - `ticker` string, nullable: Stock ticker symbol.
    - `exchange` string, nullable: Listing exchange (e.g. 'NASDAQ', 'NYSE').
    - `sic` string, nullable: SIC industry code.
    - `sic_description` string, nullable: SIC code description.
    - `category` string, nullable: Filer category (e.g. 'Large Accelerated Filer').
    - `state_of_incorporation` string, nullable: US state or country of incorporation.
    - `fiscal_year_end` string, nullable: Fiscal year-end as MM-DD (e.g. '12-31', '06-30').
    - `tax_id` string, nullable: Tax ID (EIN / SSN).
    - `lei` string, nullable: Legal Entity Identifier (ISO 17442).
    - `industry` string, nullable: Free-form industry label.
    - `entity_type` string, nullable: Legal form (e.g. 'corporation', 'llc', 'lp').
    - `reporting_style_id` string, nullable: Active Reporting Style (Structure id) governing this entity's statement layout. Change it via the change-reporting-style operation.
    - `phone` string, nullable
    - `website` string, nullable
    - `status` string: Operational status: 'active' | 'inactive' | 'dissolved'.
    - `is_parent` boolean: True for top-level entities; False for subsidiaries.
    - `parent_entity_id` string, nullable: Parent entity ID for subsidiaries; null for top-level.
    - `ownership_pct` number, nullable: The parent's share of this entity, as a percent (100 = wholly owned). Null on the group parent, and where it was never recorded.
    - `consolidation_method` string: How the group's consolidated statements treat this entity: `full` (its books are summed and an outside owner's share is carried as noncontrolling interest), `equity` (one investment line and one income line), `cost` (an investment at cost) or `none` (the group parent, the consolidation entity, a linked counterparty). Derived from `ownership_pct` when not given — 50 and above `full`, 20 to 50 `equity`, below 20 `cost`, unrecorded `full` — and set by a person where control is not the percentage: a managing member with a minority stake consolidates in full, a majority without control takes the equity method.
    - `entity_role` string: `operating` keeps a company's books. `consolidation` is the group's one entity for the consolidating entries — eliminations, noncontrolling interest, the equity-method pick-up — the adjustments column of a consolidation worksheet, which only the consolidated statements read and no operating company's statements ever include. Its method is `none`.
    - `joined_on` string, date, nullable: The month this entity became a member of the group, as any date in it; null is a member since the beginning. The consolidated statements include it from that month. Membership is by month: a period column wider than a month that overlaps the interval is summed whole, so a member's books in this graph should hold only the months it belonged.
    - `left_on` string, date, nullable: The month this entity left the group, as any date in it; null is a member still. The consolidated statements include it through that month and leave it out after. Membership is by month: a period column wider than a month that overlaps the interval is summed whole, so a member's books in this graph should hold only the months it belonged.
    - `source` string: Provenance: 'native' | 'sec' | 'quickbooks' | 'xero' | 'plaid'.
    - `source_id` string, nullable: Source-system primary key for sync reconciliation.
    - `source_graph_id` string, nullable: Origin graph for received entities (cross-graph linking, e.g. RoboInvestor portfolio holdings).
    - `connection_id` string, nullable: Source connection that ingested this row.
    - `address_line1` string, nullable
    - `address_city` string, nullable
    - `address_state` string, nullable
    - `address_postal_code` string, nullable
    - `address_country` string, nullable
    - `created_at` string, nullable
    - `updated_at` string, nullable
  - `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)