Organizational API

The Organizational API provides endpoints for managing organizational units and their hierarchical structure within the UBU Digital Finance Solution.

Endpoints

Create Organizational Unit

POST /organization/

Creates a new organizational unit. Requires the create_organizational_unit permission.

Request Body

{
  "unit_name": "string",
  "unit_description": "string",
  "parent_unit_id": "uuid" // Optional, null for top-level units
}

Responses

201 Created - Organizational unit created successfully

{
  "unit_id": "uuid",
  "unit_name": "string",
  "unit_description": "string",
  "parent_unit_id": "uuid",
  "is_active": true
}

400 Bad Request - Validation error

{
  "detail": "Organizational unit with this name already exists."
}

404 Not Found - Parent unit not found

{
  "detail": "Parent organizational unit not found"
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Get All Organizational Units

GET /organization/

Retrieves a list of all organizational units. Requires the view_organizational_units permission.

Responses

200 OK - Organizational units retrieved successfully

[
  {
    "unit_id": "uuid",
    "unit_name": "string",
    "unit_description": "string",
    "parent_unit_id": "uuid",
    "is_active": true
  }
]

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Get Organizational Unit

GET /organization/{unit_id}

Retrieves a specific organizational unit. Requires the view_organizational_units permission.

Path Parameters

unit_id (UUID): ID of the organizational unit

Responses

200 OK - Organizational unit retrieved successfully

{
  "unit_id": "uuid",
  "unit_name": "string",
  "unit_description": "string",
  "parent_unit_id": "uuid",
  "is_active": true,
  "parent": {
    "unit_id": "uuid",
    "unit_name": "string"
  },
  "children": [
    {
      "unit_id": "uuid",
      "unit_name": "string"
    }
  ]
}

404 Not Found - Organizational unit not found

{
  "detail": "Organizational unit not found"
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Update Organizational Unit

PUT /organization/{unit_id}

Updates an organizational unit. Requires the update_organizational_unit permission.

Path Parameters

unit_id (UUID): ID of the organizational unit to update

Request Body

{
  "unit_name": "string",
  "unit_description": "string",
  "parent_unit_id": "uuid", // Optional, null for top-level units
  "is_active": true
}

Responses

200 OK - Organizational unit updated successfully

{
  "unit_id": "uuid",
  "unit_name": "string",
  "unit_description": "string",
  "parent_unit_id": "uuid",
  "is_active": true
}

404 Not Found - Organizational unit not found

{
  "detail": "Organizational unit not found"
}

404 Not Found - Parent unit not found

{
  "detail": "Parent organizational unit not found"
}

400 Bad Request - Validation error

{
  "detail": "Organizational unit with this name already exists."
}

400 Bad Request - Circular reference

{
  "detail": "Cannot set a unit as its own ancestor"
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Delete Organizational Unit

DELETE /organization/{unit_id}

Deletes an organizational unit. Requires the delete_organizational_unit permission.

Path Parameters

unit_id (UUID): ID of the organizational unit to delete

Responses

200 OK - Organizational unit deleted successfully

{
  "detail": "Organizational unit deleted successfully"
}

404 Not Found - Organizational unit not found

{
  "detail": "Organizational unit not found"
}

400 Bad Request - Unit has children

{
  "detail": "Cannot delete organizational unit as it has child units"
}

400 Bad Request - Unit has users

{
  "detail": "Cannot delete organizational unit as it has assigned users"
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Get Users in Organizational Unit

GET /organization/{unit_id}/users

Retrieves the users assigned to an organizational unit. Requires the view_organizational_units permission.

Path Parameters

unit_id (UUID): ID of the organizational unit

Responses

200 OK - Users retrieved successfully

[
  {
    "user_id": "uuid",
    "user_code": "string",
    "user_fullname": "string",
    "user_email": "string",
    "assignment_is_active": true
  }
]

404 Not Found - Organizational unit not found

{
  "detail": "Organizational unit not found"
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Get User's Organizational Units

GET /organization/user/{user_id}

Retrieves the organizational units assigned to a user. Requires the view_organizational_units permission.

Path Parameters

user_id (UUID): ID of the user

Responses

200 OK - Organizational units retrieved successfully

[
  {
    "unit_id": "uuid",
    "unit_name": "string",
    "unit_description": "string",
    "parent_unit_id": "uuid",
    "is_active": true,
    "assignment_is_active": true
  }
]

404 Not Found - User not found

{
  "detail": "User not found"
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Organizational Structure

Organizational units in the UBU Digital Finance Solution are structured hierarchically:

Hierarchical Structure

Each unit can have a parent unit
Units without a parent are considered top-level units
The hierarchy can have multiple levels
Units cannot be their own ancestor (no circular references)

Unit Properties

Unit Name: A human-readable name for the unit
Unit Description: Additional context about what the unit represents
Parent Unit: The parent unit in the hierarchy (optional)
Active Status: Whether the unit is active

Unit Status

Units can be active or inactive:

Active units can be assigned to users
Inactive units cannot be assigned to users
Existing assignments to inactive units are not automatically removed

Default Organizational Units

The system can be configured with default organizational units:

Unit Name	Description	Parent
Headquarters	Main organizational headquarters	None
Finance Department	Department handling financial operations	Headquarters
IT Department	Department handling technology	Headquarters
Operations Department	Department handling day-to-day operations	Headquarters
East Region	Regional office for eastern operations	Headquarters
West Region	Regional office for western operations	Headquarters
Branch Office 1	Local branch office	East Region
Branch Office 2	Local branch office	West Region

Unit Assignment

Organizational units are assigned to users through the User API when creating or updating a user. The assignment includes:

User ID: The ID of the user
Unit ID: The ID of the organizational unit
Active Status: Whether the unit assignment is active

A user can be assigned to multiple organizational units, but typically one primary unit is used for most operations.

Organizational Unit-Based Access Control

The system can implement organizational unit-based access control:

Users are assigned to organizational units
Access to certain resources can be restricted based on organizational unit membership
This provides an additional layer of access control beyond role-based permissions
Useful for implementing branch-level or department-level restrictions