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

Response

{
  "data": [
    {
      "id": 123,
      "name": "Sales Department",
      "client_account_id": 456,
      "sequence_number": 1,
      "is_active": true,
      "autonomy_level": null,
      "created_at": "2024-03-15T10:00:00Z",
      "updated_at": "2024-03-15T10:00:00Z",
      "created_by_id": 789,
      "updated_by_id": 789,
      "client_account": {
        "id": 456,
        "unique_name": "company-abc",
        "display_name": "Company ABC"
      }
    }
  ],
  "meta": {
    "page": 1,
    "pages": 1,
    "per_page": 50,
    "records": 1
  }
}

The client_account field is only included when with=client_account is in the query.

Department Attributes

Get Department

GET /api/v2/departments/{id}

Retrieves a specific department by ID.

Query Parameters

Response

{
  "id": 123,
  "name": "Sales Department",
  "client_account_id": 456,
  "sequence_number": 1,
  "is_active": true,
  "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

Example Request

{
  "name": "Sales Department",
  "client_account_id": 456
}

Response

{
  "id": 123,
  "name": "Sales Department",
  "client_account_id": 456,
  "sequence_number": 1,
  "is_active": true,
  "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|POST /api/v2/departments/{id}

Updates an existing department. Only name, is_active, and autonomy_level can be modified. client_account_id cannot be changed after creation.

Request Body

Example Request

{
  "name": "Updated Department Name",
  "autonomy_level": "INDEPENDENT"
}

Response

{
  "id": 123,
  "name": "Updated Department Name",
  "client_account_id": 456,
  "sequence_number": 1,
  "is_active": true,
  "created_at": "2024-03-15T10:00:00Z",
  "updated_at": "2024-03-15T15:30:00Z",
  "created_by_id": 789,
  "updated_by_id": 789
}

Deactivate Department

DELETE /api/v2/departments/{id}

Deactivates a department by setting its is_active status to false. The department record is preserved for historical purposes.

Response

{
  "id": 123,
  "name": "Sales Department",
  "client_account_id": 456,
  "sequence_number": 1,
  "is_active": false,
  "created_at": "2024-03-15T10:00:00Z",
  "updated_at": "2024-03-15T16:00:00Z",
  "created_by_id": 789,
  "updated_by_id": 789
}

Deactivation Validation

When attempting to deactivate a department, the system performs validation to ensure data integrity:

• Balance Checking: The system checks if any accounting accounts with mandatory department dimensions have non-zero balances for this specific department.
• Validation Failure: If any accounts have non-zero balances, the deactivation is denied with a 400 Bad Request error.
• Error Details: The error message includes specific account codes and their balances to help identify which transactions need to be resolved.

Example Error Response

{
    "error": "Cannot deactivate department: account 4000: 8500.00, account 5000: -1200.00",
    "status": 400
}

This validation ensures that departments cannot be deactivated while they still have outstanding balances, maintaining the integrity of your accounting records.

Error Responses

Business Rules

1. Departments are associated with a specific client account
2. Users must have access to the client account to manage its departments
3. The client_account_id cannot be changed after department creation
4. Each department is automatically assigned a unique sequence number within its client account
5. Creation and update timestamps and user IDs are automatically tracked

Common Use Cases

1. Creating organizational structure within a company
2. Tracking activities by department
3. Managing departmental resources
4. Organizing reporting by business unit

Best Practices

1. Use clear and descriptive department names
2. Maintain consistent naming conventions
3. Consider the organizational hierarchy when creating departments
4. Use the sequence_number for internal reference