> 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/organization-members-management.md).

# Organization Members Management

Base URL: `/api/v1/`

*Note: All endpoints on this page require authentication.*

***

### Get My Organisations

Retrieves all organisations that the authenticated user belongs to (either as owner or member).

**GET** `/api/v1/my/organisations`

#### Success Response

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Your organisations retrieved successfully",
  "action_time": "2025-05-28T17:54:31.5467617",
  "data": {
    "userName": "richardhendricks",
    "totalOrganisations": 3,
    "ownedOrganisations": 2,
    "memberOrganisations": 1,
    "organisations": [
      {
        "organisationId": "cf4f9af5-ba82-459b-839d-2c4f7c103d96",
        "organisationName": "Pied Piper",
        "organisationDescription": "Revolutionary data compression technology making the world a better place",
        "myRole": "OWNER",
        "myStatus": "ACTIVE",
        "joinedAt": "2025-05-28T11:23:19.56042",
        "canManageMembers": true,
        "canInviteMembers": true,
        "totalMembers": 5,
        "totalPendingInvitations": 2,
        "ownerUserName": "richardhendricks",
        "owner": true,
        "admin": false
      },
      {
        "organisationId": "164b6742-951e-47f0-b282-2450246fa1f1",
        "organisationName": "Hooli",
        "organisationDescription": "Making the world a better place through minimal message-oriented transport layers",
        "myRole": "MEMBER",
        "myStatus": "ACTIVE",
        "joinedAt": "2025-05-28T12:27:58.490997",
        "canManageMembers": false,
        "canInviteMembers": false,
        "totalMembers": 847,
        "totalPendingInvitations": 12,
        "ownerUserName": "gavinnelson",
        "owner": false,
        "admin": false
      },
      {
        "organisationId": "a8b9c3d4-e5f6-7890-abcd-ef1234567890",
        "organisationName": "Aviato",
        "organisationDescription": "My aviato? Nah bro, Aviato. My Aviato.",
        "myRole": "OWNER",
        "myStatus": "ACTIVE",
        "joinedAt": "2025-05-28T14:15:32.123456",
        "canManageMembers": true,
        "canInviteMembers": true,
        "totalMembers": 1,
        "totalPendingInvitations": 0,
        "ownerUserName": "erlichtbachman",
        "owner": true,
        "admin": false
      }
    ]
  }
}
```

#### Error Responses

* **401**: Authentication required
* **500**: Failed to retrieve organisations

***

### Invite Member

Sends an invitation to a user to join the organisation.

**POST** `/api/v1/organisation/{orgId}/members/invite`

#### Request Body

```json
{
  "email": "dineshchugtai@gmail.com",
  "role": "MEMBER"
}
```

#### Validation Rules

* **email**: Must be a valid email format and not blank
* **role**: Must be either "ADMIN" or "MEMBER"

#### Success Response

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Invitation sent successfully to dineshchugtai@gmail.com",
  "action_time": "2025-05-28T12:29:15.8747368",
  "data": null
}
```

#### Error Responses

* **400**: Invalid Email Format, User Already Member
* **401**: Authentication failed
* **403**: Insufficient Permissions
* **404**: Organisation Not Found
* **500**: Internal Server Error

***

### Get All Members in Organisation

Retrieves a complete overview of all organisation members and pending invitations.

**GET** `/api/v1/organisation/{orgId}/members`

#### Success Response

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Organisation members and invitations retrieved successfully",
  "action_time": "2025-05-28T19:12:16.005208312",
  "data": {
    "organisationName": "Pied Piper",
    "totalMembers": 4,
    "totalPendingInvitations": 1,
    "totalActiveMembers": 4,
    "totalSuspendedMembers": 0,
    "members": [
      {
        "memberId": "418bd377-6acf-407d-97a2-5191f965df5c",
        "userName": "dineshchugtai",
        "email": "dineshchugtai@gmail.com",
        "role": "MEMBER",
        "status": "ACTIVE",
        "joinedAt": "2025-05-28T19:09:56.421755",
        "invitedByUserName": "richardhendricks",
        "canManageMembers": false,
        "admin": false,
        "owner": false
      },
      {
        "memberId": "d474db78-4d64-447b-a668-e6b0ae011f3c",
        "userName": "richardhendricks",
        "email": "richardhendricks@gmail.com",
        "role": "OWNER",
        "status": "ACTIVE",
        "joinedAt": "2025-05-28T18:50:07.801545",
        "invitedByUserName": "richardhendricks",
        "canManageMembers": true,
        "admin": false,
        "owner": true
      },
      {
        "memberId": "e585ec89-5e75-558c-b779-f7c1bf122e4d",
        "userName": "gilfoyle",
        "email": "gilfoyle@gmail.com",
        "role": "MEMBER",
        "status": "ACTIVE",
        "joinedAt": "2025-05-28T20:15:32.987654",
        "invitedByUserName": "richardhendricks",
        "canManageMembers": false,
        "admin": false,
        "owner": false
      },
      {
        "memberId": "f696fd9a-6f86-669d-c88a-g8d2cg233f5e",
        "userName": "jareddunn",
        "email": "jareddunn@gmail.com",
        "role": "ADMIN",
        "status": "ACTIVE",
        "joinedAt": "2025-05-28T21:30:45.123789",
        "invitedByUserName": "richardhendricks",
        "canManageMembers": true,
        "admin": true,
        "owner": false
      }
    ],
    "pendingInvitations": [
      {
        "invitationId": "456e7890-e89b-12d3-a456-426614174002",
        "email": "bighead@gmail.com",
        "role": "MEMBER",
        "status": "PENDING",
        "invitedAt": "2025-05-28T14:30:00Z",
        "expiresAt": "2025-06-04T14:30:00Z",
        "invitedByUserName": "richardhendricks",
        "isExpired": false,
        "canResend": true,
        "canRevoke": true
      }
    ],
    "declinedInvitations": []
  }
}
```

#### Error Responses

* **400**: Invalid Organization ID
* **401**: Authentication failed
* **403**: Not a member
* **404**: Organization not found
* **500**: Failed to retrieve organisation member

***

### Get Active Members

Retrieves only the active members of the organisation.

**GET** `/api/v1/organisation/{orgId}/members/active`

#### Success Response

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Active members retrieved successfully",
  "action_time": "2025-05-28T22:20:15.772467771",
  "data": [
    {
      "memberId": "418bd377-6acf-407d-97a2-5191f965df5c",
      "userName": "dineschchugtai",
      "email": "dineschchugtai@gmail.com",
      "role": "MEMBER",
      "status": "ACTIVE",
      "joinedAt": "2025-05-28T19:09:56.421755",
      "invitedByUserName": "richardhendricks",
      "canManageMembers": false,
      "admin": false,
      "owner": false
    },
    {
      "memberId": "d474db78-4d64-447b-a668-e6b0ae011f3c",
      "userName": "richardhendricks",
      "email": "richardhendricks@gmail.com",
      "role": "OWNER",
      "status": "ACTIVE",
      "joinedAt": "2025-05-28T18:50:07.801545",
      "invitedByUserName": "richardhendricks",
      "canManageMembers": true,
      "admin": false,
      "owner": true
    },
    {
      "memberId": "e585ec89-5e75-558c-b779-f7c1bf122e4d",
      "userName": "gilfoyle",
      "email": "gilfoyle@gmail.com",
      "role": "MEMBER",
      "status": "ACTIVE",
      "joinedAt": "2025-05-28T20:15:32.987654",
      "invitedByUserName": "richardhendricks",
      "canManageMembers": false,
      "admin": false,
      "owner": false
    },
    {
      "memberId": "f696fd9a-6f86-669d-c88a-g8d2cg233f5e",
      "userName": "jareddunn",
      "email": "jareddunn@gmail.com",
      "role": "ADMIN",
      "status": "ACTIVE",
      "joinedAt": "2025-05-28T21:30:45.123789",
      "invitedByUserName": "richardhendricks",
      "canManageMembers": true,
      "admin": true,
      "owner": false
    }
  ]
}
```

#### Error Responses

* **400**: Invalid Organisation ID
* **401**: Authentication required
* **403**: Not a Member
* **404**: Organisation not found

***

### Get Pending Invitations

Retrieves all pending invitations for the organisation.

**GET** `/api/v1/organisation/{orgId}/members/invitations/pending`

#### Success Response

**If there are no pending invitations:**

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Pending invitations retrieved successfully",
  "action_time": "2025-05-28T22:27:02.810745939",
  "data": []
}
```

**If there are pending invitations:**

```json
{
  "success": true,
  "message": "Pending invitations retrieved successfully",
  "data": [
    {
      "invitationId": "456e7890-e89b-12d3-a456-426614174002",
      "email": "bighead@gmail.com",
      "role": "MEMBER",
      "status": "PENDING",
      "invitedAt": "2025-05-28T14:30:00Z",
      "expiresAt": "2025-06-04T14:30:00Z",
      "invitedByUserName": "richardhendricks",
      "isExpired": false,
      "canResend": true,
      "canRevoke": true
    },
    {
      "invitationId": "789e0123-e89b-12d3-a456-426614174004",
      "email": "monicahall@gmail.com",
      "role": "ADMIN",
      "status": "PENDING",
      "invitedAt": "2025-05-28T11:15:00Z",
      "expiresAt": "2025-06-04T11:15:00Z",
      "invitedByUserName": "richardhendricks",
      "isExpired": false,
      "canResend": true,
      "canRevoke": true
    }
  ],
  "timestamp": "2025-05-28T15:30:00Z"
}
```

#### Error Responses

* **400**: Invalid Organisation ID
* **401**: Authentication Required
* **403**: Insufficient Permission to view the invitations for the organisation
* **404**: Organisation not found
* **500**: Failed to retrieve the pending and accepted invitations

***

### Remove Member

Removes a member from the organisation (This endpoint should not be used for now).

**DELETE** `/api/v1/organisation/{orgId}/members/{memberId}`

#### Success Response

```json
{
  "success": true,
  "message": "Member removed successfully",
  "data": null,
  "timestamp": "2025-05-28T10:30:00Z"
}
```

#### Error Responses

* **400**: Invalid UUID Format, and cannot remove the owner
* **401**: Authentication required
* **403**: Insufficient Permission to remove the user
* **404**: Organisation not found or member not found
* **500**: Failed to remove the member due to internal error