Departments
Departments represent organizational units within a client account, allowing for better organization and tracking of business activities.
Endpoints
List Departments
GET /api/v2/departments
Retrieves a paginated list of departments.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_account_id | integer | No | Filter departments by client account |
| page | integer | No | Page number (default: 1) |
| per_page | integer | No | Items per page (default: 50) |
| with | string | No | Include related resources (supported: client_account) |
Response
{
"data": [
{
"id": 123,
"name": "Sales Department",
"client_account_id": 456,
"sequence_number": 1,
"created_at": "2024-03-15T10:00:00Z",
"updated_at": "2024-03-15T10:00:00Z",
"created_by_id": 789,
"updated_by_id": 789,
"client_account": { // Only included when with=client_account
"id": 456,
"unique_name": "company-abc",
"display_name": "Company ABC"
}
}
],
"meta": {
"page": 1,
"pages": 1,
"per_page": 50,
"records": 1
}
}
Get Department
GET /api/v2/departments/{id}
Retrieves a specific department by ID.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| with | string | No | Include related resources (supported: client_account) |
Response
{
"id": 123,
"name": "Sales Department",
"client_account_id": 456,
"sequence_number": 1,
"created_at": "2024-03-15T10:00:00Z",
"updated_at": "2024-03-15T10:00:00Z",
"created_by_id": 789,
"updated_by_id": 789
}
Create Department
POST /api/v2/departments
Creates a new department.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | The name of the department |
| client_account_id | integer | Yes | The ID of the client account |
Example Request
{
"name": "Sales Department",
"client_account_id": 456
}
Response
{
"id": 123,
"name": "Sales Department",
"client_account_id": 456,
"sequence_number": 1,
"created_at": "2024-03-15T10:00:00Z",
"updated_at": "2024-03-15T10:00:00Z",
"created_by_id": 789,
"updated_by_id": 789
}
Update Department
PUT /api/v2/departments/{id}
Updates an existing department.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | The new name for the department |
Example Request
{
"name": "Updated Department Name"
}
Response
{
"id": 123,
"name": "Updated Department Name",
"client_account_id": 456,
"sequence_number": 1,
"created_at": "2024-03-15T10:00:00Z",
"updated_at": "2024-03-15T15:30:00Z",
"created_by_id": 789,
"updated_by_id": 789
}
Error Responses
| Status Code | Description |
|---|---|
| 400 | Invalid request (e.g., missing required fields) |
| 403 | Forbidden (no access to client account) |
| 404 | Department not found |
Business Rules
- Departments are associated with a specific client account
- Users must have access to the client account to manage its departments
- The client_account_id cannot be changed after department creation
- Each department is automatically assigned a unique sequence number within its client account
- Creation and update timestamps and user IDs are automatically tracked
Common Use Cases
- Creating organizational structure within a company
- Tracking activities by department
- Managing departmental resources
- Organizing reporting by business unit
Best Practices
- Use clear and descriptive department names
- Maintain consistent naming conventions
- Consider the organizational hierarchy when creating departments
- Use the sequence_number for internal reference