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,
  "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
}

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,
  "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
}

Update Department

PUT|POST /api/v2/departments/{id}

Updates an existing department. Only name, is_active, and autonomy_level can be modified; any other field in the body, including client_account_id, is ignored.

Request Body

Example Request

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

Response

{
  "id": 123,
  "name": "Updated Department Name",
  "client_account_id": 456,
  "sequence_number": 1,
  "is_active": true,
  "autonomy_level": "DRAFT",
  "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,
  "autonomy_level": null,
  "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": {
        "code": "common.validation_error",
        "message": "Cannot deactivate department: account 1500: 8500.00, account 2400: -1200.00",
        "request_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
    }
}

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

Relationships

Each balance is debit minus credit across journal entry lines tagged with the department. Statistics are limited to balance-sheet accounts (account code 2999 and below). Balances for income-statement accounts (account code 3000 and above) are not included, and accounts with a zero balance are omitted.

Example Response with Statistics

GET /api/v2/departments/123?with=statistics

{
  "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,
  "statistics": {
    "balances": [
      { "account_code": "1500", "balance": 8500.0 },
      { "account_code": "2400", "balance": -1200.0 }
    ]
  }
}

Error Responses

Errors use the standard v2 envelope ({"error": {"code", "message", "request_id"}}).

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; it is ignored in update requests
4. Department names must be unique within a client account when the department is created, including names of deactivated departments
5. Each department is automatically assigned a unique sequence number within its client account
6. 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