> ## Documentation Index
> Fetch the complete documentation index at: https://docs.commenda.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Business entity API
> Manage business entities and their core information
## Overview
The Business Entity API provides endpoints for managing legal business entities (corporations, LLCs, partnerships, etc.) and their associated data including locations, persons, government identifiers, registrations, documents, and credentials.
## Core endpoints
### Get business entity
Retrieve a single business entity by ID.
```http theme={null}
GET /business-entity/:businessEntityId
```
**Path parameters**
| Parameter | Type | Description |
| ------------------ | ------- | ----------------------------------------- |
| `businessEntityId` | integer | Unique identifier for the business entity |
**Query parameters**
| Parameter | Type | Description |
| --------- | --------- | ---------------------------------------------------------------- |
| `extends` | string\[] | Optional fields to include: `governmentIdentifiers`, `locations` |
**Response**
```json theme={null}
{
"id": 123,
"legalName": "Acme Corporation",
"dbaName": "Acme",
"incorporationCountry": "US",
"incorporationJurisdiction": "DE",
"entityType": "C_CORP",
"formationDate": "2020-01-15",
"businessDescription": "Software development",
"fiscalYearEnd": "12-31",
"accountingBasis": "ACCRUAL",
"governmentIdentifiers": [...],
"locations": [...]
}
```
### Update business entity
Update core business entity information.
```http theme={null}
POST /business-entity/:businessEntityId
```
**Path parameters**
| Parameter | Type | Description |
| ------------------ | ------- | ----------------------------------------- |
| `businessEntityId` | integer | Unique identifier for the business entity |
**Request body**
```json theme={null}
{
"legalName": "Acme Corporation Inc.",
"dbaName": "Acme",
"businessDescription": "Enterprise software development",
"fiscalYearEnd": "12-31",
"accountingBasis": "ACCRUAL",
"taxClassification": "C_CORP"
}
```
**Response**
Returns `200 OK` on success.
### List business entities
Get all business entities for a company.
```http theme={null}
GET /business-entity/list/company/:companyId
```
**Path parameters**
| Parameter | Type | Description |
| ----------- | ------- | --------------------------------- |
| `companyId` | integer | Unique identifier for the company |
**Response**
```json theme={null}
{
"entities": [
{
"id": 123,
"legalName": "Acme Corporation",
"incorporationCountry": "US",
"incorporationJurisdiction": "DE"
}
]
}
```
Business entities the customer has marked as **non-controlled** (for example, an external parent holding company recorded only to complete the ownership graph) are excluded from this listing. Use [Get business entity](#get-business-entity) by id to read a non-controlled entity directly, or fetch the company's organizational structure to see them in context.
### Get organizational structure
Retrieve the full ownership graph for a company, including non-controlled parent entities. The response is the union of every entity the company owns or that owns into the company, plus the ownership edges between them.
```http theme={null}
GET /business-entity/list/company/:companyId/org-structure
```
**Path parameters**
| Parameter | Type | Description |
| ----------- | ------- | --------------------------------- |
| `companyId` | integer | Unique identifier for the company |
**Response**
```json theme={null}
{
"entities": [
{
"id": 123,
"legalName": "Acme Corporation",
"incorporationCountry": "US",
"businessEntityType": "C_CORP",
"keyPersons": { "data": [{ "directorId": 42, "name": "Jane Founder" }], "count": 1 },
"bankAccounts": { "data": [], "count": 0 },
"taxClassification": "C_CORP"
}
],
"edges": [
{
"fromCorporationId": 124,
"toCorporationId": 123,
"ownershipPercent": 1000000,
"dilutedOwnershipPercent": 500000,
"stockClassId": "stk_class_abc123",
"hasSignificantControl": true
}
],
"stockClasses": [
{
"id": "stk_class_abc123",
"corporationId": 123,
"name": "Class A Common",
"initialSharesAuthorized": 1000
}
],
"percentScale": 1000000
}
```
| Field | Type | Description |
| ---------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entities[]` | array | All entities reachable in the ownership graph, including non-controlled parents. |
| `edges[]` | array | Directed `from → to` ownership edges. `from` is the shareholder, `to` is the owned entity. |
| `edges[].ownershipPercent` | integer | Raw ownership percentage within the share class, scaled by `percentScale` (e.g. `1000000` with `percentScale: 1000000` represents 100%). |
| `edges[].dilutedOwnershipPercent` | integer | Ownership percentage relative to the target corporation's total authorized shares across all classes, scaled by `percentScale`. Falls back to `ownershipPercent` when the corporation's classes have incomplete authorized share data, or when the stakeholding has no associated stock class. Use this value to label org chart edges. |
| `edges[].stockClassId` | string \| null | Identifier of the stock class this edge represents. `null` for legacy stakeholdings without an explicit class. Look up class detail in the top-level `stockClasses` array. |
| `edges[].hasSignificantControl` | boolean | Whether the shareholder has been flagged as exercising significant control. |
| `stockClasses[]` | array | Flat list of stock classes for every corporation in the graph. Group by `corporationId` to render per-issuer detail. |
| `stockClasses[].id` | string | Stock class identifier, referenced by `edges[].stockClassId`. |
| `stockClasses[].corporationId` | integer | Corporation that issued the class. |
| `stockClasses[].name` | string | Human-readable name of the share class (for example, `Class A Common`). |
| `stockClasses[].initialSharesAuthorized` | integer \| null | Total shares authorized for the class. `null` when not recorded; if any class on a corporation is missing this value, diluted percentages on that corporation's edges fall back to the raw `ownershipPercent`. |
| `percentScale` | integer | Divisor applied to every `ownershipPercent` and `dilutedOwnershipPercent` value in the response. |
This is the only listing surface that surfaces non-controlled entities by design — it powers the org chart visualization.
## Key persons
### Add key person
Associate a person with a business entity.
```http theme={null}
POST /business-entity/:businessEntityId/persons/:personId
```
**Path parameters**
| Parameter | Type | Description |
| ------------------ | ------- | ------------------ |
| `businessEntityId` | integer | Business entity ID |
| `personId` | integer | Person ID |
**Request body**
```json theme={null}
{
"role": "DIRECTOR",
"startDate": "2020-01-15",
"endDate": null,
"ownershipPercentage": 25.5,
"isResidentDirector": true
}
```
| Field | Type | Description |
| --------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `role` | string | Governance role (e.g. `DIRECTOR`, `OFFICER`, `SHAREHOLDER`) |
| `startDate` | string | Date the person assumed the role (ISO 8601) |
| `endDate` | string \| null | Date the person left the role, if applicable |
| `ownershipPercentage` | number | Equity ownership percentage |
| `isResidentDirector` | boolean | Whether the person is a resident director of this entity. Used in jurisdictions that require at least one locally resident director (e.g. India). Optional. |
When you read a person back through the Commenda OS persons endpoints, the response includes a `governanceRelationships` object keyed by role. The set of keys present is a subset of `DIRECTOR`, `AUTHORIZED_SIGNATORY`, and `BENEFICIAL_OWNER`. The `BENEFICIAL_OWNER` key is set automatically by Commenda's ownership engine when the person is currently recorded as an ultimate beneficial owner (UBO) of the business entity — it is not assigned through this endpoint.
**Response**
Returns `200 OK` on success.
### Remove key person
Remove a person from a business entity.
```http theme={null}
DELETE /business-entity/:businessEntityId/persons/:personId
```
**Path parameters**
| Parameter | Type | Description |
| ------------------ | ------- | ------------------ |
| `businessEntityId` | integer | Business entity ID |
| `personId` | integer | Person ID |
**Response**
Returns `204 No Content` on success.
## Assignments
### Unassign business entity
Remove a business entity from a company.
```http theme={null}
POST /business-entity/unassign
```
**Request body**
```json theme={null}
{
"businessEntityId": 123
}
```
**Response**
Returns `200 OK` on success.
## Related resources
* [Locations API](/engine/commendaos/locations) - Manage business entity addresses
* [Government Identifiers API](/engine/commendaos/government-identifiers) - Manage tax IDs and official numbers
* [Registrations API](/engine/commendaos/registrations) - Manage government registrations
* [Documents API](/engine/commendaos/documents) - Manage entity documents
* [Credentials API](/engine/commendaos/credentials) - Manage portal access credentials