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
curl -X POST 'https://api.cadanapay.com/v1/persons' \
-H 'Authorization: Bearer YOUR_API_KEY'
curl -X POST 'https://api.cadanapay.com/v1/persons' \
-H 'Authorization: Bearer YOUR_API_KEY'
curl -X POST 'https://api.cadanapay.com/v1/persons' \
-H 'Authorization: Bearer YOUR_API_KEY'
{
"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 |
|---|
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) |
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 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.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) |
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.
Bank Transfer
Mobile Money
ACH (US)
SWIFT
curl -X PUT 'https://api.cadanapay.com/v1/persons/8ef9a712-cdae-4110-b1ea-9ba95abbee6e/paymentInfo' \
-H 'Authorization: Bearer YOUR_API_KEY'
curl -X PUT 'https://api.cadanapay.com/v1/persons/8ef9a712-cdae-4110-b1ea-9ba95abbee6e/paymentInfo' \
-H 'Authorization: Bearer YOUR_API_KEY'
curl -X PUT 'https://api.cadanapay.com/v1/persons/8ef9a712-cdae-4110-b1ea-9ba95abbee6e/paymentInfo' \
-H 'Authorization: Bearer YOUR_API_KEY'
curl -X PUT 'https://api.cadanapay.com/v1/persons/8ef9a712-cdae-4110-b1ea-9ba95abbee6e/paymentInfo' \
-H 'Authorization: Bearer YOUR_API_KEY'
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
curl -X GET 'https://api.cadanapay.com/v1/persons/8ef9a712-cdae-4110-b1ea-9ba95abbee6e/paymentInfo' \
-H 'Authorization: Bearer YOUR_API_KEY'
Step 3: Issue a Contract (Optional)
You can issue a contract to the worker immediately after onboarding. See Manage Contracts for the full guide.
curl -X POST 'https://api.cadanapay.com/v1/contracts' \
-H 'Authorization: Bearer YOUR_API_KEY'
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 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 |
Next Steps
