CreateEntityRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/robosystems-ai/json-schema/robosystems-ai-create-entity-request-schema.json",
  "title": "CreateEntityRequest",
  "description": "Add an entity to the graph's reporting group.\n\nThe new entity is a subsidiary of `parent_entity_id`, default the group\nparent, and keeps its own books: give it a chart next\n(`initialize-chart-of-accounts` with `entity_id`) and a calendar\n(`initialize`), then name it with `entity_id` on any ledger operation.\nA graph created without an entity gets this one as its group parent.\nThere is no cap on entities in a graph; capacity is the tier's.",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/robosystems-ai-openapi.json#/components/schemas/CreateEntityRequest",
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1,
      "title": "Name",
      "description": "Display name."
    },
    "legal_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Legal Name",
      "description": "Registered legal name. Defaults to `name`."
    },
    "entity_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Entity Type",
      "description": "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": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Reporting Style Id",
      "description": "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": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Parent Entity Id",
      "description": "The entity this one is held under. Omit for the group parent; name a subsidiary to nest a sub-group under it."
    },
    "ownership_pct": {
      "anyOf": [
        {
          "type": "number",
          "maximum": 100.0,
          "exclusiveMinimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Ownership Pct",
      "description": "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": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "full",
            "equity",
            "cost",
            "none"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Consolidation Method",
      "description": "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": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "operating",
            "consolidation"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Entity Role",
      "description": "`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": {
      "anyOf": [
        {
          "type": "string",
          "format": "date"
        },
        {
          "type": "null"
        }
      ],
      "title": "Joined On",
      "description": "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": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 10,
          "minLength": 1
        },
        {
          "type": "null"
        }
      ],
      "title": "Ticker",
      "description": "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": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Uri",
      "description": "Canonical URL / external identifier."
    },
    "cik": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Cik"
    },
    "sic": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sic"
    },
    "sic_description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sic Description"
    },
    "category": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Category"
    },
    "state_of_incorporation": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "State Of Incorporation"
    },
    "fiscal_year_end": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Fiscal Year End",
      "description": "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": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Tax Id"
    },
    "lei": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Lei"
    },
    "industry": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Industry"
    },
    "phone": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Phone"
    },
    "website": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Website"
    },
    "address_line1": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Address Line1"
    },
    "address_city": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Address City"
    },
    "address_state": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Address State"
    },
    "address_postal_code": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Address Postal Code"
    },
    "address_country": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Address Country"
    }
  },
  "type": "object",
  "required": [
    "name"
  ]
}