Skip to main content
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

1

Platform access enabled

Contact your account manager to enable Platform API access.
2

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

ErrorCauseSolution
Request affects the wrong business (no error)Missing X-MultiTenantKey header — the request ran against your platform’s main businessAdd the header with the correct tenant key
401 UnauthorizedInvalid or expired tokenVerify your Platform token is valid
403 ForbiddenTenant key doesn’t belong to your platformVerify the tenant key matches a business you created
400 unauthorized accessThe businessId in the path doesn’t belong to the business in X-MultiTenantKeyUse the businessId and tenantKey of the same business
400 Platform access requiredAccount not enabled for platform accessContact 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