Skip to main content

​
Prerequisites

1

Platform access enabled

Contact your account manager to enable Platform API access.
2

Platform API token

Generate a Platform token from your 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.
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. Without it, the request returns 400 Bad Request. 
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) require the X-MultiTenantKey header. Platform-level endpoints (/v1/platform/*) like creating and listing businesses do not. 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",
      "status": "active",
      "tenantKey": "cad95193904",
      "country": "US"
    },
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Beta Inc",
      "status": "pending",
      "tenantKey": "cad12345678",
      "country": "NG"
    }
  ]
}

​
Complete KYB

Businesses must complete Know Your Business (KYB) verification before they can process payments. You can either generate a hosted form link for the business owner to complete, or submit the data directly via API. See KYB Requirements for full details on both approaches, required fields, and document uploads.

​
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": "completed",
    "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
400 X-MultiTenantKey header cannot be blankMissing X-MultiTenantKey headerAdd 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 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