> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cadanapay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Departments & Custom Fields
> Organize workers by department and track custom metadata
export const ApiExample = ({method = "GET", path, params, body, reference, tenantKey}) => {
const baseUrl = "https://api.cadanapay.com";
const query = params ? "?" + Object.entries(params).map(([k, v]) => `${k}=${v}`).join("&") : "";
const url = `${baseUrl}${path}${query}`;
const isPlatformPath = (/^\/(v1\/)?platform(\/|$)/).test(path || "");
const includeTenantKey = tenantKey === undefined ? !isPlatformPath : tenantKey;
let curl = `curl -X ${method} '${url}' \\\n -H 'Authorization: Bearer YOUR_API_KEY'`;
if (includeTenantKey) {
curl += ` \\\n -H 'X-MultiTenantKey: YOUR_BUSINESS_TENANT_KEY'`;
}
if (body) {
const formatted = JSON.stringify(body, null, 2);
curl += ` \\\n -H 'Content-Type: application/json' \\\n -d '${formatted}'`;
}
return ;
};
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
Get your API key from the [Cadana Dashboard](https://app.cadanapay.com). See [Authentication](/authentication) for details.
You need a `businessId` for these endpoints. **Platform integrators** receive this from the [`POST /v1/platform/businesses`](/api-reference/workforce/platform/create) response when creating a business. **Direct API users** can find it in the [Dashboard](https://app.cadanapay.com) 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.
**Response:**
```json theme={null}
{
"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.
Returns `204` on success.
### View Departments
Departments are returned as an array on the business object. Use [`GET /v1/businesses/{businessId}`](/api-reference/workforce/businesses/get) to retrieve them.
The response includes a `departments` array:
```json theme={null}
{
"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.
**Response:**
```json theme={null}
{
"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.
Returns `204` on success.
### View Custom Fields
Like departments, custom fields are returned on the business object via [`GET /v1/businesses/{businessId}`](/api-reference/workforce/businesses/get):
```json theme={null}
{
"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`](/api-reference/workforce/persons/update-job-information).
* `department` — pass the department **name** (string), not the ID
* `customFields` — pass an array of objects with `name` and `value`
Returns `204` on success.
For full details on creating persons and setting up job information, see [Onboard Workers](/workforce/onboarding-workers).
***
## Next Steps
Create Person records and assign departments during onboarding
Run payroll for workers across departments
Platform overview and business creation