Onboarding a worker means creating a Person — the HR record that stores their personal details, job information, and compensation. Once a Person exists, you can run payroll, issue contracts, and configure how they get paid.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.
Prerequisites
- A Cadana account with API access
- Your API key from the Dashboard
Step 1: Create a Person
A Person represents an employee or contractor in your organization.- Contractor (Individual)
- Contractor (Business)
- Employee
Required Fields
| Field | Description |
|---|---|
personType | EMPLOYEE or CONTRACTOR |
firstName, lastName | Contact person’s legal name |
email | Must be unique per tenant for active persons |
address.countryCode | ISO country code — determines available payment methods and tax rules |
compInfo.salary | Amount in minor units (cents). 500000 USD = $5,000.00 |
compInfo.currency | Compensation currency |
compInfo.frequency | hourly, daily, or monthly |
compInfo.type | net (contractor) or salaried (employee with tax calculation) |
Contractor-Specific Fields
| Field | Description |
|---|---|
contractorType | INDIVIDUAL or BUSINESS — required when personType is CONTRACTOR |
businessName | Company name — required when contractorType is BUSINESS |
Optional Fields
| Field | Description |
|---|---|
jobInfo.title | Job title |
jobInfo.department | Department name (must match a department configured on the business) |
jobInfo.startDate | Employment start date (YYYY-MM-DD) |
jobInfo.employeeNumber | Your internal employee/contractor ID |
jobInfo.entityId | UUID of the legal entity this person belongs to. See Entity Management. |
jobInfo.customFields | Custom fields configured on the business |
phoneNumber | Must be globally unique across all tenants |
metadata | Key-value pairs for your own tracking (max 50 entries) |
Step 2: Configure Payment Method
Payment methods are configured separately after creating the Person. By default, workers are paid via Cadana Wallet — the recommended option for most integrations.Cadana Wallet (Default)
Workers are paid into a Cadana Global Wallet, where they can manage their funds, withdraw to a local bank, and access financial features like Virtual Cards. To set up a wallet, the worker needs a User account. See Set Up Worker Wallets for the full flow (create User, complete KYC, wallet is provisioned automatically).Wallet is set automatically. When you create a User for a Person, the platform automatically sets wallet as the preferred payment method. No separate
PUT /paymentInfo call is needed.Direct Payment Methods (Alternative)
If enabled, you can pay workers directly to their bank account or mobile money without creating a User account.- Bank Transfer
- Mobile Money
- ACH (US)
- SWIFT
Payment Methods
| Method | preferredMethod | Use Case | Requires User |
|---|---|---|---|
| Cadana Wallet | wallet | Default — workers manage funds via Cadana | Yes |
| Bank transfer | bank | Local bank account | No |
| Mobile money | momo | Mobile money (GH, KE, UG, etc.) | No |
| ACH | ach | US bank accounts | No |
| SWIFT | swift | International wire transfers | No |
| Proxy | proxy | Proxy-based payments (e.g., Pix) | No |
Available payment methods vary by country and currency. The API will return a validation error if the method isn’t supported for the worker’s country. See Payment Methods for coverage.
Check Current Payment Info
Step 3: Issue a Contract (Optional)
You can issue a contract to the worker immediately after onboarding. See Manage Contracts for the full guide.Managing Person Records
After onboarding, you can update worker details as needed:| Operation | Endpoint | What it updates |
|---|---|---|
| Get person | GET /v1/persons/{personId} | Retrieve full person record |
| List persons | GET /v1/persons | List all persons (filterable by email) |
| Update basic info | PUT /v1/persons/{personId}/basicInfo | Name, email, phone, metadata |
| Update personal info | PUT /v1/persons/{personId}/personalInfo | Date of birth, national ID, tax ID, social security ID, gender, nationality, address |
| Update job info | PUT /v1/persons/{personId}/jobInfo | Title, department, compensation, start date |
| Update payment info | PUT /v1/persons/{personId}/paymentInfo | Preferred payment method and details |
| Update tax profile | PUT /v1/persons/{personId}/taxProfile | Marital status, number of dependents, and other country-specific tax fields |
Change Employment Type
To switch a person between Employee and Contractor without offboarding and re-onboarding, use the Update Person Type endpoint. The person must be in Active status.- Simple (auto-convert comp)
- With new compensation
204 No Content.
Request Fields
| Field | Type | Required | Description |
|---|---|---|---|
newType | string | Yes | Target employment type: EMPLOYEE or CONTRACTOR |
compInfo | object | No | Compensation for the new type. If omitted, incompatible compensation is auto-converted. |
compInfo.type | string | Yes (if compInfo provided) | Compensation type: net, salaried, gross, or fixed |
compInfo.salary | object | Yes (if compInfo provided) | Amount in minor units with currency (e.g., { "amount": 600000, "currency": "GHS" }) |
compInfo.frequency | string | No | Pay frequency: monthly, daily, weekly, biweekly, or hourly. Defaults to monthly. |
Auto-Conversion Rules
WhencompInfo is omitted, the API automatically converts incompatible compensation types:
| Current comp type | Target person type | Result |
|---|---|---|
salaried | Contractor | Auto-converted to net — same amount and frequency |
fixed | Employee | Auto-converted to net — same amount, frequency defaults to monthly if not set |
net or gross | Either | No conversion needed — left unchanged |
Auto-conversion only changes the compensation type. All other compensation fields (allowances, deductions, tax reliefs, employer contributions, pension settings) are preserved. The tax engine interprets these fields based on the person’s type at payroll calculation time.
Compensation Type Compatibility
When providingcompInfo, the compensation type must be compatible with the target person type:
| Comp type | Employee | Contractor |
|---|---|---|
salaried | Yes | No |
gross | Yes | Yes |
net | Yes | Yes |
fixed | No | Yes |
Next Steps
Set Up Worker Wallets
Create a User account and provision a Cadana wallet
Pay Workers via Payroll
Pay your onboarded workers
Manage Contracts
Issue employment or contractor agreements
Admin Management
Add and manage business administrators