Business entity API

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.

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

{
  "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.

POST /business-entity/:businessEntityId

Path parameters

Parameter	Type	Description
`businessEntityId`	integer	Unique identifier for the business entity

Request body

{
  "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.

GET /business-entity/list/company/:companyId

Path parameters

Parameter	Type	Description
`companyId`	integer	Unique identifier for the company

Response

{
  "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 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.

GET /business-entity/list/company/:companyId/org-structure

Path parameters

Parameter	Type	Description
`companyId`	integer	Unique identifier for the company

Response

{
  "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.

POST /business-entity/:businessEntityId/persons/:personId

Path parameters

Parameter	Type	Description
`businessEntityId`	integer	Business entity ID
`personId`	integer	Person ID

Request body

{
  "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.

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.

POST /business-entity/unassign

Request body

{
  "businessEntityId": 123
}

Response Returns 200 OK on success.

Locations API - Manage business entity addresses
Government Identifiers API - Manage tax IDs and official numbers
Registrations API - Manage government registrations
Documents API - Manage entity documents
Credentials API - Manage portal access credentials

Overview

Customer setup

Partner Incorporation API

Commenda OS Partner API

Webhooks

Overview

Core endpoints

Get business entity

Update business entity

List business entities

Get organizational structure

Key persons

Add key person

Remove key person

Assignments

Unassign business entity

​Overview

​Core endpoints

​Get business entity

​Update business entity

​List business entities

​Get organizational structure

​Key persons

​Add key person

​Remove key person

​Assignments

​Unassign business entity

​Related resources

Overview

Core endpoints

Get business entity

Update business entity

List business entities

Get organizational structure

Key persons

Add key person

Remove key person

Assignments

Unassign business entity

Related resources