Skip to main content

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.

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

1

API key from Dashboard

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

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

FieldDescription
legalNameLegal name of the entity
countryISO 3166-1 alpha-2 country code (e.g., GH, NG, GB)
currencyISO 4217 currency code (e.g., GHS, NGN, GBP)

​
Optional Fields

FieldDescription
entityTypeLegal structure: corporation, c-corporation, s-corporation, partnership, sole proprietorship, limited liability company, non profit, other
addressEntity’s registered address
phoneNumberEntity’s phone number
registrationNumberBusiness registration number in the jurisdiction
taxIdTax identification number
incorporationDateDate 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.
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:
FieldPurpose
taxIdEmployer tax identification on statutory returns
registrationNumberEmployer registration with government authorities
countryDetermines applicable jurisdiction and filing types
addressEmployer 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