Coaches

This guide explains how to interact with the coaches API endpoints in the Calwe application.

List Coaches

Endpoint

Method: GET
URL: /v1/customer/coaches

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes

Query Parameters

Parameter	Type	Description	Required	Validation Rules
filter[available_days][from]	string	Start date for availability	No	after_or_equal: current date (Y-m-d)
filter[available_days][to]	string	End date for availability	No	after: from date (Y-m-d)
filter[available_time][from]	string	Start time for availability	No	date_format: H:i
filter[available_time][to]	string	End time for availability	No	date_format: H:i
filter[languages][]	string	Language IDs	No	array of valid language UUIDs
filter[gender][]	string	Coach gender	No	array with single value: FEMALE or MALE
filter[complete_sessions][]	number	Minimum completed sessions	No	array with single numeric value
filter[online_coaches][]	string	Specific coach IDs	No	array of valid coach UUIDs
filter[categories][]	string	Category IDs	No	array of valid category UUIDs
filter[nationalities][]	string	Country IDs	No	array of valid country UUIDs
filter[rate][]	number	Rating filter	No	array with single numeric value
filter[status][]	string	Status filter	No	array

Success Response

{
    "success": true,
    "message": "تم جلب البيانات بنجاح",
    "data": {
        "coaches": [
            {
                "id": "uuid",
                "firstName": "اسم",
                "lastName": "اللقب",
                "email": "ecample@example.com",
                "phone": "1234567890",
                "gender": "MALE",
                "avatar": "https://example.com/avatar.jpg",
                "rate": 4.5,
                "completeSessions": 100,
                "languages": [
                    {
                        "id": "uuid",
                        "name": "English"
                    }
                ],
                "categories": [
                    {
                        "id": "uuid",
                        "name": "Fitness"
                    }
                ],
                "nationality": {
                    "id": "uuid",
                    "name": "Saudi Arabia"
                }
            }
        ],
        "pagination": {
            "currentPage": 1,
            "lastPage": 10,
            "perPage": 15,
            "total": 150
        }
    },
    "statusCode": 200
}

Get Coach Details

Endpoint

Method: GET
URL: /v1/customer/coaches/{id}

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes

Path Parameters

Parameter	Type	Description	Required
id	string	Coach UUID	Yes

Success Response

{
    "success": true,
    "message": "تم جلب البيانات بنجاح",
    "data": {
        "id": "uuid",
        "firstName": "اسم",
        "lastName": "اللقب",
        "email": "coach@example.com",
        "phone": "1234567890",
        "gender": "MALE",
        "avatar": "https://example.com/avatar.jpg",
        "rate": 4.5,
        "completeSessions": 100,
        "languages": [
            {
                "id": "uuid",
                "name": "English"
            }
        ],
        "categories": [
            {
                "id": "uuid",
                "name": "Fitness"
            }
        ],
        "nationality": {
            "id": "uuid",
            "name": "Saudi Arabia"
        },
        "bio": "Coach description",
        "experience": "5 years",
        "specializations": ["Weight Loss", "Muscle Gain"],
        "availability": {
            "days": ["Monday", "Wednesday", "Friday"],
            "time": "09:00-17:00"
        }
    },
    "statusCode": 200
}

Error Responses

Not Found Error (404)

{
    "success": false,
    "message": "لم يتم العثور على السجل",
    "data": [],
    "statusCode": 404
}

Get Main Page Coaches

Endpoint

Method: GET
URL: /v1/customer/coaches/main-page

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes

Success Response

{
    "success": true,
    "message": "تم جلب البيانات بنجاح",
    "data": {
        "coaches": [
            {
                "id": "uuid",
                "name": "اسم",
                "about": "نبذة عنيي",
                "rate": "2.7",
                "avatar": "https://example.com/avatar.jpg",
                "status": "ONLINE",
                "availabilityStatus": "ONLINE",
                "coachLevelId": "uuid",
                "coachLevelName": "353454364",
                "deepSpecialization": null,
                "categories": [
                    {
                        "id": "uuid",
                        "name": "استشارة طبية",
                        "description": "وصف استشارة طبية",
                        "deepSpecializations": []
                    }
                ]
            },
        ]
    },
    "statusCode": 200
}

Get Online Coaches

Endpoint

Method: GET
URL: /v1/customer/online-coaches

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes

Success Response

{
    "success": true,
    "message": "تم جلب البيانات بنجاح",
    "data": {
        "coaches": [
            {
                "id": "uuid",
                "name": "اسم",
                "about": "نبذة عنيي",
                "categoryName": "مجال الوعي",
                "sessionCompletedCount": "113",
                "rate": "2.7",
                "avatar": "https://example.com/avatar.jpg",
                "status": "ONLINE",
                "availabilityStatus": "ONLINE",
                "coachLevelId": "uuid",
                "coachLevelName": "353454364",
                "deepSpecialization": null,
                "categories": [
                    {
                        "id": "uuid",
                        "name": "استشارة طبية",
                        "description": "وصف استشارة طبية",
                        "deepSpecializations": []
                    }
                ]
            },
        ]
    },
    "statusCode": 200
}

Get Coach Rates

Endpoint

Method: GET
URL: /v1/customer/coaches/{id}/rates

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes

Path Parameters

Parameter	Type	Description	Required
id	string	Coach UUID	Yes

Success Response

{
    "success": true,
    "message": "تم جلب البيانات بنجاح",
    "data": {
        "rates": [
            {
                "full_name": "اسم المدرب",
                "avatar": "https://example.com/avatar.jpg",
                "rate": 4.5,
                "comment": "تعليق على جودة التدريب",
                "created_at": "منذ 3 ساعات"
            }
        ],
        "average_rate": 4.5,
        "total_rates": 10
    },
    "statusCode": 200
}

Get Coach Appointments

Endpoint

Method: GET
URL: /v1/customer/coaches/{id}/appointments

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes

Path Parameters

Parameter	Type	Description	Required
id	string	Coach UUID	Yes

Query Parameters

Parameter	Type	Description	Required	Validation Rules
filter[is_booked]	boolean	Filter by booking status	No	true/false
filter[coach_id]	string	Filter by coach ID	No	UUID

Success Response

{
    "success": true,
    "message": "تم جلب البيانات بنجاح.",
    "data": {
        "currentPage": 1,
        "from": 1,
        "to": 0,
        "perPage": 7,
        "total": 0,
        "prevPageUrl": null,
        "nextPageUrl": null,
        "lastPage": 0,
        "appointments": {
            "الجمعة 03/21": [
                {
                    "id": "uuid",
                    "hour": "01:00 م - 02:00 م",
                    "duration": 60
                }
            ],
            "السبت 03/22": [
                {
                    "id": "uuid",
                    "hour": "01:00 م - 02:00 م",
                    "duration": 60
                }
            ]
        }
    },
    "statusCode": 200
}

Get Coach Available Appointments

Get available appointment slots for a specific coach.

Endpoint

Method: GET
URL: /v1/customer/coaches/{id}/coach-available-appointments

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes
Authorization	Bearer token	Yes

Path Parameters

Parameter	Type	Description	Required
id	string	Coach ID	Yes

Query Parameters

Parameter	Type	Description	Required	Default
date	string	Date to check availability (format: Y-m-d)	Yes	null
coach_category_id	string	Filter by coach category	No	null

Success Response

{
    "success": true,
    "message": "تم جلب البيانات بنجاح",
    "data": {
        "available_slots": [
            {
                "id": "uuid",
                "start_time": "10:00",
                "end_time": "11:00",
                "is_available": true,
                "session_type": "scheduled",
                "session_duration": 60
            }
        ],
        "coach": {
            "id": "uuid",
            "first_name": "string",
            "last_name": "string",
            "image": "string",
            "rate": "decimal",
            "coach_category": {
                "id": "uuid",
                "name": "string"
            }
        }
    },
    "statusCode": 200
}

Error Response

Coach Not Found (404)

{
    "success": false,
    "message": "لم يتم العثور على المدرب",
    "data": null,
    "statusCode": 404
}

Invalid Date Format (422)

{
    "success": false,
    "message": "صيغة التاريخ غير صحيحة",
    "data": null,
    "statusCode": 422
}

Unauthorized (401)

{
    "success": false,
    "message": "غير مصرح",
    "data": null,
    "statusCode": 401
}

Important Notes

General Information

All coach data is cached for better performance
Coach information is managed through the admin panel
Coach profiles include both personal and professional details
Coaches can have multiple specializations and languages
Coach availability is tracked in real-time
Coach ratings are calculated based on completed sessions

Coach Listing

Coaches can be filtered by various criteria
Results are paginated for better performance
Filters can be combined for precise results
Coach list includes basic information for quick overview
List can be sorted by different parameters
Online status is updated in real-time

Coach Details

Detailed profile includes comprehensive information
Coach experience and specializations are highlighted
Availability schedule is included
Contact information is provided based on privacy settings
Coach categories and languages are listed
Performance metrics are displayed

Coach Rates

Rates are based on completed session feedback
Average rate is calculated from all ratings
Individual ratings include comments and timestamps
Rate history is maintained
Rating system uses 1-5 scale
Only completed sessions can be rated

Coach Appointments

Appointments are organized by date
Each appointment includes duration and time slot
Appointments can be filtered by booking status
Available slots are shown in chronological order
Appointments respect coach's working hours
Booking window is limited to 30 days in advance

Coach Availability

Available slots are filtered based on:
- Coach's working hours
- Existing appointments
- Coach's preferred schedule
- Category-specific requirements
Slots can be filtered by:
- Date range
- Time range
- Coach category
- Session type
Real-time availability updates
Maximum booking window restrictions
Minimum notice period requirements

Coach Categories

Coaches can belong to multiple categories
Categories have specific requirements
Category-specific pricing may apply
Categories determine available session types
Category information includes descriptions
Deep specializations are supported

Coach Levels

Coaches are assigned experience levels
Levels affect pricing and availability
Level progression is tracked
Level requirements are category-specific
Level information is displayed in listings
Level affects coach visibility

Coach Languages

Multiple languages are supported
Language proficiency is indicated
Language affects coach availability
Language preferences can be filtered
Language settings affect communication
Language-specific pricing may apply

Coach Status

Online/Offline status is tracked
Status affects availability
Status updates are real-time
Status history is maintained
Status affects coach visibility
Status can be manually updated by coach

Coach Search and Filtering

Search by name or specialization
Filter by multiple criteria:
- Availability
- Languages
- Categories
- Experience
- Rating
- Gender
- Nationality
Results are sorted by relevance
Advanced filtering options available
Search results are cached

List Coaches​

Endpoint​

Request Headers​

Query Parameters​

Success Response​

Get Coach Details​

Endpoint​

Request Headers​

Path Parameters​

Success Response​

Error Responses​

Not Found Error (404)​

Get Main Page Coaches​

Endpoint​

Request Headers​

Success Response​

Get Online Coaches​

Endpoint​

Request Headers​

Success Response​

Get Coach Rates​

Endpoint​

Request Headers​

Path Parameters​

Success Response​

Get Coach Appointments​

Endpoint​

Request Headers​

Path Parameters​

Query Parameters​

Success Response​

Get Coach Available Appointments​

Endpoint​

Request Headers​

Path Parameters​

Query Parameters​

Success Response​

Error Response​

Coach Not Found (404)​

Invalid Date Format (422)​

Unauthorized (401)​

Important Notes​

General Information​

Coach Listing​

Coach Details​

Coach Rates​

Coach Appointments​

Coach Availability​

Coach Categories​

Coach Levels​

Coach Languages​

Coach Status​

Coach Search and Filtering​

List Coaches

Endpoint

Request Headers

Query Parameters

Success Response

Get Coach Details

Endpoint

Request Headers

Path Parameters

Success Response

Error Responses

Not Found Error (404)

Get Main Page Coaches

Endpoint

Request Headers

Success Response

Get Online Coaches

Endpoint

Request Headers

Success Response

Get Coach Rates

Endpoint

Request Headers

Path Parameters

Success Response

Get Coach Appointments

Endpoint

Request Headers

Path Parameters

Query Parameters

Success Response

Get Coach Available Appointments

Endpoint

Request Headers

Path Parameters

Query Parameters

Success Response

Error Response

Coach Not Found (404)

Invalid Date Format (422)

Unauthorized (401)

Important Notes

General Information

Coach Listing

Coach Details

Coach Rates

Coach Appointments

Coach Availability

Coach Categories

Coach Levels

Coach Languages

Coach Status

Coach Search and Filtering