[PERS SDK - v2.3.26](/sdk-reference/readme) / [Exports](/sdk-reference/modules) / BusinessMembershipApi

# Class: BusinessMembershipApi

Business Membership API Client

Platform-agnostic API client for managing business memberships.
Handles user access to businesses with role-based permissions.

Base Path: /businesses/:businessId/members

Required Headers:

- Authorization: Bearer <business_jwt_token>
- X-Project-Key: <project_key>


**`Example`**

```typescript
const membershipApi = new BusinessMembershipApi(apiClient);

// List all members of a business
const members = await membershipApi.getMembers('business-123');

// Add a new member
const newMember = await membershipApi.addMember('business-123', {
  userId: 'user-456',
  role: MembershipRole.EDITOR
});
```

**`Version`**

2.0.0

## Table of contents

### Constructors

- [constructor](/sdk-reference/classes/businessmembershipapi#constructor)


### Methods

- [getMembers](/sdk-reference/classes/businessmembershipapi#getmembers)
- [addMember](/sdk-reference/classes/businessmembershipapi#addmember)
- [addMemberByUserId](/sdk-reference/classes/businessmembershipapi#addmemberbyuserid)
- [updateMemberRole](/sdk-reference/classes/businessmembershipapi#updatememberrole)
- [setMemberRole](/sdk-reference/classes/businessmembershipapi#setmemberrole)
- [removeMember](/sdk-reference/classes/businessmembershipapi#removemember)


## Constructors

### constructor

• **new BusinessMembershipApi**(`apiClient`): [`BusinessMembershipApi`](/sdk-reference/classes/businessmembershipapi)

#### Parameters

| Name | Type |
|  --- | --- |
| `apiClient` | [`PersApiClient`](/sdk-reference/classes/persapiclient) |


#### Returns

[`BusinessMembershipApi`](/sdk-reference/classes/businessmembershipapi)

#### Defined in

[business/api/business-membership-api.ts:58](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/business/api/business-membership-api.ts#L58)

## Methods

### getMembers

▸ **getMembers**(`businessId`, `options?`): `Promise`<`PaginatedResponseDTO`<`BusinessMembershipDTO`>>

List all members of a business with pagination

Endpoint: GET /businesses/:businessId/members
Min Role: VIEWER (any member can view)

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `businessId` | `string` | The business UUID |
| `options?` | [`GetBusinessMembersOptions`](/sdk-reference/interfaces/getbusinessmembersoptions) | Pagination, filter, and include options |


#### Returns

`Promise`<`PaginatedResponseDTO`<`BusinessMembershipDTO`>>

Paginated array of business memberships with user and role details

**`Throws`**

401 - Not authenticated

**`Throws`**

403 - businessId in path doesn't match JWT's business

**`Example`**

```typescript
// Get first page of members
const page1 = await membershipApi.getMembers('business-123');
page1.data.forEach(m => console.log(`${m.userId}: ${m.role}`));

// Include user data for display
const withUsers = await membershipApi.getMembers('business-123', { 
  include: ['user'],
  page: 1,
  limit: 50
});
withUsers.data.forEach(m => console.log(m.included?.user?.email));

// Filter by role with user data
const admins = await membershipApi.getMembers('business-123', { 
  role: MembershipRole.ADMIN,
  include: ['user']
});
```

#### Defined in

[business/api/business-membership-api.ts:112](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/business/api/business-membership-api.ts#L112)

### addMember

▸ **addMember**(`businessId`, `request`): `Promise`<`BusinessMembershipDTO`>

Add a member to a business

Endpoint: POST /businesses/:businessId/members
Min Role: ADMIN

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `businessId` | `string` | The business UUID |
| `request` | `AddBusinessMemberRequestDTO` | The add member request with userId and optional role |


#### Returns

`Promise`<`BusinessMembershipDTO`>

The created business membership

**`Throws`**

401 - Not authenticated

**`Throws`**

403 - Insufficient role (requires ADMIN or higher)

**`Throws`**

404 - User not found

**`Throws`**

409 - User is already a member

**`Example`**

```typescript
const newMember = await membershipApi.addMember('business-123', {
  userId: 'user-456',
  role: MembershipRole.EDITOR
});
```

#### Defined in

[business/api/business-membership-api.ts:160](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/business/api/business-membership-api.ts#L160)

### addMemberByUserId

▸ **addMemberByUserId**(`businessId`, `userId`, `role?`): `Promise`<`BusinessMembershipDTO`>

Add a member to a business with explicit parameters

Convenience method that constructs the request DTO internally.

#### Parameters

| Name | Type | Default value | Description |
|  --- | --- | --- | --- |
| `businessId` | `string` | `undefined` | The business UUID |
| `userId` | `string` | `undefined` | The user UUID to add |
| `role` | `MembershipRole` | `MembershipRole.VIEWER` | The role to assign (defaults to VIEWER) |


#### Returns

`Promise`<`BusinessMembershipDTO`>

The created business membership

**`Example`**

```typescript
const member = await membershipApi.addMemberByUserId(
  'business-123',
  'user-456',
  MembershipRole.EDITOR
);
```

#### Defined in

[business/api/business-membership-api.ts:189](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/business/api/business-membership-api.ts#L189)

### updateMemberRole

▸ **updateMemberRole**(`businessId`, `userId`, `request`): `Promise`<`BusinessMembershipDTO`>

Update a member's role in a business

Endpoint: PUT /businesses/:businessId/members/:userId
Min Role: ADMIN

Business Rules:

- Cannot demote the last OWNER (must transfer ownership first)
- Can only assign roles up to your own level (ADMIN cannot create OWNER)


#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `businessId` | `string` | The business UUID |
| `userId` | `string` | The user UUID to update |
| `request` | `BusinessMembershipUpdateRequestDTO` | The update request with new role |


#### Returns

`Promise`<`BusinessMembershipDTO`>

The updated business membership

**`Throws`**

401 - Not authenticated

**`Throws`**

403 - Insufficient role (requires ADMIN or higher)

**`Throws`**

404 - Membership not found

**`Throws`**

400 - Cannot demote last OWNER

**`Example`**

```typescript
const updated = await membershipApi.updateMemberRole(
  'business-123',
  'user-456',
  { role: MembershipRole.ADMIN }
);
```

#### Defined in

[business/api/business-membership-api.ts:230](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/business/api/business-membership-api.ts#L230)

### setMemberRole

▸ **setMemberRole**(`businessId`, `userId`, `role`): `Promise`<`BusinessMembershipDTO`>

Update a member's role with explicit parameters

Convenience method that constructs the request DTO internally.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `businessId` | `string` | The business UUID |
| `userId` | `string` | The user UUID to update |
| `role` | `MembershipRole` | The new role to assign |


#### Returns

`Promise`<`BusinessMembershipDTO`>

The updated business membership

**`Example`**

```typescript
const updated = await membershipApi.setMemberRole(
  'business-123',
  'user-456',
  MembershipRole.ADMIN
);
```

#### Defined in

[business/api/business-membership-api.ts:260](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/business/api/business-membership-api.ts#L260)

### removeMember

▸ **removeMember**(`businessId`, `userId`): `Promise`<{ `success`: `boolean`  }>

Remove a member from a business

Endpoint: DELETE /businesses/:businessId/members/:userId
Min Role: ADMIN

Business Rules:

- Cannot remove the last OWNER
- Cannot remove yourself (use leave endpoint or transfer ownership)


#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `businessId` | `string` | The business UUID |
| `userId` | `string` | The user UUID to remove |


#### Returns

`Promise`<{ `success`: `boolean`  }>

Success confirmation

**`Throws`**

401 - Not authenticated

**`Throws`**

403 - Insufficient role (requires ADMIN or higher)

**`Throws`**

404 - Membership not found

**`Throws`**

400 - Cannot remove last OWNER

**`Example`**

```typescript
const result = await membershipApi.removeMember('business-123', 'user-456');
if (result.success) {
  console.log('Member removed successfully');
}
```

#### Defined in

[business/api/business-membership-api.ts:299](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/business/api/business-membership-api.ts#L299)