> For the complete documentation index, see [llms.txt](https://qbits-organization.gitbook.io/buildwise-doc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://qbits-organization.gitbook.io/buildwise-doc/organisation/organisation-management.md).

# Organisation Management

### Create Organisation

Creates a new organisation for the authenticated user.

#### Endpoint

```http
POST /api/v1/organisation
```

#### Request Body

```json
{
  "name": "My Construction Company",
  "description": "Leading construction services provider"
}
```

#### Validation Rules

* `name`: Required, cannot be blank
* `description`: Optional
* Organisation name must be unique per user

#### Success Response

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Organisation created successfully",
  "action_time": "2025-05-27T14:30:15.123456",
  "data": {
    "organisationId": "123e4567-e89b-12d3-a456-426614174000",
    "organisationName": "My Construction Company",
    "ownerId": "987fcdeb-51a2-43d1-9f12-123456789abc",
    "ownerUserName": "john.doe",
    "description": "Leading construction services provider",
    "active": true,
    "deleted": false,
    "createdAt": "2025-05-27T14:30:15.123456",
    "updatedAt": "2025-05-27T14:30:15.123456"
  }
}
```

#### Error Responses

* `400` - Organisation name already exists for user
* `401` - Unauthorized (invalid token)
* `422` - Validation errors

### Get Organisation by ID

Retrieves any organisation by its ID (public access).

#### Endpoint

```http
GET /api/v1/organisation/{id}
```

#### Path Parameters

* `id` (UUID): Organisation identifier

#### Success Response

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Organisation retrieved successfully",
  "action_time": "2025-05-27T14:35:20.654321",
  "data": {
    "organisationId": "123e4567-e89b-12d3-a456-426614174000",
    "organisationName": "My Construction Company",
    "ownerId": "987fcdeb-51a2-43d1-9f12-123456789abc",
    "ownerUserName": "john.doe",
    "description": "Leading construction services provider",
    "active": true,
    "deleted": false,
    "createdAt": "2025-05-27T14:30:15.123456",
    "updatedAt": "2025-05-27T14:30:15.123456"
  }
}
```

#### Error Responses

* `404` - Organisation not found
* `401` - Unauthorized

### Get My Organisation by ID

Retrieves a specific organisation owned by the authenticated user.

#### Endpoint

```http
GET /api/v1/organisation/my/{id}
```

#### Path Parameters

* `id` (UUID): Organisation identifier

#### Success Response

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Your organisation retrieved successfully",
  "action_time": "2025-05-27T14:40:30.789123",
  "data": {
    "organisationId": "123e4567-e89b-12d3-a456-426614174000",
    "organisationName": "My Construction Company",
    "ownerId": "987fcdeb-51a2-43d1-9f12-123456789abc",
    "ownerUserName": "john.doe",
    "description": "Leading construction services provider",
    "active": true,
    "deleted": false,
    "createdAt": "2025-05-27T14:30:15.123456",
    "updatedAt": "2025-05-27T14:30:15.123456"
  }
}
```

#### Error Responses

* `404` - Organisation not found or not owned by user
* `401` - Unauthorized

***

### Get All Organisations

Retrieves all organisations in the system (public access).

#### Endpoint

```http
GET /api/v1/organisation
```

#### Success Response

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "All organisations retrieved successfully",
  "action_time": "2025-05-27T14:45:45.456789",
  "data": [
    {
      "organisationId": "123e4567-e89b-12d3-a456-426614174000",
      "organisationName": "Construction Co A",
      "ownerId": "987fcdeb-51a2-43d1-9f12-123456789abc",
      "ownerUserName": "john.doe",
      "description": "Professional construction services",
      "active": true,
      "deleted": false,
      "createdAt": "2025-05-27T14:30:15.123456",
      "updatedAt": "2025-05-27T14:30:15.123456"
    },
    {
      "organisationId": "456f7890-e12c-34d5-b678-901234567def",
      "organisationName": "Building Solutions Ltd",
      "ownerId": "321fedcb-a987-6543-210f-fedcba987654",
      "ownerUserName": "jane.smith",
      "description": "Innovative building solutions",
      "active": true,
      "deleted": false,
      "createdAt": "2025-05-26T10:15:30.987654",
      "updatedAt": "2025-05-26T10:15:30.987654"
    }
  ]
}
```

#### Error Responses

* `401` - Unauthorized

***

### Get My Organisations

Retrieves all organisations owned by the authenticated user.

#### Endpoint

```http
GET /api/v1/organisation/my
```

#### Success Response

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Your organisations retrieved successfully",
  "action_time": "2025-05-27T14:50:10.234567",
  "data": [
    {
      "organisationId": "123e4567-e89b-12d3-a456-426614174000",
      "organisationName": "My Construction Company",
      "ownerId": "987fcdeb-51a2-43d1-9f12-123456789abc",
      "ownerUserName": "john.doe",
      "description": "Leading construction services provider",
      "active": true,
      "deleted": false,
      "createdAt": "2025-05-27T14:30:15.123456",
      "updatedAt": "2025-05-27T14:30:15.123456"
    }
  ]
}
```

#### Error Responses

* `401` - Unauthorized
* `404` - User not found

***

### Update Organisation

Updates an existing organisation owned by the authenticated user.

#### Endpoint

```http
PUT /api/v1/organisation/{id}
```

#### Path Parameters

* `id` (UUID): Organisation identifier

#### Request Body

```json
{
  "name": "Updated Company Name",
  "description": "Updated company description"
}
```

#### Update Rules

* Only provided fields are updated
* Empty or null values preserve existing data
* Only organisation owner can update
* Name must be unique per user if changed

#### Success Response

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Organisation updated successfully",
  "action_time": "2025-05-27T15:00:25.345678",
  "data": {
    "organisationId": "123e4567-e89b-12d3-a456-426614174000",
    "organisationName": "Updated Company Name",
    "ownerId": "987fcdeb-51a2-43d1-9f12-123456789abc",
    "ownerUserName": "john.doe",
    "description": "Updated company description",
    "active": true,
    "deleted": false,
    "createdAt": "2025-05-27T14:30:15.123456",
    "updatedAt": "2025-05-27T15:00:25.345678"
  }
}
```

#### Error Responses

* `404` - Organisation not found or not owned by user
* `400` - Organisation name already exists for user
* `401` - Unauthorized
* `422` - Validation errors