Create employee and contractor records, configure compensation, and set up payment methods
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.
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)
For workers with variable pay, you may set compInfo.salary to 0 during onboarding. You’ll provide the actual amount when saving payroll entries during a payroll run.
Payment methods are configured separately after creating the Person. By default, workers are paid via Cadana Wallet — the recommended option for most integrations.
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 (bank transfer, mobile money, etc.) require enablement for your business. Contact your account manager to configure direct-to-bank payouts.
If enabled, you can pay workers directly to their bank account or mobile money without creating a User account.
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.
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.
When compInfo 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.
When providing compInfo, 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
Pass compInfo when you want to set a specific compensation structure for the new type — for example, switching a contractor to a salaried employee with tax calculation, or changing the pay amount alongside the type switch.
