RoboLedger: Setup

Create Entity

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.

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

Path parameters

graph_idstring required

Headers

Idempotency-Keystring nullable

Request body

namestring required

Display name.

legal_namestring nullable

Registered legal name. Defaults to name.

entity_typestring 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_idstring 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_idstring nullable

The entity this one is held under. Omit for the group parent; name a subsidiary to nest a sub-group under it.

ownership_pctnumber 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_onstring 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.

tickerstring 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.

uristring nullable

Canonical URL / external identifier.

cikstring nullable
sicstring nullable
sic_descriptionstring nullable
categorystring nullable
state_of_incorporationstring nullable
fiscal_year_endstring 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_idstring nullable
leistring nullable
industrystring nullable
phonestring nullable
websitestring nullable
address_line1string nullable
address_citystring nullable
address_statestring nullable
address_postal_codestring nullable
address_countrystring nullable

Example request

{
  "entity_type": "llc",
  "name": "Maple Court LLC",
  "ownership_pct": 100
}

Response

Successful Response

operationstring required

Kebab-case operation name

operationIdstring required

op_-prefixed ULID for audit and SSE correlation

status'completed' | 'pending' | 'failed' required

Operation lifecycle state

atstring required

ISO-8601 UTC timestamp

createdBystring nullable

User ID that initiated the operation

idempotentReplayboolean

True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.

Changes

No recorded changes to this operation across all 1 revision of this API.