> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cadanapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Entity Management

> Manage legal sub-entities for global payroll across jurisdictions

export const ApiExample = ({method = "GET", path, params, body, reference, tenantKey}) => {
  const baseUrl = "https://api.cadanapay.com";
  const query = params ? "?" + Object.entries(params).map(([k, v]) => `${k}=${v}`).join("&") : "";
  const url = `${baseUrl}${path}${query}`;
  const isPlatformPath = (/^\/(v1\/)?platform(\/|$)/).test(path || "");
  const includeTenantKey = tenantKey === undefined ? !isPlatformPath : tenantKey;
  let curl = `curl -X ${method} '${url}' \\\n  -H 'Authorization: Bearer YOUR_API_KEY'`;
  if (includeTenantKey) {
    curl += ` \\\n  -H 'X-MultiTenantKey: YOUR_BUSINESS_TENANT_KEY'`;
  }
  if (body) {
    const formatted = JSON.stringify(body, null, 2);
    curl += ` \\\n  -H 'Content-Type: application/json' \\\n  -d '${formatted}'`;
  }
  return <div>
      <CodeBlock language="bash" filename="bash" wrap>
        {curl}
      </CodeBlock>
      {reference && <div style={{
    marginTop: "-0.5rem",
    marginBottom: "1rem"
  }}>
          <a href={reference} style={{
    fontSize: "0.875rem"
  }}>
            Try it in the playground →
          </a>
        </div>}
    </div>;
};

Every organisation on Cadana starts with a **Business** — the top-level legal entity you created during onboarding (or via the Platform API). An **Entity** is a child of that business: a subsidiary, branch, or regional office that operates in a different jurisdiction under the same tenant.

```mermaid theme={null}
flowchart TD
    BIZ["Business (Parent)
    Acme Inc · US · USD"] --> E1["Entity
    Acme UK Ltd · GB · GBP"]
    BIZ --> E2["Entity
    Acme GmbH · DE · EUR"]
    BIZ --> E3["Entity
    Acme Nigeria Ltd · NG · NGN"]
```

Each entity has its own legal name, country, currency, registration number, tax ID, and address. When a person is linked to an entity, that entity's details — not the parent business's — are used for statutory filings and government remittances.

<Tip>
  If your company operates in a single jurisdiction, you don't need entities — the parent business is sufficient. Entities are designed for **global payroll** where you need distinct employer identities per country.
</Tip>

***

## Prerequisites

<Steps>
  <Step title="API key from Dashboard">
    Get your API key from the [Cadana Dashboard](https://app.cadanapay.com). See [Authentication](/authentication) for details.
  </Step>

  <Step title="An active business (tenant key)">
    You need an active business with a tenant key. **Platform integrators** receive this from the [`POST /v1/platform/businesses`](/api-reference/workforce/platform/create) response. **Direct API users** can find it in the [Dashboard](https://app.cadanapay.com) under **Settings > Business**.
  </Step>
</Steps>

***

## Create an Entity

Create a legal entity under the current business tenant.

<ApiExample method="POST" path="/v1/entities" body={{ legalName: "Acme UK Ltd", country: "GB", currency: "GBP", entityType: "corporation", address: { city: "London", countryCode: "GB", line1: "10 Downing Street", line2: "", postalCode: "SW1A 2AA", state: "England" }, phoneNumber: { countryCode: "44", number: "2071234567" }, registrationNumber: "12345678", taxId: "GB123456789", incorporationDate: "2020-01-15" }} reference="/api-reference/workforce/entities/create" />

**Response:**

```json theme={null}
{
  "id": "37ad8c1e-0187-4e10-8c54-395e3385b4d2"
}
```

### Required Fields

| Field       | Description                                              |
| :---------- | :------------------------------------------------------- |
| `legalName` | Legal name of the entity                                 |
| `country`   | ISO 3166-1 alpha-2 country code (e.g., `GH`, `NG`, `GB`) |
| `currency`  | ISO 4217 currency code (e.g., `GHS`, `NGN`, `GBP`)       |

### Optional Fields

| Field                | Description                                                                                                                                                |
| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entityType`         | Legal structure: `corporation`, `c-corporation`, `s-corporation`, `partnership`, `sole proprietorship`, `limited liability company`, `non profit`, `other` |
| `address`            | Entity's registered address                                                                                                                                |
| `phoneNumber`        | Entity's phone number                                                                                                                                      |
| `registrationNumber` | Business registration number in the jurisdiction                                                                                                           |
| `taxId`              | Tax identification number                                                                                                                                  |
| `incorporationDate`  | Date of incorporation (`YYYY-MM-DD`)                                                                                                                       |

<Note>
  Entities start as `ACTIVE`. KYB verification per entity is planned for a future phase.
</Note>

***

## List Entities

Retrieve all entities under the current tenant.

<ApiExample method="GET" path="/v1/entities" reference="/api-reference/workforce/entities/list" />

**Response:**

```json theme={null}
[
  {
    "id": "37ad8c1e-0187-4e10-8c54-395e3385b4d2",
    "legalName": "Acme UK Ltd",
    "country": "GB",
    "currency": "GBP",
    "entityType": "corporation",
    "status": "ACTIVE",
    "createdTimestamp": 1609459200,
    "lastUpdatedTimestamp": 1609459200
  }
]
```

***

## Get a Single Entity

<ApiExample method="GET" path="/v1/entities/37ad8c1e-0187-4e10-8c54-395e3385b4d2" reference="/api-reference/workforce/entities/get" />

**Response:**

```json theme={null}
{
  "id": "37ad8c1e-0187-4e10-8c54-395e3385b4d2",
  "tenantKey": "cad617152",
  "legalName": "Acme UK Ltd",
  "country": "GB",
  "currency": "GBP",
  "address": {
    "city": "London",
    "countryCode": "GB",
    "line1": "10 Downing Street",
    "line2": "",
    "postalCode": "SW1A 2AA",
    "state": "England"
  },
  "phoneNumber": {
    "countryCode": "44",
    "number": "2071234567"
  },
  "registrationNumber": "12345678",
  "taxId": "GB123456789",
  "incorporationDate": "2020-01-15",
  "entityType": "corporation",
  "status": "ACTIVE",
  "createdTimestamp": 1609459200,
  "lastUpdatedTimestamp": 1609459200
}
```

***

## Update an Entity

Update an existing entity. This is a partial update — only include the fields you want to change.

<ApiExample method="PATCH" path="/v1/entities/37ad8c1e-0187-4e10-8c54-395e3385b4d2" body={{ legalName: "Acme UK Ltd (Updated)", address: { city: "Manchester", countryCode: "GB", line1: "5 Market Street", line2: "", postalCode: "M1 1AA", state: "England" } }} reference="/api-reference/workforce/entities/update" />

Returns `204` on success.

***

## Link Persons to Entities

Assign a person to a specific entity by setting `entityId` in their job information via [`PUT /v1/persons/{personId}/jobInfo`](/api-reference/workforce/persons/update-job-information).

<ApiExample method="PUT" path="/v1/persons/8ef9a712-cdae-4110-b1ea-9ba95abbee6e/jobInfo" body={{ title: "Software Engineer", department: "Engineering", startDate: "2024-01-15", entityId: "37ad8c1e-0187-4e10-8c54-395e3385b4d2" }} reference="/api-reference/workforce/persons/update-job-information" />

Returns `204` on success.

<Note>
  If `entityId` is not set, the person is employed under the parent business. This is the default behavior and is fully backwards compatible — existing persons without an `entityId` continue to work as before.
</Note>

***

## Statutory Compliance Impact

When a person is linked to an entity via `entityId`, statutory filings use the **entity's** employer details instead of the parent business's. The entity fields used for compliance are:

| Field                | Purpose                                             |
| :------------------- | :-------------------------------------------------- |
| `taxId`              | Employer tax identification on statutory returns    |
| `registrationNumber` | Employer registration with government authorities   |
| `country`            | Determines applicable jurisdiction and filing types |
| `address`            | Employer address on statutory returns               |

<Warning>
  Make sure entities have complete registration details (`taxId`, `registrationNumber`, `address`) before running statutory filings for persons linked to them. Missing data will cause filings to be `blocked` until resolved.
</Warning>

<Tip>
  For full details on statutory filings and requirements, see the [Statutory Compliance](/statutory/overview) guide.
</Tip>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Onboard Workers" icon="user-plus" href="/workforce/onboarding-workers">
    Create Person records and assign them to entities during onboarding
  </Card>

  <Card title="Statutory Compliance" icon="file-lines" href="/statutory/overview">
    Automate filings and remittances for entity jurisdictions
  </Card>

  <Card title="Multi-Tenant Setup" icon="building" href="/platform/multi-tenant-setup">
    Platform integration and business creation
  </Card>

  <Card title="Departments & Custom Fields" icon="sitemap" href="/workforce/departments-custom-fields">
    Organize workers by department and track custom metadata
  </Card>
</CardGroup>