Update Appointment

This endpoint allows you to update an existing appointment's details. Only the fields you provide will be modified, while others remain unchanged.

🔹 Endpoint Details

PUT /api/v1/appointments/{appointmentId}

🔒 Authentication

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

📝 Updatable Fields

Field	Type	Description	Example
title	string	Title or subject of the appointment	"Updated Product Demo"
description	string	Detailed description	"Product walkthrough"
start	string	Start time (ISO 8601)	"2025-03-10T08:00:00Z"
end	string	End time (ISO 8601)	"2025-03-10T08:30:00Z"
guests	array	List of attendees	See examples
reminders	array	Reminder settings	See examples
extraFields	object	Custom fields	{"priority": "high"}
lang	string	Language code	"en"
classification	string	Category	"internal"
event	object	Virtual event details	See examples
state	string	Appointment state	"confirmed"
agentComment	string	Internal notes	"Follow-up needed"

🧩 Request Examples

Basic Update

curl -X PUT "https://openapi.onlive.site/api/v1/appointments/1610c525-f19a-40d0-8cd1-03daba3d2d98" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature" \
-d '{
  "start": "2025-03-10T08:00:00.000Z",
  "end": "2025-03-10T08:30:00.000Z"
}'

Comprehensive Update

curl -X PUT "https://openapi.onlive.site/api/v1/appointments/1610c525-f19a-40d0-8cd1-03daba3d2d98" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature" \
-d '{
  "title": "Updated Product Demo Meeting",
  "description": "Updated demo session with new features",
  "start": "2025-03-10T08:00:00.000Z",
  "end": "2025-03-10T08:30:00.000Z",
  "guests": [
    {
      "email": "[email protected]"
    }
  ],
  "reminders": [
    {
      "time": 15,
      "unit": "m"
    }
  ],
  "extraFields": {
    "priority": "high",
    "location": "Virtual Meeting Room"
  },
  "event": {
    "iCallUrl": "https://meet.example.com/updated-room",
    "room": "Demo Room 2"
  }
}'

📤 Response Format

Success Response (HTTP 200)

{
  "id": "1610c525-f19a-40d0-8cd1-03daba3d2d98",
  "createdAt": "2025-03-09T19:32:03.735Z",
  "updatedAt": "2025-03-09T19:32:06.669Z",
  "title": "Updated Product Demo Meeting",
  "description": "Updated demo session with new features",
  "start": "2025-03-10T08:00:00.000Z",
  "end": "2025-03-10T08:30:00.000Z",
  "guests": [
    {
      "email": "[email protected]"
    }
  ],
  "reminders": [
    {
      "time": 15,
      "unit": "m"
    }
  ],
  "extraFields": {
    "priority": "high",
    "location": "Virtual Meeting Room"
  },
  "event": {
    "iCallUrl": "https://meet.example.com/updated-room",
    "room": "Demo Room 2"
  },
  "state": "confirmed"
}

❌ Error Responses

400 Bad Request

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

403 Forbidden

{
  "statusCode": 403,
  "message": "Insufficient permissions to update this appointment"
}

404 Not Found

{
  "statusCode": 404,
  "message": "Appointment not found"
}

409 Conflict

{
  "statusCode": 409,
  "message": "Scheduling conflict",
  "errors": [
    {
      "field": "time",
      "message": "Selected time slot is no longer available"
    }
  ]
}

422 Unprocessable Entity

{
  "statusCode": 422,
  "message": "Validation failed",
  "errors": [
    {
      "field": "guests",
      "message": "Maximum number of guests exceeded"
    }
  ]
}

🔍 Validation Rules

1. Time Validation

   • End time must be after start time
   • Times must be in valid ISO 8601 format
   • Cannot modify past appointments
   • Must respect service duration (if applicable)

2. Guest Management

   • Valid email addresses required
   • No duplicate email addresses

3. Resource Validation

   • Calendar availability checked
   • Service rules respected

📘 Notes

1. Update Behavior

   • Partial updates supported
   • Unchanged fields retain values
   • Arrays are replaced, not merged
   • Null values clear fields

2. Notification Handling

   • Changes trigger notifications
   • Guest preferences respected
   • Calendar syncs updated
   • Service provider notified

3. Resource Management

   • Calendar slots updated
   • Service availability adjusted
   • Room bookings modified
   • Resources reallocated

💡 Best Practices

1. Update Strategy

   • Only include changed fields
   • Validate before updating
   • Handle conflicts gracefully
   • Consider timezone impact

2. Guest Management

   • Verify email addresses
   • Consider notification timing
   • Maintain guest preferences
   • Handle declined invitations

3. Resource Handling

   • Check availability first
   • Reserve resources early
   • Handle cleanup properly
   • Monitor conflicts

4. Error Management

   • Implement proper rollback
   • Log significant changes
   • Monitor failure patterns
   • Provide clear messages