Skip to main content
Departments and custom fields let you define organizational structure and track arbitrary metadata for your workforce. Both are defined at the business level, then assigned to individual workers via their job information.
  • Departments — organizational units like “Engineering” or “Sales”
  • Custom fields — arbitrary metadata like “T-shirt Size” or “Employee ID”
Once created on a business, departments and custom fields become available to assign when updating a person’s jobInfo.

​
Prerequisites

1

API key from Dashboard

Get your API key from the Cadana Dashboard. See Authentication for details.
2

Your business ID

You need a businessId for these endpoints. Platform integrators receive this from the POST /v1/platform/businesses response when creating a business. Direct API users can find it in the Dashboard under Settings > Business.

​
Departments

​
Create Departments

Create one or more departments in a single request. Pass an array of department names in the data field.
bash
curl -X POST 'https://api.cadanapay.com/v1/businesses/3e8b9a1c-5d4f-4a2e-b7c6-9f0e8d7c6b5a/departments' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Response: 
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Engineering"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Sales"
    },
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "name": "Operations"
    }
  ]
}

​
Update a Department

Rename an existing department by its ID.
bash
curl -X PUT 'https://api.cadanapay.com/v1/businesses/3e8b9a1c-5d4f-4a2e-b7c6-9f0e8d7c6b5a/departments/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Returns 204 on success.

​
View Departments

Departments are returned as an array on the business object. Use GET /v1/businesses/{businessId} to retrieve them.
bash
curl -X GET 'https://api.cadanapay.com/v1/businesses/3e8b9a1c-5d4f-4a2e-b7c6-9f0e8d7c6b5a' \
  -H 'Authorization: Bearer YOUR_API_KEY'
The response includes a departments array: 
{
  "id": "3e8b9a1c-5d4f-4a2e-b7c6-9f0e8d7c6b5a",
  "name": "ACME LLC",
  "departments": [
    { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Legal" },
    { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Sales" },
    { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "name": "Operations" }
  ],
  "customFields": []
}

​
Custom Fields

​
Create Custom Fields

Create one or more custom fields in a single request. Pass an array of field names in the data field.
bash
curl -X POST 'https://api.cadanapay.com/v1/businesses/3e8b9a1c-5d4f-4a2e-b7c6-9f0e8d7c6b5a/customFields' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Response: 
{
  "data": [
    {
      "id": "d4e5f6a7-b8c9-0123-def0-234567890123",
      "name": "T-shirt Size",
      "value": ""
    },
    {
      "id": "e5f6a7b8-c9d0-1234-ef01-345678901234",
      "name": "Desk Number",
      "value": ""
    }
  ]
}
Custom fields are created with an empty value. Values are set per-person when you assign the field via jobInfo.

​
Update a Custom Field

Rename an existing custom field by its ID.
bash
curl -X PUT 'https://api.cadanapay.com/v1/businesses/3e8b9a1c-5d4f-4a2e-b7c6-9f0e8d7c6b5a/customFields/d4e5f6a7-b8c9-0123-def0-234567890123' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Returns 204 on success.

​
View Custom Fields

Like departments, custom fields are returned on the business object via GET /v1/businesses/{businessId}: 
{
  "customFields": [
    { "id": "d4e5f6a7-b8c9-0123-def0-234567890123", "name": "Employee ID", "value": "" },
    { "id": "e5f6a7b8-c9d0-1234-ef01-345678901234", "name": "Desk Number", "value": "" }
  ]
}

​
Assign to Workers

Once departments and custom fields exist on the business, assign them to individual workers via PUT /v1/persons/{personId}/jobInfo.
  • department — pass the department name (string), not the ID
  • customFields — pass an array of objects with name and value
bash
curl -X PUT 'https://api.cadanapay.com/v1/persons/8ef9a712-cdae-4110-b1ea-9ba95abbee6e/jobInfo' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Returns 204 on success.
For full details on creating persons and setting up job information, see Onboard Workers.

​
Next Steps

Onboard Workers

Create Person records and assign departments during onboarding

Pay Workers via Payroll

Run payroll for workers across departments

Business Setup

Platform overview and business creation