openapi: 3.0.0
info:
description: APIs for interacting with Cadana Embedded Consumer Wallets
version: 1.0.0
title: Embedded Consumer Wallets Balances Persons API
termsOfService: https://cadanapay.com/terms-and-conditions
contact:
email: api@cadanapay.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.cadanapay.com
description: Prod Server
- url: https://dev-api.cadanapay.com
description: Dev Server
security:
- Authorization: []
tags:
- name: Persons
description: APIs for interacting with the HR module
paths:
/v1/persons/{personId}:
get:
summary: Get
description: Fetch a person's details
operationId: getPerson
tags:
- Persons
parameters:
- $ref: '#/components/parameters/personId'
- $ref: '#/components/parameters/XMultiTenantKey'
responses:
'200':
$ref: '#/components/responses/GetPersonResponse'
'404':
$ref: '#/components/responses/NotFoundError'
5XX:
$ref: '#/components/responses/InternalError'
security:
- Authorization: []
/v1/persons:
get:
summary: List
description: Get all persons
operationId: getPersons
tags:
- Persons
parameters:
- in: query
name: page
schema:
type: integer
minimum: 1
description: Page number to retrieve
- in: query
name: limit
schema:
type: integer
minimum: 1
maximum: 100
description: Maximum number of items to return per page
- in: query
name: email
schema:
type: string
description: Filter by email
- $ref: '#/components/parameters/XMultiTenantKey'
responses:
'200':
$ref: '#/components/responses/GetPersonsResponse'
'400':
$ref: '#/components/responses/BadRequestError'
5XX:
$ref: '#/components/responses/InternalError'
security:
- Authorization: []
post:
summary: Create
description: Create a new employee/contractor
operationId: createPerson
tags:
- Persons
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePersonRequest'
responses:
'200':
$ref: '#/components/responses/CreatePersonResponse'
'400':
$ref: '#/components/responses/BadRequestError'
5XX:
$ref: '#/components/responses/InternalError'
security:
- Authorization: []
parameters:
- $ref: '#/components/parameters/XMultiTenantKey'
/v1/persons/{personId}/basicInfo:
put:
summary: Update basic information
description: Update a person's basic information
operationId: updatePersonBasicInfo
tags:
- Persons
parameters:
- $ref: '#/components/parameters/personId'
- $ref: '#/components/parameters/XMultiTenantKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePersonBasicInfoRequest'
responses:
'204':
description: Successful operation
'400':
$ref: '#/components/responses/BadRequestError'
'404':
$ref: '#/components/responses/NotFoundError'
5XX:
$ref: '#/components/responses/InternalError'
security:
- Authorization: []
/v1/persons/{personId}/personalInfo:
put:
summary: Update personal information
description: Update a person's personal information including identity documents, date of birth, gender, nationality, and address
operationId: updatePersonPersonalInfo
tags:
- Persons
parameters:
- $ref: '#/components/parameters/personId'
- $ref: '#/components/parameters/XMultiTenantKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePersonPersonalInfoRequest'
responses:
'204':
description: Successful operation
'400':
$ref: '#/components/responses/BadRequestError'
'404':
$ref: '#/components/responses/NotFoundError'
5XX:
$ref: '#/components/responses/InternalError'
security:
- Authorization: []
/v1/persons/{personId}/taxProfile:
get:
summary: Get tax profile
description: Retrieve a person's tax profile. Returns the shape accepted by PUT /v1/persons/{personId}/taxProfile plus a server-derived `countryCode` field — remove `countryCode` before resubmitting via PUT.
operationId: getPersonTaxProfile
tags:
- Persons
parameters:
- $ref: '#/components/parameters/personId'
- $ref: '#/components/parameters/XMultiTenantKey'
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/GetPersonTaxProfileResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'404':
$ref: '#/components/responses/NotFoundError'
5XX:
$ref: '#/components/responses/InternalError'
security:
- Authorization: []
put:
summary: Update tax profile
description: Update a person's tax profile with country-specific tax fields such as marital status and number of dependents
operationId: updatePersonTaxProfile
tags:
- Persons
parameters:
- $ref: '#/components/parameters/personId'
- $ref: '#/components/parameters/XMultiTenantKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePersonTaxProfileRequest'
responses:
'204':
description: Successful operation
'400':
$ref: '#/components/responses/BadRequestError'
'404':
$ref: '#/components/responses/NotFoundError'
5XX:
$ref: '#/components/responses/InternalError'
security:
- Authorization: []
/v1/persons/{personId}/jobInfo:
put:
summary: Update job information
description: Update a person's job information
operationId: updatePersonJobInfo
tags:
- Persons
parameters:
- $ref: '#/components/parameters/personId'
- $ref: '#/components/parameters/XMultiTenantKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePersonJobInfoRequest'
responses:
'204':
description: Successful operation
'400':
$ref: '#/components/responses/BadRequestError'
'404':
$ref: '#/components/responses/NotFoundError'
5XX:
$ref: '#/components/responses/InternalError'
security:
- Authorization: []
/v1/persons/{personId}/paymentInfo:
get:
summary: Get payment information
description: Fetch a person's payment information
operationId: getPersonPaymentInfo
tags:
- Persons
parameters:
- $ref: '#/components/parameters/personId'
- $ref: '#/components/parameters/XMultiTenantKey'
responses:
'200':
$ref: '#/components/responses/GetPersonPaymentInfoResponse'
'404':
$ref: '#/components/responses/NotFoundError'
5XX:
$ref: '#/components/responses/InternalError'
security:
- Authorization: []
put:
summary: Update payment information
description: Update a person's payment information. Required fields vary by payout corridor — use [GET /v1/payment-requirements](/api-reference/payments/resources/payment-corridor-requirements) as the authoritative list of fields for each currency and method.
operationId: updatePersonPaymentInfo
tags:
- Persons
parameters:
- $ref: '#/components/parameters/personId'
- $ref: '#/components/parameters/XMultiTenantKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePersonPaymentInfoRequest'
examples:
achPayment:
$ref: '#/components/examples/achPaymentMethod'
swiftPayment:
$ref: '#/components/examples/swiftPaymentMethod'
philippinesBankPayment:
$ref: '#/components/examples/philippinesBankPaymentMethod'
indiaBankPayment:
$ref: '#/components/examples/indiaBankPaymentMethod'
mexicoBankPayment:
$ref: '#/components/examples/mexicoBankPaymentMethod'
colombiaBankPayment:
$ref: '#/components/examples/colombiaBankPaymentMethod'
elSalvadorBankPayment:
$ref: '#/components/examples/elSalvadorBankPaymentMethod'
walletRequest:
$ref: '#/components/examples/walletPaymentMethod'
responses:
'204':
description: Successful operation
'400':
$ref: '#/components/responses/BadRequestError'
'404':
$ref: '#/components/responses/NotFoundError'
5XX:
$ref: '#/components/responses/InternalError'
security:
- Authorization: []
/v1/persons/{personId}/offboard:
post:
summary: Schedule offboarding
description: Schedule a person for offboarding on a given exit date
operationId: scheduleOffboarding
tags:
- Persons
parameters:
- $ref: '#/components/parameters/personId'
- $ref: '#/components/parameters/XMultiTenantKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleOffboardingRequest'
responses:
'204':
description: Offboarding scheduled successfully
'400':
$ref: '#/components/responses/BadRequestError'
'404':
$ref: '#/components/responses/NotFoundError'
5XX:
$ref: '#/components/responses/InternalError'
security:
- Authorization: []
/v1/persons/{personId}/cancelOffboarding:
post:
summary: Cancel offboarding
description: Cancel a pending offboarding and return the person to active status
operationId: cancelOffboarding
tags:
- Persons
parameters:
- $ref: '#/components/parameters/personId'
- $ref: '#/components/parameters/XMultiTenantKey'
responses:
'204':
description: Offboarding cancelled successfully
'400':
$ref: '#/components/responses/BadRequestError'
'404':
$ref: '#/components/responses/NotFoundError'
5XX:
$ref: '#/components/responses/InternalError'
security:
- Authorization: []
/v1/persons/{personId}/reinstate:
post:
summary: Reinstate
description: Reinstate a former person back to active status
operationId: reinstatePerson
tags:
- Persons
parameters:
- $ref: '#/components/parameters/personId'
- $ref: '#/components/parameters/XMultiTenantKey'
responses:
'204':
description: Person reinstated successfully
'400':
$ref: '#/components/responses/BadRequestError'
'404':
$ref: '#/components/responses/NotFoundError'
5XX:
$ref: '#/components/responses/InternalError'
security:
- Authorization: []
/v1/persons/{personId}/type:
put:
summary: Update person type
description: Switch a person's employment type between employee and contractor. The person must be in Active status. Optionally provide new compensation info. If omitted, incompatible compensation is auto-converted (salaried becomes net, fixed becomes net).
operationId: updatePersonType
tags:
- Persons
parameters:
- $ref: '#/components/parameters/personId'
- $ref: '#/components/parameters/XMultiTenantKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePersonTypeRequest'
responses:
'204':
description: Person type updated successfully
'400':
$ref: '#/components/responses/BadRequestError'
'404':
$ref: '#/components/responses/NotFoundError'
5XX:
$ref: '#/components/responses/InternalError'
security:
- Authorization: []
components:
examples:
colombiaBankPaymentMethod:
summary: Colombia Bank Payment Method
value:
preferredMethod: bank
bank:
accountName: John Doe
accountNumber: '123456789'
bankName: Colombia Bank
accountType: Checking
bankCode: '001'
address:
line1: Avenida Caracas
line2: Oficina 202
city: Bogota
postalCode: '11001'
countryCode: CO
beneficiaryId:
type: NIT
value: '123456789'
walletPaymentMethod:
summary: Wallet Payment Method
value:
preferredMethod: wallet
wallet:
currency: USD
philippinesBankPaymentMethod:
summary: Philippines Bank Payment Method
value:
preferredMethod: bank
bank:
accountName: John Doe
accountNumber: '123456789'
bankName: Philippines National Bank
bankCode: '001'
address:
line1: Mabini St
line2: Bldg 5
city: Manila
postalCode: '1000'
countryCode: PH
swiftPaymentMethod:
summary: Swift Payment Method
value:
preferredMethod: swift
swift:
accountName: Jane Smith
accountNumber: '987654321'
bankName: London Bank
swiftCode: EXMPGB2L
currency: USD
address:
line1: Queen's Way
line2: Suite 100
city: London
postalCode: WC2N 5DU
state: London
countryCode: GB
indiaBankPaymentMethod:
summary: India Bank Payment Method
value:
preferredMethod: bank
bank:
accountName: Vraj Shah
ownerType: Individual
accountNumber: '12345678901234'
bankCode: HDFC
bankName: HDFC Bank
sortCode: HDFC0000123
address:
line1: 12 Alkapuri Main Road
city: Vadodara
postalCode: '390007'
state: GJ
countryCode: IN
email: worker@example.com
phoneNumber:
countryCode: '91'
number: '9876543210'
elSalvadorBankPaymentMethod:
summary: El Salvador Bank Payment Method
value:
preferredMethod: bank
bank:
accountName: John Doe
accountNumber: '123456789'
bankName: El Salvador Bank
bankCode: '001'
address:
line1: Calle Real
line2: Casa 5
city: San Salvador
postalCode: '1200'
countryCode: SV
email: john.doe@example.com
phoneNumber:
countryCode: '503'
number: '70000000'
mexicoBankPaymentMethod:
summary: Mexico Bank Payment Method
value:
preferredMethod: bank
bank:
accountName: John Doe
accountNumber: '123456789012345678'
bankName: Mexico City Bank
bankCode: '001'
address:
line1: Avenida de la Reforma
line2: Oficina 10
city: Mexico City
postalCode: '06600'
countryCode: MX
achPaymentMethod:
summary: ACH Payment Method
value:
preferredMethod: ach
ach:
accountName: John Doe
accountNumber: '123456789'
bankName: Gotham City Bank
routingNumber: '000000000'
accountType: Checking
address:
line1: 1234 Elm St
line2: Apt 1A
city: Gotham
postalCode: '10001'
state: NY
countryCode: US
schemas:
UpdatePersonTaxProfileRequest:
description: Update a person's tax profile. The submitted object replaces the person's entire tax profile — it is not a merge, so omitted fields are cleared. Updates are applied asynchronously; a subsequent GET may briefly return the previous profile. The accepted fields vary by country — use the [required fields endpoint](/api-reference/statutory/jurisdictions/get-required-fields-for-tax-calculation-and-statutory-filing) or [tax fields endpoint](/api-reference/tax/tax-calculator/list-required-additional-tax-fields-by-country) to discover which fields are needed for a given jurisdiction.
type: object
additionalProperties: true
example:
maritalStatus: single
numberOfDependents: 2
meta:
type: object
description: Meta about the pagination
properties:
limit:
type: number
example: 1
currentPage:
type: number
example: 1
skipped:
type: number
example: 1
pages:
type: number
example: 1
itemCount:
type: number
example: 1
UpdatePersonPersonalInfoRequest:
description: Update person personal info request payload
type: object
properties:
dateOfBirth:
type: string
format: date
description: Person's date of birth
example: '1990-05-15'
nationalId:
$ref: '#/components/schemas/NationalID'
taxId:
$ref: '#/components/schemas/NationalID'
socialSecurityId:
$ref: '#/components/schemas/NationalID'
gender:
type: string
enum:
- male
- female
- other
description: Person's gender
example: female
nationality:
type: string
description: ISO 3166-1 alpha-2 country code
example: DE
address:
$ref: '#/components/schemas/address'
swiftDetails:
type: object
required:
- currency
- iban
- accountName
- accountNumber
- bankName
- swiftCode
- address
properties:
currency:
type: string
description: The currency of the bank account
example: EUR
iban:
type: string
description: The International Bank Account Number
example: DE00000000000000000000
accountName:
type: string
description: The name on the bank account
example: John Doe
accountNumber:
type: string
description: The bank account number
example: '1234567890'
bankName:
type: string
description: The name of the bank
example: Example Bank
swiftCode:
type: string
description: The SWIFT/BIC code of the bank
example: EXMPDEFF
address:
$ref: '#/components/schemas/address'
phoneNumber:
type: object
description: Person's phone number
properties:
countryCode:
type: string
example: '1'
number:
type: string
example: '2345678901'
NationalID:
type: object
description: National identification document
properties:
fullId:
type: string
description: Full ID number
example: T22084535
suffix:
type: string
description: ID suffix
example: '01'
type:
type: string
description: Type of ID document. Required when fullId is provided.
example: tin
OffboardingDetails:
type: object
properties:
exitDate:
type: string
format: date
example: '2025-06-30'
reason:
type: string
example: Voluntary resignation
compensation:
$ref: '#/components/schemas/compInfo'
includeInRegularPayroll:
type: boolean
example: true
uuid:
type: string
format: uuid
example: 8ef9a712-cdae-4110-b1ea-9ba95abbee6e
NotFoundError:
description: Not Found
allOf:
- $ref: '#/components/schemas/Error'
example:
code: resource_not_found
message: Requested resource could not be found.
walletDetails:
type: object
properties:
type:
type: string
description: The type of wallet account
enum:
- user
- business
example: user
identifier:
type: string
description: The unique identifier for the wallet account
example: 69a2a928-ed49-4e53-92ec-a72b4ee7eacc
currency:
type: string
description: The currency of the wallet
example: USD
UpdatePersonTypeRequest:
type: object
required:
- newType
properties:
newType:
type: string
description: The new employment type for the person
enum:
- EMPLOYEE
- CONTRACTOR
example: CONTRACTOR
compInfo:
description: Optional compensation for the new type. If omitted, incompatible compensation is auto-converted (salaried becomes net, fixed becomes net).
allOf:
- $ref: '#/components/schemas/compInfo'
UpdatePersonBasicInfoRequest:
description: Update person basic info request payload
type: object
allOf:
- $ref: '#/components/schemas/basicInfo'
InternalError:
description: Internal server error
allOf:
- $ref: '#/components/schemas/Error'
example:
code: internal_error
message: An unexpected error occurred. Please try again later.
ScheduleOffboardingRequest:
type: object
required:
- exitDate
- reason
properties:
exitDate:
type: string
format: date
description: The date the person will exit the organization
example: '2025-06-30'
reason:
type: string
description: The reason for offboarding
example: Voluntary resignation
compensation:
$ref: '#/components/schemas/compInfo'
includeInRegularPayroll:
type: boolean
description: Whether to include the person in the regular payroll run for their exit period
example: true
BadRequestError:
description: Bad input provided by client
allOf:
- $ref: '#/components/schemas/Error'
- type: object
properties:
params:
description: A map for meta data around the error that occurred
type: object
example:
code: invalid_request_body
message: The request body provided is not valid
params:
field: Value is invalid.
amount:
type: object
required:
- amount
- currency
properties:
amount:
type: integer
description: value in lowest denomination
example: 10000
currency:
type: string
description: currency
example: USD
GetPersonTaxProfileResponse:
type: object
properties:
taxProfile:
type: object
additionalProperties: true
description: The person's tax profile. Empty if none set. Includes a read-only, server-derived `countryCode` field; remove it from the payload before resubmitting via PUT, which rejects unknown fields.
example:
countryCode: DE
maritalStatus: single
numberOfDependents: 2
CreatePersonRequest:
description: Create person request payload
type: object
allOf:
- $ref: '#/components/schemas/basicInfo'
- $ref: '#/components/schemas/tags'
required:
- type
- email
- firstName
- lastName
- address
- compInfo
properties:
businessName:
type: string
description: Business name, required if contractor type is business
example: Wayne Enterprise
type:
type: string
example: CONTRACTOR
description: Type of the person, we allow contractors and employees
enum:
- EMPLOYEE
- CONTRACTOR
contractorType:
type: string
example: INDIVIDUAL
description: Type of the contractor, only required if person is a contractor type, we allow individual and business type contractors
enum:
- INDIVIDUAL
- BUSINESS
address:
$ref: '#/components/schemas/address'
compInfo:
$ref: '#/components/schemas/compInfo'
jobInfo:
$ref: '#/components/schemas/jobInfo'
metadata:
type: object
additionalProperties: true
description: Optional metadata you can store as key-value pairs
example:
customField1: value1
customField2: value2
beneficiaryId:
type: object
description: ID details for the beneficiary
properties:
type:
type: string
enum:
- NIT
- CC
- CE
- TI
- PASS
description: Type of beneficiary ID
example: NIT
value:
type: string
description: ID number of the beneficiary
example: '123456789'
tags:
type: object
description: Any custom data you want to store
jobInfo:
type: object
description: Person's job information, start date, job title, and employee number
properties:
startDate:
type: string
format: date
example: '2023-01-01'
employeeNumber:
type: string
example: '1'
title:
type: string
example: Software Engineer
department:
type: string
example: Product
customFields:
type: array
description: A list of custom fields associated with the job information
items:
$ref: '#/components/schemas/customField'
entityId:
type: string
format: uuid
description: The legal entity this person is employed under. If omitted, the person is employed under the parent business.
example: 37ad8c1e-0187-4e10-8c54-395e3385b4d2
wireDetails:
type: object
description: Wire transfer payment details
properties:
bankName:
type: string
description: The name of the bank
example: Example Bank
accountName:
type: string
description: The name on the account
example: John Doe
routingNumber:
type: string
description: The routing number
example: '000000000'
accountNumber:
type: string
description: The account number
example: '123456789'
address:
$ref: '#/components/schemas/address'
paymentMethods:
type: object
required:
- preferredMethod
properties:
preferredMethod:
type: string
enum:
- momo
- bank
- swift
- ach
- wallet
- wire
description: The preferred payment method type
example: bank
momo:
$ref: '#/components/schemas/momoDetails'
bank:
$ref: '#/components/schemas/bankDetails'
swift:
$ref: '#/components/schemas/swiftDetails'
ach:
$ref: '#/components/schemas/achDetails'
wallet:
$ref: '#/components/schemas/walletDetails'
wire:
$ref: '#/components/schemas/wireDetails'
bankDetails:
type: object
properties:
accountName:
type: string
description: The name on the bank account
example: John Doe
accountNumber:
type: string
description: The bank account number
example: '1234567890'
accountType:
type: string
description: The type of bank account (e.g., Checking, Savings)
example: Checking
ownerType:
type: string
description: The type of account owner
enum:
- Individual
- Business
example: Individual
bankCode:
type: string
description: The bank identification code
example: EXMPJPJT
bankName:
type: string
description: The name of the bank
example: Gotham City Bank
branchName:
type: string
description: The name of the bank branch
example: Downtown Branch
sortCode:
type: string
description: The bank sort code (UK); carries the IFSC for India
example: '401234'
iban:
type: string
description: The International Bank Account Number
example: GB00000000000000000000
provider:
type: string
description: The platform providing this account (e.g., wise)
example: wise
currency:
type: string
description: The currency of the bank account
example: USD
beneficiaryId:
$ref: '#/components/schemas/beneficiaryId'
address:
$ref: '#/components/schemas/address'
phoneNumber:
$ref: '#/components/schemas/phoneNumber'
email:
type: string
format: email
description: The email address of the account holder
example: john.doe@example.com
momoDetails:
type: object
properties:
accountName:
type: string
description: The name associated with the mobile money account
example: John Doe
provider:
type: string
description: The name of the mobile money provider
example: MTN
providerCode:
type: string
description: The code identifying the mobile money provider
example: MTN
phoneNumber:
$ref: '#/components/schemas/phoneNumber'
currency:
type: string
description: The currency of the mobile money account
example: GHS
compInfo:
type: object
description: Person's compensation information, how much will they get paid, currency and frequency
properties:
type:
type: string
description: Person's compensation type
example: net
enum:
- net
- salaried
- milestone
salary:
type: object
description: Person's compensation amount
allOf:
- $ref: '#/components/schemas/amount'
frequency:
type: string
description: Person's compensation frequency
example: monthly
enum:
- hourly
- daily
- monthly
employmentModel:
type: string
description: Specifies the employment model for the person. Set to "eor" for Employer of Record employees. When omitted, the person is treated as direct employment.
example: eor
enum:
- eor
basicInfo:
type: object
required:
- email
- firstName
- lastName
properties:
firstName:
type: string
description: Person's first name
example: John
lastName:
type: string
description: Person's last name
example: Doe
email:
type: string
description: Person's email
phoneNumber:
$ref: '#/components/schemas/phoneNumber'
metadata:
type: object
additionalProperties: true
description: Optional metadata you can store as key-value pairs
example:
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cadana/refs/heads/main/openapi/cadana-persons-api-openapi.yml