Get Department

GET /clients/{client_id}/departments/{department_id}

Returns the full profile for a specific department, fetched directly by ID.

When to use this endpoint

You should always be able to fetch any known resource directly by its ID. The list endpoint is for discovery -- this endpoint is for direct access.

Scenario	Why this endpoint
User clicks a department in the table, app navigates to its detail page	Load one department by ID without fetching the full list
Refresh one department's state after a PATCH	Re-fetch only that department, not the whole list
An integration or script needs to look up a specific department	Direct ID lookup, no search required

GET /departments is the right call when you need a collection. GET /departments/{id} is the right call when you already know which department you need.

Path Parameters

Parameter	Type	Description
client_id	string (uuid)	Unique identifier for the client organization
department_id	string (uuid)	Unique identifier for the department

Response

Returns a single Department object.

Field	Type	Nullable	Description
id	string (uuid)	No	Stable unique identifier for the department
name	string	No	Department display name
description	string	Yes	Optional department description
member_count	integer	No	Number of users currently assigned to this department
created_at	string (ISO 8601)	No	When this department record was first created
updated_at	string (ISO 8601)	No	When this department record was last modified

Example Request

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/departments/d1a2b3c4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

{
  "id": "d1a2b3c4-e5f6-7890-abcd-ef1234567890",
  "name": "Engineering",
  "description": "Software development and infrastructure teams",
  "member_count": 45,
  "created_at": "2026-01-10T09:00:00.000Z",
  "updated_at": "2026-02-05T21:29:34.214Z"
}

Department with no members or description

{
  "id": "f3c4d5e6-a7b8-9012-cdef-123456789012",
  "name": "New Team",
  "description": null,
  "member_count": 0,
  "created_at": "2026-02-24T10:00:00.000Z",
  "updated_at": "2026-02-24T10:00:00.000Z"
}

Error Responses

Status	Description
401	Authentication required
403	Insufficient permissions for this client
404	Department or client not found
500	Server error

{
  "error": {
    "code": "not_found",
    "message": "Department not found",
    "details": {
      "department_id": "ffffffff-ffff-ffff-ffff-ffffffffffff"
    }
  }
}

Related Endpoints

• List Departments - Paginated list of departments
• Update Department - Update a department's name or description
• Delete Department - Delete a department
• List Users - Get users in this department with ?department_id=