Get Calendar Sessions (v1)

Method & Path

GET /api/v1/workspace/:workspaceId/sessions/calendar

Actual backend path: /v1/workspace/:workspaceId/sessions/calendar

Description

Retrieve sessions formatted for calendar display. This endpoint returns sessions within a specified date range with optimized data for calendar rendering, including session times, durations, and basic information needed for calendar visualization.

Authentication

Required: Workspace authentication via session cookie or JWT token.

Required Permissions:

• sessions.view

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer token: Bearer <token> OR session cookie
Content-Type	string	No	application/json

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace identifier

Query Parameters

Parameter	Type	Required	Description
startDate	string	No	Start date for calendar range (ISO 8601 datetime). If not provided, defaults to start of current week/month based on view
endDate	string	No	End date for calendar range (ISO 8601 datetime). If not provided, defaults to end of current week/month based on view
clientId	string	No	Filter sessions by specific client ID
view	string	No	Calendar view type. Valid values: day, week, month. Defaults to week

Response 200 OK

{
  "sessions": [
    {
      "id": "507f1f77bcf86cd799439011",
      "workspaceId": "507f191e810c19729de860ea",
      "clientId": "507f1f77bcf86cd799439012",
      "clientName": "أحمد محمد",
      "name": "جلسة العلاج الطبيعي",
      "date": "2024-01-15T00:00:00.000Z",
      "startTime": "10:00",
      "endTime": "11:00",
      "durationMinutes": 60,
      "status": "scheduled",
      "serviceId": "507f1f77bcf86cd799439013",
      "serviceIds": ["507f1f77bcf86cd799439013"],
      "serviceName": "العلاج الطبيعي",
      "serviceNames": ["العلاج الطبيعي"],
      "fieldValues": [
        {
          "fieldId": "507f1f77bcf86cd799439014",
          "fieldKey": "therapist",
          "value": "د. محمد علي",
          "normalizedValue": "507f1f77bcf86cd799439015"
        }
      ]
    }
  ]
}

Response Fields:

Field	Type	Description
sessions	array	Array of session objects optimized for calendar display

Session Object Fields:

Field	Type	Description
id	string	Session unique identifier
workspaceId	string	Workspace identifier
clientId	string	Associated client ID
clientName	string	Client display name
name	string	Session name/title
date	string	Session date (ISO 8601 date)
startTime	string	Session start time (HH:mm format)
endTime	string	Session end time (HH:mm format)
durationMinutes	number	Session duration in minutes
status	string	Session status: scheduled, in-progress, completed, cancelled
serviceId	string	Primary service ID (deprecated, use serviceIds)
serviceIds	array	Array of service IDs associated with the session
serviceName	string	Primary service name (deprecated, use serviceNames)
serviceNames	array	Array of service names
fieldValues	array	Array of custom field values (only filterable fields are included)

Field Value Object:

Field	Type	Description
fieldId	string	Session field ID
fieldKey	string	Session field key (for filtering)
value	string	Display value
normalizedValue	string | array	Normalized value for filtering (ID for team fields, value for others)

Usage Notes

1. Date Range:

   • If startDate and endDate are not provided, the endpoint uses sensible defaults based on the view parameter
   • For day view: current day
   • For week view: Sunday to Saturday of current week
   • For month view: first to last day of current month

2. Timezone Handling:

   • All dates are returned in UTC
   • Times are in workspace timezone (HH:mm format)
   • Client should convert dates/times based on workspace timezone settings

3. Field Values:

   • Only filterable session fields are included in the response
   • Team fields include both value (display name) and normalizedValue (staff member ID)
   • Other fields include normalizedValue as the filterable value

4. Performance:

   • Optimized for calendar rendering with minimal data
   • Suitable for day/week/month views
   • For detailed session information, use the GET /sessions/:sessionId endpoint

Example Requests

Get Week View Sessions

GET /api/v1/workspace/507f191e810c19729de860ea/sessions/calendar?view=week&startDate=2024-01-14T00:00:00Z&endDate=2024-01-20T23:59:59Z

Get Day View Sessions for Specific Client

GET /api/v1/workspace/507f191e810c19729de860ea/sessions/calendar?view=day&clientId=507f1f77bcf86cd799439012&startDate=2024-01-15T00:00:00Z&endDate=2024-01-15T23:59:59Z

Get Month View Sessions

GET /api/v1/workspace/507f191e810c19729de860ea/sessions/calendar?view=month&startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z

Common Errors

400 Bad Request: Invalid date format or invalid view parameter value

404 Not Found: Workspace not found or access denied

401 Unauthorized: Authentication required

403 Forbidden: Subscription expired or insufficient permissions (sessions.view required)

422 Unprocessable Entity: Invalid query parameters

500 Internal Server Error: Server error occurred

Related Documentation

• List Sessions - Full session listing with detailed information
• Get Session - Get detailed information for a single session
• Session Calendar Product Documentation - User guide for calendar features