Onboard Workers

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.

---

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

Response:

{
  "id": "8ef9a712-cdae-4110-b1ea-9ba95abbee6e"
}

Save the id — you’ll need it to configure payment methods, create a user, and run payroll.

Required Fields

Field	Description
type	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)

Set compInfo.employmentModel: "eor" to employ the worker through Cadana’s Employer of Record — this changes what payroll collects. See Employment Models.

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.

Contractor-Specific Fields

Field	Description
contractorType	INDIVIDUAL or BUSINESS — required when type 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)

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.

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

See the Workforce API Reference for full request and response schemas.

Person profile writes (e.g., tax profile, payment info) are applied asynchronously — a read immediately after a write may return the previous state, and approving a payroll immediately after saving it can briefly fail. Retry after a short delay.

---

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

A successful request returns 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

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.

Compensation Type Compatibility

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.

---

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