Departments

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

  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

Relaterte artikler