Entity Management

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

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.

Prerequisites

API key from Dashboard

Get your API key from the Cadana Dashboard. See Authentication for details.

An active business (tenant key)

You need an active business with a tenant key. Platform integrators receive this from the POST /v1/platform/businesses response. Direct API users can find it in the Dashboard under Settings > Business.

Create an Entity

Create a legal entity under the current business tenant. Response:

{
  "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`)

Entities start as ACTIVE. KYB verification per entity is planned for a future phase.

List Entities

Retrieve all entities under the current tenant. Response:

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

Response:

{
  "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. 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. Returns 204 on success.

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.

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

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.

For full details on statutory filings and requirements, see the Statutory Compliance guide.

Next Steps

Onboard Workers

Create Person records and assign them to entities during onboarding

Statutory Compliance

Automate filings and remittances for entity jurisdictions

Multi-Tenant Setup

Platform integration and business creation

Departments & Custom Fields

Organize workers by department and track custom metadata

Get Started

Workforce Management

Payroll & Compliance

White-Label UI

Platform Integration

Payments

Wallets

Prerequisites

Create an Entity

Required Fields

Optional Fields

List Entities

Get a Single Entity

Update an Entity

Link Persons to Entities

Statutory Compliance Impact

Next Steps

Onboard Workers

Statutory Compliance

Multi-Tenant Setup

Departments & Custom Fields

​Prerequisites

​Create an Entity

​Required Fields

​Optional Fields

​List Entities

​Get a Single Entity

​Update an Entity

​Link Persons to Entities

​Statutory Compliance Impact

​Next Steps

Onboard Workers

Statutory Compliance

Multi-Tenant Setup

Departments & Custom Fields

Prerequisites

Create an Entity

Required Fields

Optional Fields

List Entities

Get a Single Entity

Update an Entity

Link Persons to Entities

Statutory Compliance Impact

Next Steps