Browse the extensions reference

Create Entity

post/extensions/roboledger/{graph_id}/operations/create-entity

Part of RoboLedger: Setup.

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.

Authentication

Authenticate in any one of these ways — not all of them:

  • API key in the X-API-Key header.
  • Bearer token in the Authorization header.

Path parameters

NameTypeDescription
graph_idrequiredstringGraph Id

Constraints: matches ^(kg[a-f0-9]{16,}(?:_[a-zA-Z0-9]{1,20})?|sec(?:_[a-zA-Z0-9]{1,20})?|library)$

Header parameters

NameTypeDescription
Idempotency-KeyoptionalstringIdempotency-Key

Request body

Required, application/json.

FieldTypeDescription
namerequiredstring

Display name.

Constraints: 1–255 characters

legal_nameoptionalstring

Registered legal name. Defaults to name.

entity_typeoptionalstring

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_idoptionalstring

Structure id of the Reporting Style to present under, validated in the graph like change-reporting-style. Omit to derive it from entity_type. A consolidation entity always takes the group parent's.

parent_entity_idoptionalstring

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

ownership_pctoptionalnumber

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.

Constraints: at most 100; greater than 0

consolidation_methodoptionalstring

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.

One of: full, equity, cost, none

entity_roleoptionalstring

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.

One of: operating, consolidation

joined_onoptionalstring (date)

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.

tickeroptionalstring

Short symbol, unique in the graph; it prefixes the entity's account names (coa-<ticker>:1000). Derived from the name's initials when omitted.

Constraints: 1–10 characters

urioptionalstring

Canonical URL / external identifier.

cikoptionalstring
sicoptionalstring
sic_descriptionoptionalstring
categoryoptionalstring
state_of_incorporationoptionalstring
fiscal_year_endoptionalstring

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_idoptionalstring
leioptionalstring
industryoptionalstring
phoneoptionalstring
websiteoptionalstring
address_line1optionalstring
address_cityoptionalstring
address_stateoptionalstring
address_postal_codeoptionalstring
address_countryoptionalstring

Example request

curl · example 1 of 4
curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/create-entity" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "entity_type": "llc",
  "name": "Maple Court LLC",
  "ownership_pct": 100
}'
curl · example 2 of 4
curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/create-entity" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "entity_type": "llc",
  "legal_name": "Harbor Property Management, LLC",
  "name": "Harbor Property Management LLC",
  "ownership_pct": 60,
  "parent_entity_id": "ent_01J9ZK3M4N5P6Q7R8S9T0V1W2X",
  "state_of_incorporation": "DE",
  "tax_id": "12-3456789",
  "ticker": "HPM"
}'
curl · example 3 of 4
curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/create-entity" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "entity_type": "llc",
  "name": "Pier Market Kiosk LLC",
  "ownership_pct": 40
}'
curl · example 4 of 4
curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/create-entity" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "entity_role": "consolidation",
  "entity_type": "llc",
  "name": "Consolidation Adjustments"
}'

Responses

200 Successful Response

FieldTypeDescription
operationrequiredstring

Kebab-case operation name

operationIdrequiredstring

op_-prefixed ULID for audit and SSE correlation

statusrequiredstring

Operation lifecycle state

One of: completed, pending, failed

resultoptionalLedgerEntityResponse

Command-specific result payload

LedgerEntityResponse fields
FieldTypeDescription
idrequiredstring

Entity identifier (ULID).

namerequiredstring

Display name shown in UI.

legal_nameoptionalstring

Full registered legal name (when different from name).

urioptionalstring

Canonical URL / external identifier.

cikoptionalstring

SEC CIK (Central Index Key).

tickeroptionalstring

Stock ticker symbol.

exchangeoptionalstring

Listing exchange (e.g. 'NASDAQ', 'NYSE').

sicoptionalstring

SIC industry code.

sic_descriptionoptionalstring

SIC code description.

categoryoptionalstring

Filer category (e.g. 'Large Accelerated Filer').

state_of_incorporationoptionalstring

US state or country of incorporation.

fiscal_year_endoptionalstring

Fiscal year-end as MM-DD (e.g. '12-31', '06-30').

tax_idoptionalstring

Tax ID (EIN / SSN).

leioptionalstring

Legal Entity Identifier (ISO 17442).

industryoptionalstring

Free-form industry label.

entity_typeoptionalstring

Legal form (e.g. 'corporation', 'llc', 'lp').

reporting_style_idoptionalstring

Active Reporting Style (Structure id) governing this entity's statement layout. Change it via the change-reporting-style operation.

phoneoptionalstring
websiteoptionalstring
statusoptionalstring

Operational status: 'active' | 'inactive' | 'dissolved'.

Default: active

is_parentoptionalboolean

True for top-level entities; False for subsidiaries.

Default: true

parent_entity_idoptionalstring

Parent entity ID for subsidiaries; null for top-level.

ownership_pctoptionalnumber

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_methodoptionalstring

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.

Default: none

entity_roleoptionalstring

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

joined_onoptionalstring (date)

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_onoptionalstring (date)

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.

is_formeroptionalboolean

True once the month this entity left the group is over: its months in the group are history, readable under it, and it is no longer current. False for a member still in, and through the month it leaves.

Default: false

sourceoptionalstring

Provenance: 'native' | 'sec' | 'quickbooks' | 'xero' | 'plaid'.

Default: native

source_idoptionalstring

Source-system primary key for sync reconciliation.

source_graph_idoptionalstring

Origin graph for received entities (cross-graph linking, e.g. RoboInvestor portfolio holdings).

connection_idoptionalstring

Source connection that ingested this row.

address_line1optionalstring
address_cityoptionalstring
address_stateoptionalstring
address_postal_codeoptionalstring
address_countryoptionalstring
created_atoptionalstring
updated_atoptionalstring
atrequiredstring

ISO-8601 UTC timestamp

createdByoptionalstring

User ID that initiated the operation

idempotentReplayoptionalboolean

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

Default: false

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