Create Appointment

This endpoint allows you to create a new appointment in the system. The appointment can be associated with a calendar and service, and will include guest management and notification settings.

🔹 Endpoint Details

POST /api/v1/appointments

🔒 Authentication

Header	Required	Description
Content-Type	Yes	Must be application/json
Authorization	Yes	Format: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature

📝 Request Structure

Required Fields

Field	Type	Required	Description	Example
start	string (ISO 8601)	Yes	Start time	"2025-05-20T14:00:00Z"
end	string (ISO 8601)	Yes	End time	"2025-05-20T15:00:00Z"
calendarIds	array of string (UUID)	Yes	Calendar identifiers	["123e4567-e89b-12d3-a456-426614174000"]

Optional Fields

Field	Type	Required	Description	Example
title	string	No	Appointment title	"Product Demo Meeting"
origin	string	No	Creation source	"web"
externalId	string	No	External identifier	"ext123"
description	string	No	Detailed description	-
allowOverlapping	boolean	No	Allow overlapping	false
serviceId	string (UUID)	No	Associated service	-
reminders	array	No	Reminder settings	[{ "time": 10, "unit": "m" }]
extraFields	object	No	Additional custom fields	-
guests	array	No	Guest list	[]
lang	string	No	Language code	"en"

🧩 Request Examples

Basic Appointment

curl -X POST "https://openapi.onlive.site/api/v1/appointments" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature" \
-d '{
  "title": "Quick Meeting",
  "start": "2025-05-20T14:00:00Z",
  "end": "2025-05-20T15:00:00Z",
  "origin": "web",
  "calendarIds": [
    "af6c6be0-689a-4cf3-a8c8-550dd97b3a6b"
  ]
}'

Comprehensive Appointment

curl -X POST "https://openapi.onlive.site/api/v1/appointments" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature" \
-d '{
  "title": "Product Demo Meeting",
  "description": "Product demonstration with new features",
  "start": "2025-05-20T14:00:00Z",
  "end": "2025-05-20T15:00:00Z",
  "calendarIds": [
    "af6c6be0-689a-4cf3-a8c8-550dd97b3a6b"
  ],
  "serviceId": "01392598-e4b2-4810-ac7c-8c9cf4286a26",
  "origin": "web",
  "lang": "en",
  "reminders": [
    {
      "time": 10,
      "unit": "m"
    }
  ],
  "guests": [
    {
      "email": "[email protected]"
    }
  ],
  "extraFields": {
    "priority": "high",
    "location": "Conference Room A"
  }
}'

📤 Response Format

Success Response (201 Created)

{
  "id": "1610c525-f19a-40d0-8cd1-03daba3d2d98",
  "createdAt": "2025-05-20T13:55:03.735Z",
  "updatedAt": "2025-05-20T13:55:03.735Z",
  "title": "Product Demo Meeting",
  "description": "Product demonstration with new features",
  "lang": "en",
  "start": "2025-05-20T14:00:00Z",
  "end": "2025-05-20T15:00:00Z",
  "calendarIds": ["af6c6be0-689a-4cf3-a8c8-550dd97b3a6b"],
  "serviceId": "01392598-e4b2-4810-ac7c-8c9cf4286a26",
  "reminders": [
    {
      "time": 10,
      "unit": "m"
    }
  ],
  "guests": [
    {
      "email": "[email protected]"
    }
  ],
  "extraFields": {
    "priority": "high",
    "location": "Conference Room A"
  },
  "state": "confirmed",
  "origin": "web"
}

❌ Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid input",
  "errors": [
    {
      "field": "end",
      "message": "end time must be after start time"
    }
  ]
}

403 Forbidden

{
  "statusCode": 403,
  "message": "Insufficient permissions to create appointments"
}

409 Conflict

{
  "statusCode": 409,
  "message": "Time slot is already booked"
}

422 Unprocessable Entity

{
  "statusCode": 422,
  "message": "Validation failed",
  "errors": [
    {
      "field": "serviceId",
      "message": "appointment duration does not match service requirements"
    }
  ]
}

📘 Notes

• The organizationId is automatically set from your authentication credentials
• All times must be in ISO 8601 format with UTC timezone
• Guest email notifications are handled automatically based on preferences
• Service constraints (duration, availability) are automatically validated
• Default reminder is 10 minutes before appointment if not specified
• Calendar availability is checked before appointment creation

✅ Common Use Cases

• 📅 Basic Meeting: Schedule simple one-on-one meetings
• 👥 Team Event: Create meetings with multiple participants
• 🎯 Service Booking: Schedule service-based appointments
• 🌐 Virtual Meeting: Set up video conferences
• 📊 Resource Booking: Schedule equipment or room usage

🔍 Validation Rules

1. Time Validation

   • End time must be after start time
   • Times must be in the future
   • Duration must match service requirements (if applicable)

2. Guest Validation

   • Valid email addresses required
   • Maximum 50 guests per appointment
   • Duplicate emails not allowed

3. Calendar Validation

   • Calendar must be available
   • Time slot must be free (unless allowOverlapping is true)
   • Must be within calendar's working hours

4. Service Validation

   • Service must be active
   • Duration must match service settings
   • Must respect service scheduling rules

💡 Best Practices

1. Scheduling

   • Check calendar availability first
   • Consider timezone differences
   • Allow buffer time between appointments

2. Guest Management

   • Validate email addresses
   • Set appropriate notification preferences
   • Consider guest calendar availability

3. Service Integration

   • Use service templates when possible
   • Respect service duration requirements
   • Include relevant service details