Multi-Tenant Setup

This guide walks through the full lifecycle of a business on your platform: Each business you create gets its own tenantKey. Every subsequent call for that business — KYB, funding, workers, payroll — carries that key in the X-MultiTenantKey header.

Prerequisites

Platform access enabled

Contact your account manager to enable Platform API access.

Platform API token

Generate a Platform token from your Platform Dashboard under Settings > Developers.

Platform API access requires special enablement. Standard org tokens cannot create businesses or use the X-MultiTenantKey header.

Create a Business

Create a business on your platform. The response includes the tenantKey you’ll need for all subsequent calls to this business. Response:

{
  "businessId": "7dd569f9-bd54-4fbb-a5c2-f0aaadc68adf",
  "tenantKey": "cad95193904"
}

Store the tenantKey in your database mapped to the business. You’ll need it for every API call that targets this business.

Creating a business sends a welcome email to adminEmail. Pass suppressWelcomeEmail: true if you onboard the business yourself and don’t want Cadana to email your customer.

Add Legal Entities (Optional)

For global payroll, you can create legal entities representing subsidiaries or branches in different jurisdictions: See Entity Management for full details.

Use the Tenant Key

For all business-specific operations, include the X-MultiTenantKey header with the tenant key.

If you omit the header, the request does not fail — it silently runs against your platform’s own main business. Always set X-MultiTenantKey when you intend to operate on a sub-business.

Unsure which business a request will hit? Call GET /v1/me with the same headers — the response includes the business the request resolved to.

curl -X GET 'https://api.cadanapay.com/v1/users' \
  -H 'Authorization: Bearer PLATFORM_TOKEN' \
  -H 'X-MultiTenantKey: cad95193904'

All business-scoped endpoints (persons, users, payrolls, contracts, invoices, KYB) accept the X-MultiTenantKey header. Platform-level endpoints (/v1/platform/*) like creating and listing businesses do not take it. See the API Reference for all available endpoints.

List Your Businesses

Retrieve all businesses on your platform. No tenant key needed. Response:

{
  "data": [
    {
      "id": "7dd569f9-bd54-4fbb-a5c2-f0aaadc68adf",
      "name": "Acme Corporation",
      "shortName": "Acme",
      "status": "ACTIVE",
      "tenantKey": "cad95193904",
      "country": "US",
      "requiresKYB": true,
      "admin": { "name": "Jane Founder", "email": "jane@example.com" },
      "address": { "line1": "123 Main Street", "line2": "", "city": "San Francisco", "postalCode": "94105", "state": "CA", "countryCode": "US" },
      "createdTimestamp": 1765359752,
      "idempotencyKey": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    },
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Beta Inc",
      "shortName": "Beta",
      "status": "pending_verification",
      "tenantKey": "cad12345678",
      "country": "NG",
      "requiresKYB": true,
      "admin": { "name": "Bola Adeyemi", "email": "bola@example.com" },
      "address": { "line1": "12 Marina Road", "line2": "", "city": "Lagos", "postalCode": "101241", "state": "LA", "countryCode": "NG" },
      "createdTimestamp": 1765359801,
      "idempotencyKey": "b6ae5da9-6342-4a58-bd50-8564d68d3f7e"
    }
  ],
  "node": {
    "previous": null,
    "next": "eyJwbGF0Zm9ybVByZWZpeCI6..."
  }
}

A business starts in pending_verification and moves to ACTIVE once KYB is approved. Use the node.next cursor with the next query parameter to page through results.

Complete KYB

A new business starts in pending_verification and can’t process payments until Know Your Business (KYB) verification is approved. There are two ways to submit it:

Hosted form — generate a KYB link and send it to the business owner. They complete a branded multi-step form; links expire after 6 hours and progress is saved between visits.
API submission — collect the data in your own UI and submit it directly. You can submit everything at once or incrementally.

See KYB Requirements for required fields, document uploads, and the nuances of updating a submission (in short: PATCH updates existing fields and principals, re-POST to add principals).

Track Verification

Poll GET /v1/businesses/{businessId}/kyb — requirements.currentlyDue lists anything still outstanding — or subscribe to the business.kyb.reviewed and business.kyb.completed webhooks. When KYB reaches complete, the business status flips to ACTIVE.

Fund the Business

Once the business is ACTIVE, retrieve the bank details to send funds to, and check balances: See Fund Your Account for all funding methods (bank transfer, ACH direct debit, crypto) and the sandbox deposit endpoint for instant test funds.

Webhooks

Platform integrations receive webhooks for all businesses. The payload includes a tenantKey field to identify which business the event relates to.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "eventType": "business.kyb.completed",
  "version": "1.0",
  "timestamp": 1765359752,
  "data": {
    "businessId": "7dd569f9-bd54-4fbb-a5c2-f0aaadc68adf",
    "businessName": "Acme Corporation",
    "status": "complete",
    "tenantKey": "cad95193904"
  }
}

See Events for all event types and Webhooks to configure your endpoint.

Sandbox Testing

In sandbox mode, businesses are created instantly and KYB can be auto-approved using test values (e.g., tax ID 000-CAD-AUTO-APPROVE). All API calls work the same as production. Use https://dev-api.cadanapay.com as the base URL. See Sandbox & Testing for all test values and simulated scenarios.

Troubleshooting

Error	Cause	Solution
Request affects the wrong business (no error)	Missing `X-MultiTenantKey` header — the request ran against your platform’s main business	Add the header with the correct tenant key
`401 Unauthorized`	Invalid or expired token	Verify your Platform token is valid
`403 Forbidden`	Tenant key doesn’t belong to your platform	Verify the tenant key matches a business you created
`400 unauthorized access`	The `businessId` in the path doesn’t belong to the business in `X-MultiTenantKey`	Use the `businessId` and `tenantKey` of the same business
`400 Platform access required`	Account not enabled for platform access	Contact your account manager

Next Steps

KYB Requirements

Business verification requirements

Fund Your Account

Fund business accounts before running payroll

Onboard Workers

Create Person and User records for each business

Pay Workers via Payroll

Run payroll for a business

Transaction Reconciliation

Reconcile transactions across businesses

Workforce API Reference

Full API documentation

Get Started

Workforce Management

Payroll & Compliance

White-Label UI

Platform Integration

Payments

Wallets

Prerequisites

Create a Business

Add Legal Entities (Optional)

Use the Tenant Key

List Your Businesses

Complete KYB

Track Verification

Fund the Business

Webhooks

Sandbox Testing

Troubleshooting

Next Steps

KYB Requirements

Fund Your Account

Onboard Workers

Pay Workers via Payroll

Transaction Reconciliation

Workforce API Reference

​Prerequisites

​Create a Business

​Add Legal Entities (Optional)

​Use the Tenant Key

​List Your Businesses

​Complete KYB

​Track Verification

​Fund the Business

​Webhooks

​Sandbox Testing

​Troubleshooting

​Next Steps

KYB Requirements

Fund Your Account

Onboard Workers

Pay Workers via Payroll

Transaction Reconciliation

Workforce API Reference

Prerequisites

Create a Business

Add Legal Entities (Optional)

Use the Tenant Key

List Your Businesses

Complete KYB

Track Verification

Fund the Business

Webhooks

Sandbox Testing

Troubleshooting

Next Steps