> 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/client-management.md). # Client Management ### Create Client Creates a new client within the specified organisation. The authenticated user must have OWNER or ADMIN role in the organisation. #### Endpoint ``` POST /api/v1/clients/organisation/{organisationId} ``` #### Path Parameters * `organisationId` (UUID) - The organisation identifier where the client will be created #### Request Body ```json { "name": "ABC Construction Ltd", "description": "Leading construction company specializing in residential buildings", "address": "123 Main Street, Downtown, City 12345", "officePhone": "+1-555-0123", "tin": "123456789", "email": "contact@abcconstruction.com" } ``` #### Validation Rules * `name`: Required, cannot be blank, must be unique within the organisation * `description`: Optional * `address`: Required, must be unique within the organisation * `officePhone`: Optional * `tin`: Required, must be unique within the organisation (Tax Identification Number) * `email`: Required, must be unique within the organisation, valid email format * The authenticated user must have the OWNER or ADMIN role in the organisation #### Success Response ```json { "success": true, "httpStatus": "OK", "message": "Client created successfully", "action_time": "2025-06-02T14:30:15.123456", "data": { "clientId": "456e7890-e12b-34c5-d678-901234567890", "name": "ABC Construction Ltd", "description": "Leading construction company specializing in residential buildings", "address": "123 Main Street, Downtown, City 12345", "officePhone": "+1-555-0123", "tin": "123456789", "email": "contact@abcconstruction.com", "isActive": true, "createdAt": "2025-06-02T14:30:15.123456", "updatedAt": "2025-06-02T14:30:15.123456", "totalProjects": 0 } } ``` #### Error Responses * **404** - Organisation not found, member not found in organisation, or insufficient permissions * **400** - Client with name/address/TIN/email already exists, missing required fields, or invalid data provided * **401** - Unauthorized (invalid token) * **500** - An unexpected error occurred while creating the client *** ### Get Client By ID Retrieves a client by its ID. The authenticated user must be an active member (OWNER, ADMIN, or MEMBER) of the organisation. #### Endpoint ``` GET /api/v1/clients/{clientId} ``` #### Path Parameters * `clientId` (UUID) - The client identifier #### Success Response ```json { "success": true, "httpStatus": "OK", "message": "Client retrieved successfully", "action_time": "2025-06-02T14:35:20.654321", "data": { "clientId": "456e7890-e12b-34c5-d678-901234567890", "name": "ABC Construction Ltd", "description": "Leading construction company specializing in residential buildings", "address": "123 Main Street, Downtown, City 12345", "officePhone": "+1-555-0123", "tin": "123456789", "email": "contact@abcconstruction.com", "isActive": true, "createdAt": "2025-06-02T14:30:15.123456", "updatedAt": "2025-06-02T14:30:15.123456", "totalProjects": 5 } } ``` #### Error Responses * **404** - Client not found, member not found in organisation, member not active, or insufficient permissions * **401** - Unauthorized ### Get All Clients in Organisation Retrieves all active clients within an organisation. The authenticated user must be an active member (OWNER, ADMIN, or MEMBER) of the organisation. #### Endpoint ``` GET /api/v1/clients/organisation/{organisationId} ``` #### Path Parameters * `organisationId` (UUID) - The organisation identifier #### Success Response ```json { "success": true, "httpStatus": "OK", "message": "Clients retrieved successfully", "action_time": "2025-06-02T15:15:45.234567", "data": [ { "clientId": "456e7890-e12b-34c5-d678-901234567890", "name": "ABC Construction Ltd", "description": "Leading construction company specializing in residential buildings", "address": "123 Main Street, Downtown, City 12345", "officePhone": "+1-555-0123", "tin": "123456789", "email": "contact@abcconstruction.com", "isActive": true, "createdAt": "2025-06-02T14:30:15.123456", "updatedAt": "2025-06-02T14:30:15.123456", "totalProjects": 5 }, { "clientId": "789f0123-e45b-67c8-d901-234567890123", "name": "XYZ Engineering Co", "description": "Structural engineering and design consultancy", "address": "456 Oak Avenue, Business District, City 54321", "officePhone": "+1-555-0456", "tin": "987654321", "email": "info@xyzengineering.com", "isActive": true, "createdAt": "2025-06-01T10:15:30.987654", "updatedAt": "2025-06-01T10:15:30.987654", "totalProjects": 3 } ] } ``` #### Error Responses * **404** - Organisation not found, member not found in organisation, member not active, or insufficient permissions * **401** - Unauthorized ### Update Client Updates an existing client's details. The authenticated user must have the OWNER or ADMIN role in the organisation. #### Endpoint ``` PUT /api/v1/clients/{clientId} ``` #### Path Parameters * `clientId` (UUID) - The client identifier to update #### Request Body ```json { "name": "ABC Construction Ltd - Updated", "description": "Updated description for the construction company", "address": "456 New Street, Updated Location, City 67890", "officePhone": "+1-555-9876", "tin": "987654321", "email": "updated@abcconstruction.com", "isActive": true } ``` #### Update Rules * Only the provided fields are updated * Empty or null values preserve existing data (except for name, which gets trimmed) * Only OWNER or ADMIN members can update clients * Name, address, TIN, and email must remain unique within the organisation if changed #### Success Response ```json { "success": true, "httpStatus": "OK", "message": "Client updated successfully", "action_time": "2025-06-02T15:00:25.345678", "data": { "clientId": "456e7890-e12b-34c5-d678-901234567890", "name": "ABC Construction Ltd - Updated", "description": "Updated description for the construction company", "address": "456 New Street, Updated Location, City 67890", "officePhone": "+1-555-9876", "tin": "987654321", "email": "updated@abcconstruction.com", "isActive": true, "createdAt": "2025-06-02T14:30:15.123456", "updatedAt": "2025-06-02T15:00:25.345678", "totalProjects": 5 } } ``` #### Error Responses * **404** - Client not found, member not found in organisation, member not active, or insufficient permissions * **400** - Duplicate name/address/TIN/email, invalid data provided * **401** - Unauthorized * **500** - An unexpected error occurred while updating the client ### Delete Client Soft deletes a client by marking it as inactive. The authenticated user must have OWNER or ADMIN role in the organisation. #### Endpoint ``` DELETE /api/v1/clients/{clientId} ``` #### Path Parameters * `clientId` (UUID) - The client identifier to delete #### Success Response ```json { "success": true, "httpStatus": "OK", "message": "Client deleted successfully", "action_time": "2025-06-02T15:10:30.789123", "data": null } ``` #### Error Responses * **404** - Client not found, member not found in organisation, member not active, or insufficient permissions * **401** - Unauthorized * **500** - Failed to delete client ### Get Client Projects Retrieves all projects associated with a specific client. The authenticated user must have OWNER or ADMIN role in the organisation. #### Endpoint ``` GET /api/v1/clients/{clientId}/projects ``` #### Path Parameters * `clientId` (UUID) - The client identifier #### Success Response ```json { "success": true, "httpStatus": "OK", "message": "Client projects retrieved successfully", "action_time": "2025-06-02T15:20:45.567890", "data": [ { "projectId": "123e4567-e89b-12d3-a456-426614174000", "projectCode": "PROJ0001" "name": "Residential Complex Phase 1", "description": "Construction of 50-unit residential complex", "budget": 2500000.00, "organisationName": "My Construction Company", "organisationId": "987fcdeb-51a2-43d1-9f12-123456789abc", "status": "ACTIVE", "contractNumber": "RES-2025-001", "createdAt": "2025-05-15T09:00:00.000000", "updatedAt": "2025-05-15T09:00:00.000000" }, { "projectId": "234f5678-f90c-23e4-b567-537725285111", "projectCode": "PROJ0008" "name": "Commercial Building Renovation", "description": "Complete renovation of 10-story commercial building", "budget": 1800000.00, "organisationName": "My Construction Company", "organisationId": "987fcdeb-51a2-43d1-9f12-123456789abc", "status": "ACTIVE", "contractNumber": "COM-2025-002", "createdAt": "2025-05-20T11:30:00.000000", "updatedAt": "2025-05-20T11:30:00.000000" } ] } ``` #### Error Responses * **404** - Client not found, member not found in organisation, member not active, or insufficient permissions * **401** - Unauthorized * **500** - An unexpected error occurred while retrieving client projects ### Authentication & Authorization #### General Rules * All endpoints require authentication via a JWT token * Users must be active members of the relevant organisation * Client creation, updates, and deletion require the OWNER or ADMIN role * Client viewing and listing require OWNER, ADMIN, or MEMBER role * Client project viewing requires OWNER or ADMIN role #### Role Permissions * **OWNER**: Full access to all client operations * **ADMIN**: Full access to all client operations * **MEMBER**: Can view clients and client details only #### Common Error Responses All endpoints may return: * **401 Unauthorized** - Invalid or missing authentication token * **500 Internal Server Error** - Unexpected server error ### Response Format All successful responses follow this structure: ```json { "success": true, "httpStatus": "OK", "message": "Description of the operation", "action_time": "2025-06-02T15:45:30.123456", "data": { /* Response data or null */ } } ``` ### Additional Notes #### Client Status * Clients have an `isActive` boolean field * Deleted clients are marked as `isActive: false` (soft delete) * Only active clients are returned in the "Get All Clients" endpoint #### Data Uniqueness Within each organisation, the following fields must be unique: * Client name (case-insensitive) * Client address (case-insensitive) * Client TIN (case-insensitive) * Client email (case-insensitive) #### Project Integration * Clients can have multiple projects associated with them * The `totalProjects` field in client responses shows the count of associated projects * Client projects can be retrieved using the dedicated endpoint #### Input Validation * Email addresses must be in valid format * TIN (Tax Identification Number) format validation may apply based on business requirements * Phone numbers accept various formats but should follow international standards