Departments

Departments let you group a company's employees by team or function. Each department has a name and, optionally, a phone number, a phone extension, and a manager. The manager must be an employee of the same company.

Unlike Divisions, departments don't have to be activated. You can create one as soon as the company exists.

This page covers creating, listing, retrieving, updating, and deleting departments, and how employees are assigned to them.

All endpoints on this page require a bearer access token (see How to Get API Access). CLIENT_ID is the company identifier returned as id when you create the company.

The department object

Field	Type	Description
`id`	integer	The department's unique identifier. Use it as `DEPARTMENT_ID` in the endpoints below.
`name`	string	Department name.
`phone`	string	Department phone number. Empty string if not set.
`ext`	string	Phone extension. Omitted if not set.
`managerId`	integer	The `id` of the employee who manages the department. Omitted if the department has no manager.

Create a Department

Adds a department to a company.

Endpoint

POST https://api.worklio.com/wep/companies/{CLIENT_ID}/departments

Parameter	Type	Required	Description
`CLIENT_ID`	integer	Yes	The company's `id`. Path parameter.

Request body

Field	Type	Required	Description
`name`	string	Yes	Department name.
`phone`	string	No	Department phone number.
`ext`	string	No	Phone extension, for example `"123"`.
`managerId`	integer	No	The `id` of an employee in this company.

Example request

require("dotenv").config();

const TOKEN = process.env.API_KEY;
const CLIENT_ID = process.env.CLIENT_ID;
const url = `https://api.worklio.com/wep/companies/${CLIENT_ID}/departments`;

const payload = {
  name: "Customer Support",
  phone: "+12125550142",
  managerId: 4321
};

async function createDepartment() {
  const response = await fetch(url, {
    method: "POST",
    headers: {
      accept: "application/json",
      "api-version": "2.0",
      authorization: `Bearer ${TOKEN}`,
      "content-type": "application/json",
      "x-api-version": "2.0"
    },
    body: JSON.stringify(payload)
  });

  console.log(response.status);
  const raw = await response.text();
  console.log(JSON.stringify(JSON.parse(raw), null, 2));
}

createDepartment();

curl -s -X POST "https://api.worklio.com/wep/companies/$CLIENT_ID/departments" \
  -H "accept: application/json" \
  -H "api-version: 2.0" \
  -H "authorization: Bearer $API_KEY" \
  -H "content-type: application/json" \
  -H "x-api-version: 2.0" \
  -d '{
    "name": "Customer Support",
    "phone": "+12125550142",
    "managerId": 4321
  }' | jq .

Example response

{
  "id": 80,
  "name": "Customer Support",
  "phone": "+12125550142",
  "managerId": 4321
}

id is the new department's unique identifier. Save it — you'll need it as DEPARTMENT_ID to get, update, delete or assign employee to this this department.

This endpoint returns 201.

List Departments

Returns every department for a company, as an array. This endpoint has no pagination, filtering, or sorting — it always returns all departments.

Endpoint

GET https://api.worklio.com/wep/companies/{CLIENT_ID}/departments

Parameter	Type	Required	Description
`CLIENT_ID`	integer	Yes	The company's `id`. Path parameter.

Example request

require("dotenv").config();

const TOKEN = process.env.API_KEY;
const CLIENT_ID = process.env.CLIENT_ID;
const url = `https://api.worklio.com/wep/companies/${CLIENT_ID}/departments`;

async function listDepartments() {
  const response = await fetch(url, {
    method: "GET",
    headers: {
      accept: "application/json",
      "api-version": "2.0",
      authorization: `Bearer ${TOKEN}`,
      "x-api-version": "2.0"
    }
  });

  console.log(response.status);
  const raw = await response.text();
  console.log(JSON.stringify(JSON.parse(raw), null, 2));
}

listDepartments();

curl -s -X GET "https://api.worklio.com/wep/companies/$CLIENT_ID/departments" \
  -H "accept: application/json" \
  -H "api-version: 2.0" \
  -H "authorization: Bearer $API_KEY" \
  -H "x-api-version: 2.0" | jq .

Example response

[
  {
    "id": 79,
    "name": "Warehouse",
    "phone": ""
  },
  {
    "id": 80,
    "name": "Customer Support",
    "phone": "+12125550142",
    "managerId": 4321
  }
]

Each entry has the fields described in The department object.

Get a Department

Returns one department.

Endpoint

GET https://api.worklio.com/wep/companies/{CLIENT_ID}/departments/{DEPARTMENT_ID}

Parameter	Type	Required	Description
`CLIENT_ID`	integer	Yes	The company's `id`. Path parameter.
`DEPARTMENT_ID`	integer	Yes	The department's `id`, as returned by List Departments or Create a Department. Path parameter.

No request body.

Example request

require("dotenv").config();

const TOKEN = process.env.API_KEY;
const CLIENT_ID = process.env.CLIENT_ID;
const DEPARTMENT_ID = 79;
const url = `https://api.worklio.com/wep/companies/${CLIENT_ID}/departments/${DEPARTMENT_ID}`;

async function getDepartment() {
  const response = await fetch(url, {
    method: "GET",
    headers: {
      accept: "application/json",
      "api-version": "2.0",
      authorization: `Bearer ${TOKEN}`,
      "x-api-version": "2.0"
    }
  });

  console.log(response.status);
  const raw = await response.text();
  console.log(JSON.stringify(JSON.parse(raw), null, 2));
}

getDepartment();

curl -s -X GET "https://api.worklio.com/wep/companies/$CLIENT_ID/departments/79" \
  -H "accept: application/json" \
  -H "api-version: 2.0" \
  -H "authorization: Bearer $API_KEY" \
  -H "x-api-version: 2.0" | jq .

Example response

{
  "id": 79,
  "name": "Warehouse",
  "phone": ""
}

Update a Department

Changes a department's details.

Content type

This endpoint requires application/merge-patch+json, not application/json.

content-type: application/merge-patch+json

Endpoint

PATCH https://api.worklio.com/wep/companies/{CLIENT_ID}/departments/{DEPARTMENT_ID}

Parameter	Type	Required	Description
`CLIENT_ID`	integer	Yes	The company's `id`. Path parameter.
`DEPARTMENT_ID`	integer	Yes	The department's `id`, as returned by List Departments or Create a Department. Path parameter.

Request body

Field	Type	Required	Description
`name`	string	Yes	Department name. Send it on every update, even when you aren't changing it.
`phone`	string	No	Department phone number.
`ext`	string	No	Phone extension.
`managerId`	integer or `null`	No	The `id` of an employee in this company. Send `null` to remove the manager.

🚧
name is required on every update. This endpoint is a partial update for the other fields, but a request without name is not valid. To change only the phone number, send the current name together with the new phone.

Example request

require("dotenv").config();

const TOKEN = process.env.API_KEY;
const CLIENT_ID = process.env.CLIENT_ID;
const DEPARTMENT_ID = 80;
const url = `https://api.worklio.com/wep/companies/${CLIENT_ID}/departments/${DEPARTMENT_ID}`;

const payload = {
  name: "Customer Support",
  phone: "+12125550188",
  ext: "123"
};

async function updateDepartment() {
  const response = await fetch(url, {
    method: "PATCH",
    headers: {
      accept: "application/json",
      "api-version": "2.0",
      authorization: `Bearer ${TOKEN}`,
      "content-type": "application/merge-patch+json",
      "x-api-version": "2.0"
    },
    body: JSON.stringify(payload)
  });

  console.log(response.status);
  const raw = await response.text();
  console.log(JSON.stringify(JSON.parse(raw), null, 2));
}

updateDepartment();

curl -s -X PATCH "https://api.worklio.com/wep/companies/$CLIENT_ID/departments/80" \
  -H "accept: application/json" \
  -H "api-version: 2.0" \
  -H "authorization: Bearer $API_KEY" \
  -H "content-type: application/merge-patch+json" \
  -H "x-api-version: 2.0" \
  -d '{
    "name": "Customer Support",
    "phone": "+12125550188",
    "ext": "123"
  }' | jq .

Example response

A successful update returns the full, updated department. Fields you didn't send keep their current values.

{
  "id": 80,
  "name": "Customer Support",
  "phone": "+12125550188",
  "ext": "123",
  "managerId": 4321
}

Remove the manager

To remove a department's manager, send managerId as null:

{
  "name": "Customer Support",
  "managerId": null
}

Delete a Department

Deletes a department. Use newDepartmentId to move the department's employees into another department as part of the delete.

Endpoint

DELETE https://api.worklio.com/wep/companies/{CLIENT_ID}/departments/{DEPARTMENT_ID}

Parameter	Type	Required	Description
`CLIENT_ID`	integer	Yes	The company's `id`. Path parameter.
`DEPARTMENT_ID`	integer	Yes	The `id` of the department to delete. Path parameter.

Request body

Field	Type	Required	Description
`newDepartmentId`	integer	No	The `id` of the department that receives the deleted department's employees. It must belong to the same company.
`effectiveDate`	string	No	Date the change takes effect, in `YYYY-MM-DD` format.

🚧
If you send a request without effectiveDate, the day of the request gets used. If you dont specify newDepartmentId employees will be without a department.

Example request

This example deletes department 79 and moves its employees to department 80.

require("dotenv").config();

const TOKEN = process.env.API_KEY;
const CLIENT_ID = process.env.CLIENT_ID;
const DEPARTMENT_ID = 79;
const url = `https://api.worklio.com/wep/companies/${CLIENT_ID}/departments/${DEPARTMENT_ID}`;

const payload = {
  effectiveDate: "2026-09-29",
  newDepartmentId: 80
};

async function deleteDepartment() {
  const response = await fetch(url, {
    method: "DELETE",
    headers: {
      accept: "application/json",
      "api-version": "2.0",
      authorization: `Bearer ${TOKEN}`,
      "content-type": "application/json",
      "x-api-version": "2.0"
    },
    body: JSON.stringify(payload)
  });

  console.log(response.status);
}

deleteDepartment();

curl --request DELETE \
  --url "https://api.worklio.com/wep/companies/$CLIENT_ID/departments/79" \
  --header "accept: application/json" \
  --header "api-version: 2.0" \
  --header "authorization: Bearer $API_KEY" \
  --header "content-type: application/json" \
  --header "x-api-version: 2.0" \
  --data '{
    "effectiveDate": "2026-09-29",
    "newDepartmentId": 80
  }' \
  --include

Example response

A successful delete returns 204 with no response body.

Assigning employees to a department

When assigning employee to department use PATCH employee see Employee Basics with departmentId it employees contract.

require("dotenv").config();

const TOKEN = process.env.API_KEY
const CLIENT_ID = process.env.CLIENT_ID;
const EMPLOYEE_ID = process.env.EMPLOYEE_ID
const URL = process.env.URL
const url = `${URL}/wep/companies/${CLIENT_ID}/employees/${EMPLOYEE_ID}`;

const payload = {

  contract: {
    departmentId: 80
  },

};

async function createEmployee() {
  const response = await fetch(url, {
    method: "PATCH",
    headers: {
      accept: "application/json",
      "api-version": "2.0",
      authorization: `Bearer ${TOKEN}`,
      "content-type": "application/merge-patch+json",
      "x-api-version": "2.0"
    },
    body: JSON.stringify(payload)
  });

  console.log(response.status);
  const raw = await response.text();
  console.log(JSON.stringify(JSON.parse(raw), null, 2));
}

createEmployee();

curl --request PATCH \
  --url "$URL/wep/companies/$CLIENT_ID/employees/$EMPLOYEE_ID" \
  --header "accept: application/json" \
  --header "api-version: 2.0" \
  --header "x-api-version: 2.0" \
  --header "authorization: Bearer $API_KEY" \
  --header "content-type: application/merge-patch+json" \
  --data '{"contract":{"departmentId":80}}' \
  --include

{
  "id": 4277,
  "firstName": "Michael",
  "lastName": "Brown",
  "middleName": "",
  .
  .
  .
  "contract": {
    "id": 2977,
    "startOn": "2026-09-11",
    "workSchedule": 2,
    "compensationType": 1,
    "compensableHours": 40,
    "compensationAmount": 90000,
    "compensationNumberOfUnits": 0,
    "isStatutory": true,
    "is943": false,
    "workLocationId": 0,
    "departmentId": 80,  //ASSIGNED DEPARTMENT ID
    "divisionId": 128,
    "wcCode": "0000",
    "socCode": "151252",
    "policyId": 1084,
    "payrollPolicyId": 1084,
    "toGroupId": 724,
    "workerType": 0,
    "payPeriod": 1,
    "status": 1
  },
  .
  .
  .
}

Employees contract was updated with departmentId 80.

Creating or updating a department triggers the Department Created and Updated webhook events — see Webhook Event Types. There is no Deleted event for departments.

Departments

The department object

Create a Department

Endpoint

Request body

Example request

Example response

List Departments

Endpoint

Example request

Example response

Get a Department

Endpoint

Example request

Example response

Update a Department

Content type

Endpoint

Request body

`name` is required on every update. This endpoint is a partial update for the other fields, but a request without `name` is not valid. To change only the phone number, send the current `name` together with the new `phone`.

Example request

Example response

Remove the manager

Delete a Department

Endpoint

Request body

If you send a request without effectiveDate, the day of the request gets used. If you dont specify newDepartmentId employees will be without a department.

Example request

Example response

Assigning employees to a department

Related

The department object

Create a Department

Endpoint

Request body

Example request

Example response

List Departments

Endpoint

Example request

Example response

Get a Department

Endpoint

Example request

Example response

Update a Department

Content type

Endpoint

Request body

name is required on every update. This endpoint is a partial update for the other fields, but a request without name is not valid. To change only the phone number, send the current name together with the new phone.

Example request

Example response

Remove the manager

Delete a Department

Endpoint

Request body

If you send a request without effectiveDate, the day of the request gets used. If you dont specify newDepartmentId employees will be without a department.

Example request

Example response

Assigning employees to a department

Related

`name` is required on every update. This endpoint is a partial update for the other fields, but a request without `name` is not valid. To change only the phone number, send the current `name` together with the new `phone`.