List Departments

GET /clients/{client_id}/departments

Returns a paginated list of departments for a client organization. Each item is a full Department object including member count.

Path Parameters

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

Query Parameters

Parameter	Type	Default	Description
q	string	-	Search filter against name (case-insensitive, partial match)
sort_by	string	name	Sort field: name, member_count, created_at
sort_order	string	asc	Sort direction: asc, desc
page_size	integer	100	Items per page. Max: 500
cursor	string	-	Pagination cursor from a previous response

Response

Field	Type	Description
data	Department[]	Array of department objects
total_count	integer	Total number of departments matching the current filters
next_cursor	string | null	Cursor to pass as cursor for the next page. null when on the last page.

Example Requests

List all departments

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

Search by name

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/departments?q=eng" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Sort by member count descending

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/departments?sort_by=member_count&sort_order=desc" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

{
  "data": [
    {
      "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"
    },
    {
      "id": "e2b3c4d5-f6a7-8901-bcde-f12345678901",
      "name": "Product",
      "description": "Product management and design",
      "member_count": 12,
      "created_at": "2026-01-10T09:00:00.000Z",
      "updated_at": "2026-01-10T09:00:00.000Z"
    }
  ],
  "total_count": 8,
  "next_cursor": null
}

Pagination

This endpoint uses cursor-based pagination.

1. Omit cursor on the first request
2. If next_cursor is not null, pass its value as cursor on the next request
3. Repeat until next_cursor is null

# Page 1
GET /departments?page_size=100
# → next_cursor: "WyJ0aWNrZXQiXQ"

# Page 2
GET /departments?page_size=100&cursor=WyJ0aWNrZXQiXQ
# → next_cursor: null  (last page)

Error Responses

Status	Description
400	Invalid query parameters (e.g. unknown sort_by value)
401	Authentication required
403	Insufficient permissions for this client
404	Client not found
500	Server error

Related Endpoints

• Get Department - Full profile for a specific department
• Create Department - Create a new department
• List Users - Filter users by department with ?department_id=