API Documentation

Overview

The Member Management API provides comprehensive team member management capabilities for the Bee O'clock platform. This API handles member registration, profile management, role assignments, service assignments, and team administration within business contexts.

Base URL

{baseUrl}/api/v1/member

Authentication

All endpoints require authentication via:

• Bearer Token: Firebase JWT token in Authorization header

• Business Tenant ID: Required in x-business-tenant-id header for tenant isolation

API Endpoints

1. Get Paginated Members

Endpoint: GET /member/paged

Description: Retrieves a paginated list of team members with search and filtering capabilities.

Request Parameters:

interface MemberPaginationDto {
  page?: number;           // Page number (default: 1)
  pageSize?: number;       // Items per page (default: 10, max: 100)
  search?: string;         // Search term for name/email
  role?: RoleEnum;         // Filter by member role
  profileStatus?: MemberProfileStatusEnum; // Filter by profile status
  sortBy?: string;         // Sort field (default: 'createdAt')
  sortDirection?: 'asc' | 'desc'; // Sort direction (default: 'desc')
}

Query Parameters:

• page (optional): Page number starting from 1

• pageSize (optional): Number of items per page (1-100)

• search (optional): Search in firstName, lastName, email

• role (optional): Filter by role (ADMIN, SPECIALIST, RECEPTION)

• profileStatus (optional): Filter by status (active, inactive, pending)

• sortBy (optional): Field to sort by

• sortDirection (optional): Sort direction

Response:

{
  items: MemberDto[];
  pagination: {
    page: number;
    pageSize: number;
    total: number;
    totalPages: number;
    hasNextPage: boolean;
    hasPreviousPage: boolean;
  }
}

Example Request:

GET /api/v1/member/paged?page=1&pageSize=20&search=john&role=SPECIALIST&profileStatus=active
Authorization: Bearer <firebase-jwt>
x-business-tenant-id: <tenant-id>

Example Response:

{
  "items": [
    {
      "_id": "648f8f2e1234567890abcdef",
      "object": "MemberDto",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "[phone]",
      "role": "SPECIALIST",
      "profileStatus": "active",
      "assignments": {
        "service": {
          "full": false,
          "include": [
            {
              "service": "service-id-123",
              "serviceId": "service-123"
            }
          ]
        }
      },
      "createdAt": "2023-06-18T10:30:00.000Z",
      "updatedAt": "2023-06-18T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
  }
}

---

2. Get Member by ID

Endpoint: GET /member/:id

Description: Retrieves detailed information for a specific team member.

Path Parameters:

• id (required): Member ID (ObjectId format)

Response:

MemberDto

Example Request:

GET /api/v1/member/648f8f2e1234567890abcdef
Authorization: Bearer <firebase-jwt>
x-business-tenant-id: <tenant-id>

Example Response:

{
  "_id": "648f8f2e1234567890abcdef",
  "object": "MemberDto",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "phone": "[phone]",
  "avatar": {
    "_id": "avatar-id-123",
    "uri": "https://storage.example.com/avatar.jpg",
    "mediaType": "IMAGE"
  },
  "role": "SPECIALIST",
  "roles": [
    {
      "_id": "role-id-123",
      "name": "Service Provider",
      "permissions": ["READ_SERVICE", "UPDATE_SERVICE"]
    }
  ],
  "profileStatus": "active",
  "language": "en",
  "assignments": {
    "service": {
      "full": false,
      "include": [
        {
          "service": "service-id-123",
          "serviceId": "service-123"
        }
      ]
    }
  },
  "referal": {
    "code": "REF123",
    "source": "website"
  },
  "createdAt": "2023-06-18T10:30:00.000Z",
  "updatedAt": "2023-06-18T15:45:00.000Z"
}

---

3. Create New Member

Endpoint: POST /member

Description: Creates a new team member and sends invitation.

Request Body:

interface MemberDto {
  firstName?: string;
  lastName?: string;
  email: string;          // Required - unique within business
  phone?: string;
  role?: RoleEnum;        // Default: SPECIALIST
  profileStatus?: MemberProfileStatusEnum; // Default: active
  assignments?: AssignmentsDto;
  language?: LanguageCodeEnum; // Default: en
  referal?: ReferalDto;
}

Response:

MemberDto // Created member details

Validation Rules:

• email: Required, valid email format, unique within business

• firstName or lastName: At least one is recommended

• role: Must be valid role enum value

• phone: Valid phone format if provided

Example Request:

POST /api/v1/member
Authorization: Bearer <firebase-jwt>
x-business-tenant-id: <tenant-id>
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "[email protected]",
  "phone": "[phone]",
  "role": "SPECIALIST",
  "language": "en"
}

Example Response:

{
  "_id": "648f8f2e1234567890abcdef",
  "object": "MemberDto",
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "[email protected]",
  "phone": "[phone]",
  "role": "SPECIALIST",
  "profileStatus": "active",
  "language": "en",
  "assignments": {
    "service": {
      "full": false,
      "include": []
    }
  },
  "createdAt": "2023-06-18T10:30:00.000Z",
  "updatedAt": "2023-06-18T10:30:00.000Z"
}

---

4. Update Member

Endpoint: PUT /member/:memberId

Description: Updates an existing team member's information.

Path Parameters:

• memberId (required): Member ID to update

Request Body:

interface MemberDto {
  firstName?: string;
  lastName?: string;
  email?: string;         // Must be unique if changed
  phone?: string;
  role?: RoleEnum;
  profileStatus?: MemberProfileStatusEnum;
  language?: LanguageCodeEnum;
  referal?: ReferalDto;
}

Response:

MemberDto // Updated member details

Business Rules:

• Email must remain unique within business if changed

• Role changes require appropriate permissions

• Cannot update email to existing member's email

• Profile status changes affect member access

Example Request:

PUT /api/v1/member/648f8f2e1234567890abcdef
Authorization: Bearer <firebase-jwt>
x-business-tenant-id: <tenant-id>
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Doe-Smith",
  "phone": "[phone]",
  "profileStatus": "active"
}

Example Response:

{
  "_id": "648f8f2e1234567890abcdef",
  "object": "MemberDto",
  "firstName": "Jane",
  "lastName": "Doe-Smith",
  "email": "[email protected]",
  "phone": "[phone]",
  "role": "SPECIALIST",
  "profileStatus": "active",
  "language": "en",
  "updatedAt": "2023-06-18T16:20:00.000Z"
}

---

5. Update Member Service Assignments

Endpoint: PATCH /member/:memberId/assignments

Description: Updates service assignments for a team member.

Path Parameters:

• memberId (required): Member ID to update assignments

Request Body:

interface AssignmentsDto {
  service: {
    full: boolean;        // If true, member can handle all services
    include?: AssignedServiceDto[]; // Specific services if full=false
  }
}

interface AssignedServiceDto {
  service?: string;       // Service ObjectId reference
  serviceId?: string;     // Service identifier
}

Response:

MemberDto // Updated member with new assignments

Assignment Rules:

• full: true: Member can provide all business services

• full: false: Member can only provide services in include array

• Empty include array with full: false means no service assignments

• Service references must exist and belong to the business

Example Request:

PATCH /api/v1/member/648f8f2e1234567890abcdef/assignments
Authorization: Bearer <firebase-jwt>
x-business-tenant-id: <tenant-id>
Content-Type: application/json

{
  "service": {
    "full": false,
    "include": [
      {
        "service": "648f8f2e1234567890service1",
        "serviceId": "haircut-basic"
      },
      {
        "service": "648f8f2e1234567890service2",
        "serviceId": "haircut-premium"
      }
    ]
  }
}

Example Response:

{
  "_id": "648f8f2e1234567890abcdef",
  "object": "MemberDto",
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "[email protected]",
  "role": "SPECIALIST",
  "assignments": {
    "service": {
      "full": false,
      "include": [
        {
          "service": "648f8f2e1234567890service1",
          "serviceId": "haircut-basic"
        },
        {
          "service": "648f8f2e1234567890service2",
          "serviceId": "haircut-premium"
        }
      ]
    }
  },
  "updatedAt": "2023-06-18T16:45:00.000Z"
}

---

6. Delete Member

Endpoint: DELETE /member/:memberId

Description: Soft deletes a team member (marks as deleted while preserving data).

Path Parameters:

• memberId (required): Member ID to delete

Response:

void // No content (204 status)

Business Rules:

• Performs soft delete (preserves historical data)

• Member cannot delete themselves

• Requires DELETE_MEMBER permission

• Checks for active orders before deletion

• Maintains audit trail of deletion

Deletion Validations:

1. Self-deletion protection: Members cannot delete themselves

2. Active orders check: Cannot delete members with pending/active orders

3. Permission validation: Requires appropriate deletion permissions

4. Role validation: May have restrictions based on member role

Example Request:

DELETE /api/v1/member/648f8f2e1234567890abcdef
Authorization: Bearer <firebase-jwt>
x-business-tenant-id: <tenant-id>

Example Response:

HTTP 204 No Content

---

Member Media Management

7. Upload Member Avatar

Endpoint: POST /member-media/:memberId/avatar

Description: Uploads or updates a member's profile avatar image.

Path Parameters:

• memberId (required): Member ID for avatar upload

Request Body:

FormData {
  file: File; // Image file (JPG, PNG, WebP)
}

Response:

{
  avatarId: string;     // Media ID of uploaded avatar
  avatarUrl: string;    // Public URL of avatar image
}

File Requirements:

• Formats: JPG, JPEG, PNG, WebP

• Size: Maximum 5MB

• Dimensions: Recommended 400x400px (will be auto-resized)

Example Request:

POST /api/v1/member-media/648f8f2e1234567890abcdef/avatar
Authorization: Bearer <firebase-jwt>
x-business-tenant-id: <tenant-id>
Content-Type: multipart/form-data

FormData:
  file: [image file]

Example Response:

{
  "avatarId": "648f8f2e1234567890media123",
  "avatarUrl": "https://storage.example.com/avatars/member-avatar-123.jpg"
}

---

8. Delete Member Avatar

Endpoint: DELETE /member-media/:memberId/avatar

Description: Removes a member's profile avatar image.

Path Parameters:

• memberId (required): Member ID for avatar deletion

Response:

void // No content (204 status)

Example Request:

DELETE /api/v1/member-media/648f8f2e1234567890abcdef/avatar
Authorization: Bearer <firebase-jwt>
x-business-tenant-id: <tenant-id>

Example Response:

HTTP 204 No Content

---

Data Transfer Objects

MemberDto

interface MemberDto {
  _id?: string;
  object?: 'MemberDto';
  firstName?: string;
  lastName?: string;
  email: string;                    // Required, unique within business
  phone?: string;
  avatar?: MediaDto;
  role?: RoleEnum;                  // Default: SPECIALIST
  roles?: RoleDto[];                // Advanced role system
  profileStatus?: MemberProfileStatusEnum; // Default: active
  assignments?: AssignmentsDto;
  language?: LanguageCodeEnum;      // Default: en
  referal?: ReferalDto;
  createdAt?: string;               // ISO date string
  updatedAt?: string;               // ISO date string
}

AssignmentsDto

interface AssignmentsDto {
  service: {
    full: boolean;                  // Can handle all services
    include?: AssignedServiceDto[]; // Specific service assignments
  }
}

interface AssignedServiceDto {
  service?: string;                 // Service ObjectId reference
  serviceId?: string;               // Service identifier
}

MemberPaginationDto

interface MemberPaginationDto {
  page?: number;                    // Page number (default: 1)
  pageSize?: number;                // Items per page (default: 10)
  search?: string;                  // Search term
  role?: RoleEnum;                  // Role filter
  profileStatus?: MemberProfileStatusEnum; // Status filter
  sortBy?: string;                  // Sort field
  sortDirection?: 'asc' | 'desc';   // Sort direction
}

Enumerations

RoleEnum

enum RoleEnum {
  ADMIN = 'ADMIN',                  // Full business administration
  SPECIALIST = 'SPECIALIST',        // Service provider
  RECEPTION = 'RECEPTION'           // Front desk operations
}

MemberProfileStatusEnum

enum MemberProfileStatusEnum {
  active = 'active',                // Active and available
  inactive = 'inactive',            // Temporarily inactive
  pending = 'pending'               // Awaiting activation
}

LanguageCodeEnum

enum LanguageCodeEnum {
  en = 'en',                        // English
  es = 'es',                        // Spanish
  fr = 'fr',                        // French
  de = 'de',                        // German
  it = 'it',                        // Italian
  pt = 'pt',                        // Portuguese
  // Additional languages supported
}

Permission Requirements

All member management endpoints require appropriate permissions:

Required Permissions

Operation	Permission	Description
Get Members	READ_MEMBER	View member information
Create Member	CREATE_MEMBER	Add new team members
Update Member	EDIT_MEMBER	Modify member details
Delete Member	DELETE_MEMBER	Remove team members
Manage Assignments	ASSIGN_SERVICES	Update service assignments
Upload Avatar	EDIT_MEMBER	Manage member media

Permission Scopes

• OWN: Can only access own member data

• ANY: Can access all members within the business

• ADMIN: Full administrative access

Error Responses

Standard Error Format

interface ApiError {
  statusCode: number;
  message: string;
  error: string;
  timestamp: string;
  path: string;
}

Common Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "Validation failed: Email is required",
  "error": "Bad Request",
  "timestamp": "2023-06-18T10:30:00.000Z",
  "path": "/api/v1/member"
}

401 Unauthorized

{
  "statusCode": 401,
  "message": "Invalid or missing authentication token",
  "error": "Unauthorized",
  "timestamp": "2023-06-18T10:30:00.000Z",
  "path": "/api/v1/member"
}

403 Forbidden

{
  "statusCode": 403,
  "message": "Insufficient permissions for this operation",
  "error": "Forbidden",
  "timestamp": "2023-06-18T10:30:00.000Z",
  "path": "/api/v1/member"
}

404 Not Found

{
  "statusCode": 404,
  "message": "Member not found",
  "error": "Not Found",
  "timestamp": "2023-06-18T10:30:00.000Z",
  "path": "/api/v1/member/invalid-id"
}

409 Conflict

{
  "statusCode": 409,
  "message": "Email already exists in this business",
  "error": "Conflict",
  "timestamp": "2023-06-18T10:30:00.000Z",
  "path": "/api/v1/member"
}

422 Unprocessable Entity

{
  "statusCode": 422,
  "message": "Cannot delete member with active orders",
  "error": "Unprocessable Entity",
  "timestamp": "2023-06-18T10:30:00.000Z",
  "path": "/api/v1/member/648f8f2e1234567890abcdef"
}

Member-Specific Errors

Member Not Found

{
  "statusCode": 404,
  "message": "Member not found: 648f8f2e1234567890abcdef",
  "error": "MemberNotFoundException"
}

Email Already Exists

{
  "statusCode": 409,
  "message": "Member with email '[email protected]' already exists",
  "error": "MemberEmailExistsException"
}

Cannot Delete Self

{
  "statusCode": 422,
  "message": "Members cannot delete themselves",
  "error": "MemberCannotDeleteItselfException"
}

Has Active Orders

{
  "statusCode": 422,
  "message": "Cannot delete member with active orders or appointments",
  "error": "MemberHasActiveEventsException"
}

Tariff Plan Limit Reached

{
  "statusCode": 422,
  "message": "Maximum number of team members reached for current plan",
  "error": "TenantTariffPlanMaxMembersReachedException"
}

Rate Limiting

API endpoints are rate-limited to prevent abuse:

• General endpoints: 100 requests per minute per IP

• File upload endpoints: 10 requests per minute per user

• Bulk operations: 5 requests per minute per user

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1623456789

Caching

Member data is cached for performance optimization:

• Member details: Cached for 5 minutes

• Member lists: Cached for 1 minute

• Search results: Cached for 3 minutes

Cache headers indicate freshness:

Cache-Control: public, max-age=300
ETag: "member-12345-v2"
Last-Modified: Wed, 18 Jun 2023 10:30:00 GMT

API Versioning

The API uses URL-based versioning:

• Current version: /api/v1/

• Version format: v{major}

• Backward compatibility maintained within major versions

Integration Examples

JavaScript/TypeScript Client

class MemberApiClient {
  constructor(private baseUrl: string, private token: string, private tenantId: string) {}

  async getMembers(params?: MemberPaginationDto): Promise<PaginationResponseDto<MemberDto>> {
    const queryString = new URLSearchParams(params as any).toString();
    const response = await fetch(`${this.baseUrl}/api/v1/member/paged?${queryString}`, {
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'x-business-tenant-id': this.tenantId
      }
    });
    return response.json();
  }

  async createMember(member: Partial<MemberDto>): Promise<MemberDto> {
    const response = await fetch(`${this.baseUrl}/api/v1/member`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'x-business-tenant-id': this.tenantId,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(member)
    });
    return response.json();
  }
}

cURL Examples

# Get paginated members
curl -X GET \
  "${API_BASE_URL}/api/v1/member/paged?page=1&pageSize=10" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-business-tenant-id: ${TENANT_ID}"

# Create new member
curl -X POST \
  "${API_BASE_URL}/api/v1/member" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-business-tenant-id: ${TENANT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "role": "SPECIALIST"
  }'

# Update member assignments
curl -X PATCH \
  "${API_BASE_URL}/api/v1/member/${MEMBER_ID}/assignments" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-business-tenant-id: ${TENANT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "service": {
      "full": false,
      "include": [
        {"serviceId": "haircut-basic"},
        {"serviceId": "haircut-premium"}
      ]
    }
  }'

Best Practices

API Usage Guidelines

1. Pagination: Always use pagination for member lists to avoid performance issues

2. Caching: Implement client-side caching with appropriate TTL

3. Error Handling: Handle all error responses gracefully

4. Rate Limiting: Respect rate limits and implement exponential backoff

5. Validation: Validate data on client side before API calls

Security Considerations

1. Token Management: Secure storage and rotation of authentication tokens

2. HTTPS Only: Always use HTTPS in production environments

3. Input Validation: Validate and sanitize all inputs

4. Tenant Isolation: Always include tenant ID header

5. Permission Checking: Verify user permissions before UI actions

Performance Optimization

1. Selective Loading: Only request needed fields using field selection

2. Batch Operations: Group related API calls when possible

3. Lazy Loading: Load member details on demand

4. Image Optimization: Compress avatar images before upload

5. Connection Pooling: Reuse HTTP connections for multiple requests

---

For additional information about member management workflows and business logic, see the Use Case Documentation and Interface Documentation.