---
title: "Create a legal subsidiary"
method: POST
path: "/companies/{companyId}/entities"
tags: ["Company Settings"]
---

# Create a legal subsidiary

`POST /companies/{companyId}/entities`

## Request

- Base URL: `https://api.medianfi.com/api/v1`
- URL: `https://api.medianfi.com/api/v1/companies/{companyId}/entities`
- Auth: HTTP bearer

Admin/owner only. Creates persisted company accounting configuration; no demo data is generated.

## Request body

- CreateLegalEntityInput
  - `name` string, required
  - `shortName` string, nullable
  - `role` string, nullable
  - `functionalCurrency` string, required
  - `ownershipPct` number, nullable
  - `parentEntityId` string, uuid, nullable

## Response `201`

Legal entity created

- EntityResponse
  - `success` boolean
  - `data` Entity: A concrete legal entity under a company. Consolidated read identities live exclusively in ReportingScope and never appear as entities.
    - `id` string, uuid, required
    - `companyId` string, uuid, required
    - `name` string, required
    - `shortName` string, nullable
    - `role` string, nullable
    - `functionalCurrency` string, required: ISO 4217 functional currency code (e.g. USD, GBP).
    - `ownershipPct` number, nullable: Parent's ownership percentage of this entity, or null for the group/parent.
    - `parentEntityId` string, uuid, nullable
    - `isGroup` false, required: Deprecated compatibility field; Model A entities are always concrete.
    - `isPrimary` boolean, required: True for the one legal entity that owns legacy or otherwise unscoped accounting facts.

## Other responses

- `401`: Authentication required
- `403`: Insufficient permissions or not a company member
- `404`: Surface unavailable outside the allowlisted customer rollout
- `422`: Request failed validation

---

[API](https://skmtc.dev/medianfi/apis/median-api.md) · [All operations](https://skmtc.dev/medianfi/apis/median-api/llms.txt) · [OpenAPI document](https://skmtc.dev/medianfi/apis/median-api/revisions/20090ea32b0d?raw)