Create Appointment

This endpoint allows you to create a new appointment in the system. The appointment can be associated with one or more calendars and an optional service. You can also provide guests and reminders.

🔹 Endpoint Details

POST /api/v2/appointments

🔒 Authentication

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

📝 Request Structure

Required Fields

Conditional requirements apply:

If blockedAppointmentId is NOT provided, startAt, endAt must be valid ISO 8601 datetimes.

Field	Type	Required	Description	Example
`startAt`	string (ISO 8601)	Cond.	Start time	`"2025-05-20T14:00:00Z"`
`endAt`	string (ISO 8601)	Cond.	End time	`"2025-05-20T15:00:00Z"`

Optional Fields

Field	Type	Required	Description	Example
`title`	string	No	Appointment title	`"Quarterly Review Meeting"`
`description`	string	No	Detailed description	-
`lang`	string	No	Language code (BCP 47)	`"en-US"`
`status`	string	No	Appointment status	`"confirmed"`
`subStatus`	string	No	Appointment sub-status	`"pending"`
`origin`	string	No	Source/platform	`"web-portal"`
`originUrl`	string (URL)	No	Origin URL	`"https://example.com/create"`
`comment`	string	No	Comment or note	`"Special requirements"`
`interactionId`	string	No	Interaction identifier	`"123e4567-e89b-12d3-a456-426614174000"`
`externalId`	string	No	External identifier	`"EXT-APT-123"`
`reminders`	array of object	No	Reminder settings	See reminders schema below
`guests`	array of object	No	Guest list	See guests schema below
`calendarIds`	array of string (UUID)	Cond.	Calendar identifiers (required unless blocking by reference)	`["123e4567-e89b-12d3-a456-426614174000"]`
`serviceId`	string (UUID)	No	Associated service	`"01392598-e4b2-4810-ac7c-8c9cf4286a26"`
`userGroupId`	string (UUID)	No	Associated user group	`"123e4567-e89b-12d3-a456-426614174000"`
`blocked`	boolean	No	Whether the appointment is a block	`false`
`blockedAppointmentId`	string (UUID)	No	Block existing appointment by reference	`"123e4567-e89b-12d3-a456-426614174000"`
`extraFields`	object	No	Additional custom fields	`{ "priority": "high" }`

Reminders schema

Field	Type	Required	Description	Example
`time`	number	Yes	Numeric value for reminder time	`10`
`unit`	enum	Yes	Time unit. One of: `s`, `m`, `h`	`"m"`
`direction`	enum	Yes	Direction relative to appointment time. `before` or `after`	`"before"`

Guest schema

Field	Type	Required	Description	Example
`email`	string	No	Guest email	`"[email protected]"`
`phone`	string	No	Guest phone	`"+1234567890"`
`firstName`	string	No	Guest first name	`"John"`
`lastName`	string	No	Guest last name	`"Doe"`
`status`	string	No	Guest status	`"invited"`
`canonicalId`	string	No	Canonical ID	`"guest-12345"`

🧩 Request Examples

Basic Appointment

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

Comprehensive Appointment

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

❌ Error Responses

This endpoint follows the standard error format.

📘 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
To create a block, set blocked: true and provide startAt/endAt or use blockedAppointmentId to reference an existing appointment.

✅ 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

Time Validation
- End time must be after start time
- Times must be in the future
- Duration must match service requirements (if applicable)
Guest Validation
- Valid email addresses or phone numbers can be provided
- Maximum 50 guests per appointment
- Duplicate emails not allowed
Calendar Validation
- Calendar must be available
- Time slot must be free (unless specific business logic allows overlaps)
- Must be within calendar's working hours
Service Validation
- Service must be active
- Duration must match service settings
- Must respect service scheduling rules

💡 Best Practices

Scheduling
- Check calendar availability first
- Consider timezone differences
- Allow buffer time between appointments
Guest Management
- Validate email addresses
- Set appropriate notification preferences
- Consider guest calendar availability
Service Integration
- Use service templates when possible
- Respect service duration requirements
- Include relevant service details

🔹 Endpoint Details​

🔒 Authentication​

📝 Request Structure​

Required Fields​

Optional Fields​

Reminders schema​

Guest schema​

🧩 Request Examples​

Basic Appointment​

Comprehensive Appointment​

📤 Response Format​

Success Response (201 Created)​

❌ Error Responses​

📘 Notes​

✅ Common Use Cases​

🔍 Validation Rules​

💡 Best Practices​