SERVICE_PROFESSIONALS_API_QUICK_REF.md

Service Professionals API - Quick Reference

Overview

API for service professionals to view and update their own profile. Authentication via JWT token with staff_id. Admin operations (create/delete/list) are handled separately.

Base URL

/service-professionals

Authentication

All endpoints require JWT authentication with partner_id in the token payload (which contains the staff_id for service professionals).

Header:

Authorization: Bearer <jwt_token>

Available Endpoints

1. Get My Profile

GET /service-professionals/me

Retrieves the authenticated service professional's profile based on staff_id from JWT token.

Authentication: Required (JWT with staff_id)

Response: 200 OK

{
  "staff_id": "550e8400-e29b-41d4-a716-446655440001",
  "staff_code": "SP001",
  "name": "Priya Sharma",
  "designation": "Senior Beautician",
  "role": "beautician",
  "phone": "+919876543210",
  "email": "priya.sharma@example.com",
  "status": "active",
  "category": "beauty",
  "skills": ["facial", "makeup", "hair_styling"],
  "working_hours": [...],
  "photo_url": "https://example.com/photo.jpg",
  "address": {
    "street": "123 Main St",
    "city": "Mumbai",
    "state": "Maharashtra",
    "postal_code": "400001",
    "country": "India"
  },
  "notes": "Specialist in bridal makeup",
  "is_deleted": false,
  "meta": {...}
}

---

2. Update My Profile

PUT /service-professionals/me

Updates the authenticated service professional's profile. Staff ID is extracted from JWT token.

Authentication: Required (JWT with staff_id)

Supports updating:

• Basic info (name, designation, role, phone, email)
• Status and category
• Skills and working hours
• Address (add new or change existing)
• Photo URL and notes

Request Body (all fields optional):

{
  "email": "priya.new@example.com",
  "status": "on_leave",
  "address": {
    "street": "456 New Street",
    "city": "Delhi"
  },
  "notes": "Updated notes"
}

Response: 200 OK

{
  "staff_id": "550e8400-e29b-41d4-a716-446655440001",
  "staff_code": "SP001",
  "name": "Priya Sharma",
  "email": "priya.new@example.com",
  "status": "on_leave",
  "address": {
    "street": "456 New Street",
    "city": "Delhi",
    "state": "Maharashtra",
    "postal_code": "400001",
    "country": "India"
  },
  ...
}

---

Admin-Only Operations

The following operations are restricted to admin users and are not available through this API:

• Create Service Professional - Handled by admin interface
• Delete Service Professional - Handled by admin interface
• List Service Professionals - Handled by admin interface

---

Field Definitions

Updatable Fields (PUT endpoint)

• staff_code: Unique staff code (1-20 chars)
• name: Full name (1-100 chars)
• designation: Job designation (1-100 chars)
• role: Role category (1-50 chars)
• phone: Contact phone (10-20 chars, unique)
• email: Email address (valid email format)
• status: Status
• category: Service category
• skills: Array of skill strings
• working_hours: Array of schedule objects
• photo_url: Profile photo URL
• address: Address object with street, city, state, postal_code, country
• notes: Additional notes (max 500 chars)

Valid Status Values

• active
• inactive
• on_leave
• suspended
• terminated

Valid Category Values

• beauty
• spa
• salon
• fitness
• wellness

---

Projection List Support

The /list endpoint supports projection to reduce payload size:

Without projection (returns full objects):

{
  "filters": {"status": "active"},
  "skip": 0,
  "limit": 10
}

With projection (returns only specified fields):

{
  "filters": {"status": "active"},
  "skip": 0,
  "limit": 10,
  "projection_list": ["staff_id", "name", "phone"]
}

Benefits:

• 50-90% payload reduction
• Better performance
• Less network bandwidth

---

Error Responses

400 Bad Request

{
  "detail": "Staff code SP001 already exists"
}

404 Not Found

{
  "detail": "Service professional 550e8400-e29b-41d4-a716-446655440001 not found"
}

500 Internal Server Error

{
  "detail": "Failed to create service professional"
}

---

MongoDB Collection

• Collection: spa_service_professionals
• Indexes: staff_code, phone, is_deleted

---

Example Use Cases

1. Add New Address

PUT /service-professionals/{staff_id}
{
  "address": {
    "street": "789 Park Avenue",
    "city": "Bangalore",
    "state": "Karnataka",
    "postal_code": "560001",
    "country": "India"
  }
}

2. Change Email

PUT /service-professionals/{staff_id}
{
  "email": "new.email@example.com"
}

3. Update Status to On Leave

PUT /service-professionals/{staff_id}
{
  "status": "on_leave"
}

4. Add New Skills

PUT /service-professionals/{staff_id}
{
  "skills": ["facial", "makeup", "hair_styling", "nail_art"]
}

5. List Active Beauty Professionals

POST /service-professionals/list
{
  "filters": {
    "status": "active",
    "category": "beauty"
  },
  "projection_list": ["staff_id", "name", "phone", "skills"]
}

---

Testing

Use the provided endpoints to test the API. All endpoints follow standard REST conventions and return appropriate HTTP status codes.

Collection: spa_service_professionals Module Path: app/service_professionals/