Departments

A department is the team a task belongs to, such as Housekeeping or Maintenance. Every task needs one: createTask requires a departmentId, and listTasks can filter on it. A department’s category also changes how its tasks complete. This guide covers the three department operations. Every field is listed on the operation’s page in the API Reference.

Operation	Request	Permission
listDepartments	GET /departments	view_tasks
createDepartment	POST /departments	modify_tasks
updateDepartment	PATCH /departments/{id}	modify_tasks

Paths are relative to your region’s base URL, for example https://api-us.suiteop.com/api/v1. See Authentication for permissions.

The API can’t archive or delete a department, add or remove its members, or change its auto-assignment settings. Those are only available in the app.

Categories

category is required on create and takes one of cleans, maintenance, inspections, guest_experience or other. It is not just a label: completing a task that has a property in a cleans or inspections department requires a property status declaration (see Tasks). Choose it deliberately, and don’t recategorize a department that has open tasks as part of a routine sync.

Listing departments

GET /departments is paginated (default limit 50, maximum 100) and returns only active departments, ordered by their stored name.

curl "https://api-us.suiteop.com/api/v1/departments?nameContains=clean&language=fr" \
  -H "Authorization: Bearer sk_live_your_key_here"

{
  "data": [
    {
      "id": "0b6f2c1e-4d3a-4f8b-9c2e-7a1d5e6f8b90",
      "name": "Ménage",
      "description": "Turnover cleans",
      "color": "#847AEA",
      "category": "cleans",
      "assignmentMethod": null,
      "backupAssignmentMethod": null,
      "autoAssignEnabled": false,
      "blockingPriority": "high",
      "isMaintenance": false,
      "archivedAt": null,
      "createdAt": "2026-03-02T14:05:11.000Z",
      "updatedAt": "2026-08-19T09:40:27.000Z",
      "activeTaskCount": 12,
      "memberCount": 4,
      "managerNames": ["Ana Ruiz"]
    }
  ],
  "meta": {
    "requestId": "3f1c9a52-…",
    "pagination": { "total": 1, "limit": 50, "offset": 0 }
  }
}

• nameContains is a case-insensitive substring. It matches the stored name or the name translated into language. % and _ are matched literally, not as wildcards.
• language resolves name into that language, falling back to the stored name when there is no translation. It defaults to English. The order still follows the stored name.
• includeArchived=true also returns archived departments. Their archivedAt is set.
• ids returns only the departments you name, up to 200. Repeat the parameter for each ID (?ids=…&ids=…).
• forMemberId returns the departments one member belongs to. It takes the member’s memberId from listTeamMembers, not their userId.
• category keeps one category.

activeTaskCount counts tasks that are neither completed nor cancelled. memberCount and managerNames are read-only here.

Creating a department

POST /departments needs name and category. It answers 201 with the new department.

curl -X POST https://api-us.suiteop.com/api/v1/departments \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Idempotency-Key: 6a1f3c9e-2b7d-4e5a-8c0f-1d9b3e7a5c24" \
  -H "Content-Type: application/json" \
  -d '{"name": "Pool care", "category": "maintenance", "color": "#1E90FF", "blockingPriority": "medium"}'

{
  "data": {
    "id": "5c2e8a1f-9b3d-4a6e-8f7c-0d1b2e3f4a5b",
    "name": "Pool care",
    "nameId": "a4d9e2c1-7f3b-4e8a-9c5d-2b1e0f6a7c83",
    "description": null,
    "color": "#1E90FF",
    "category": "maintenance",
    "blockingPriority": "medium",
    "isMaintenance": false,
    "autoAssignEnabled": false,
    "archivedAt": null,
    "createdAt": "2026-09-30T10:14:02.000Z",
    "updatedAt": "2026-09-30T10:14:02.000Z"
  },
  "meta": { "requestId": "…" }
}

• name must not match another active department in the organization, or the call returns 409 conflict_error. An archived department may hold the same name. Call listDepartments first to see whether a suitable one already exists.
• color is a six-digit hex colour with a leading #. It defaults to #847AEA.
• blockingPriority is one of watch, low, medium, high or urgent, and is unset when omitted.
• language is the language name is written in. SuiteOp stores the name as a translatable string, and nameId is its translation record, which getTranslationEntries reads.
• The new department has no members. Add them in the app.

Send an Idempotency-Key so a retried create doesn’t make a second department (see Idempotency).

Updating a department

PATCH /departments/{id} takes a data object. Send only the fields you are changing.

curl -X PATCH "https://api-us.suiteop.com/api/v1/departments/5c2e8a1f-9b3d-4a6e-8f7c-0d1b2e3f4a5b" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"data": {"blockingPriority": null, "isMaintenance": true}}'

• name, description, color, category, blockingPriority (null unsets it) and isMaintenance can change. A new name must not match another active department, or the call returns 409 conflict_error. language names the language of the new name.
• data must change at least one field. An empty data, or one holding only language, returns 400 validation_error.
• Any other key is rejected with 400 validation_error rather than ignored. That includes managers, departmentUsers, autoAssignEnabled and maxDailyHours: membership and auto-assignment are only set in the app.
• A department in another organization returns 404 not_found_error. Archived departments can still be updated.

The response is the department in the same shape createDepartment returns.

Note

The list rows and the create/update response are different shapes. Only the create and update responses carry nameId, and only list rows carry activeTaskCount, memberCount, managerNames and the assignment methods.