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": "+1234567890",
      "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": "+1234567890",
  "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": "+1987654321",
  "role": "SPECIALIST",
  "language": "en"
}

Example Response:

{
  "_id": "648f8f2e1234567890abcdef",
  "object": "MemberDto",
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "[email protected]",
  "phone": "+1987654321",
  "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": "+1555123456",
  "profileStatus": "active"
}

Example Response:

{
  "_id": "648f8f2e1234567890abcdef",
  "object": "MemberDto",
  "firstName": "Jane",
  "lastName": "Doe-Smith",
  "email": "[email protected]",
  "phone": "+1555123456",
  "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:

Self-deletion protection: Members cannot delete themselves
Active orders check: Cannot delete members with pending/active orders
Permission validation: Requires appropriate deletion permissions
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

Pagination: Always use pagination for member lists to avoid performance issues
Caching: Implement client-side caching with appropriate TTL
Error Handling: Handle all error responses gracefully
Rate Limiting: Respect rate limits and implement exponential backoff
Validation: Validate data on client side before API calls

Security Considerations

Token Management: Secure storage and rotation of authentication tokens
HTTPS Only: Always use HTTPS in production environments
Input Validation: Validate and sanitize all inputs
Tenant Isolation: Always include tenant ID header
Permission Checking: Verify user permissions before UI actions

Performance Optimization

Selective Loading: Only request needed fields using field selection
Batch Operations: Group related API calls when possible
Lazy Loading: Load member details on demand
Image Optimization: Compress avatar images before upload
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.

PreviousMember Management NextInterface Documentation

Last updated 6 months ago

hashtagOverview

hashtagBase URL

hashtagAuthentication

hashtagAPI Endpoints

hashtag1. Get Paginated Members

hashtag2. Get Member by ID

hashtag3. Create New Member

hashtag4. Update Member

hashtag5. Update Member Service Assignments

hashtag6. Delete Member

hashtagMember Media Management

hashtag7. Upload Member Avatar

hashtag8. Delete Member Avatar

hashtagData Transfer Objects

hashtagMemberDto

hashtagAssignmentsDto

hashtagMemberPaginationDto

hashtagEnumerations

hashtagRoleEnum

hashtagMemberProfileStatusEnum

hashtagLanguageCodeEnum

hashtagPermission Requirements

hashtagRequired Permissions

hashtagPermission Scopes

hashtagError Responses

hashtagStandard Error Format

hashtagCommon Error Responses

hashtag400 Bad Request

hashtag401 Unauthorized

hashtag403 Forbidden

hashtag404 Not Found

hashtag409 Conflict

hashtag422 Unprocessable Entity

hashtagMember-Specific Errors

hashtagMember Not Found

hashtagEmail Already Exists

hashtagCannot Delete Self

hashtagHas Active Orders

hashtagTariff Plan Limit Reached

hashtagRate Limiting

hashtagCaching

hashtagAPI Versioning

hashtagIntegration Examples

hashtagJavaScript/TypeScript Client

hashtagcURL Examples

hashtagBest Practices

hashtagAPI Usage Guidelines

hashtagSecurity Considerations

hashtagPerformance Optimization

Overview

Base URL

Authentication

API Endpoints

1. Get Paginated Members

2. Get Member by ID

3. Create New Member

4. Update Member

5. Update Member Service Assignments

6. Delete Member

Member Media Management

7. Upload Member Avatar

8. Delete Member Avatar

Data Transfer Objects

MemberDto

AssignmentsDto

MemberPaginationDto

Enumerations

RoleEnum

MemberProfileStatusEnum

LanguageCodeEnum

Permission Requirements

Required Permissions

Permission Scopes

Error Responses

Standard Error Format

Common Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

422 Unprocessable Entity

Member-Specific Errors

Member Not Found

Email Already Exists

Cannot Delete Self

Has Active Orders

Tariff Plan Limit Reached

Rate Limiting

Caching

API Versioning

Integration Examples

JavaScript/TypeScript Client

cURL Examples

Best Practices

API Usage Guidelines

Security Considerations

Performance Optimization