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

# Update Entity

`POST /extensions/roboledger/{graph_id}/operations/update-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/update-entity`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Update an entity of the graph's reporting group. Only provided (non-null) fields are updated. Omit `entity_id` to target the group parent; name a subsidiary's id to edit it. `ownership_pct` is refused on the group parent (422), and `ticker` must stay unique in the graph (409). `consolidation_method` overrides the treatment the share implies (a new share re-derives it unless both are given), `entity_role: consolidation` marks the group's entity for consolidating entries, and `joined_on` / `left_on` bound its membership by month — set `left_on` when a subsidiary leaves the group and its history stays readable under it.

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

- UpdateEntityRequest: Update an entity of the graph's reporting group. All fields are optional — pass only what changes. Identifiers (CIK, LEI, tax_id) are typically set once at onboarding; address fields are flattened to make them easy to project into reporting forms (1099, state filings). Omit `entity_id` to target the group parent.
  - `entity_id` string, nullable: The entity to update. Omit to target the group parent — the single-entity default.
  - `name` string, nullable
  - `legal_name` string, nullable
  - `uri` string, nullable
  - `cik` string, nullable
  - `ticker` string, nullable
  - `exchange` 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 (e.g. '12-31', '06-30').
  - `tax_id` string, nullable
  - `lei` string, nullable
  - `industry` string, nullable
  - `entity_type` 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
  - `ownership_pct` number, nullable: The parent's share of this entity, as a percent. Refused on the group parent, which has no owner in the graph. A new share re-derives `consolidation_method` unless that is given too.
  - `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. On the group parent and the consolidation entity only `none` holds.
  - `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`. Refused on the group parent. Marking an entity `consolidation` sets its method to `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. Pass null to clear it. Refused on the consolidation entity.
  - `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. Must not precede `joined_on`. Set it when a subsidiary is sold, dissolved or deconsolidated; its closed months and stamped statements stay readable under the group. Pass null to reopen membership. Refused on the consolidation entity.

## 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)