Appointment Properties

This table defines the structure of the appointment entity, including all properties and their descriptions.

🔹 Core Properties

Property	Type	Required	Read-Only	Description	Example
id	string (UUID)	No	Yes	Unique identifier for the appointment	"550e8400-e29b-41d4-a716-446655440000"
createdAt	string (ISO 8601)	No	Yes	Timestamp when the appointment was created	"2025-05-01T10:30:00Z"
updatedAt	string (ISO 8601)	No	Yes	Timestamp when the appointment was last updated	"2025-05-21T09:00:00Z"
cancelledAt	string (ISO 8601)	No	Yes	Timestamp when the appointment was cancelled	"2025-05-22T08:15:00Z"
cancellationOrigin	string	No	Yes	Source or reason category for cancellation	"user"
origin	string	No	No	Source from which the appointment was created	"web"
originUrl	string (URL)	No	No	Origin URL where the appointment was created	"https://example.com"
extraFields	object	No	No	Custom object containing additional defined fields	{ "salesRep": "John Doe", "priority": "high" }
externalId	string	No	No	External identifier for the appointment	"EXT-123"
interactionId	string	No	No	Interaction identifier (UUID string)	"123e4567-e89b-12d3-a456-426614174000"
comment	string	No	No	Additional comment	"Additional notes"
title	string	No	No	Title or subject of the appointment	"Product Demo Meeting"
description	string	No	No	Detailed description of the appointment	"Demonstration of new product features"
startAt	string (ISO 8601)	Yes	No	Start time of the appointment	"2025-05-20T14:00:00Z"
endAt	string (ISO 8601)	Yes	No	End time of the appointment	"2025-05-20T15:00:00Z"
lang	string	No	No	Language code for localization	"en-US"
status	string	No	No	Current status of the appointment	"pending"
subStatus	string	No	No	Sub-status of the appointment	"reschedule-requested"
blockedUntil	string (ISO 8601)	No	No	Blocked until datetime (if applicable)	"2025-05-20T13:30:00Z"
version	number	No	No	Version number	1
bufferTimeMinutes	number	No	No	Buffer time in minutes	15
providerEventId	string	No	No	Provider event identifier	"prov-123"
providerETag	string	No	No	Provider ETag	"etag-123"
providerId	string (UUID)	No	No	Provider ID	"123e4567-e89b-12d3-a456-426614174000"
userPreferences	object	No	No	User preferences by entity type	{ "agent": [{"field":"lang","value":"en","required":true}] }

🗓️ Scheduling Properties

Property	Type	Required	Description	Example
calendarIds	array of string (UUID)	Yes	List of calendar IDs this appointment belongs to	["123e4567-e89b-12d3-a456-426614174000", "223e4567-e89b-12d3-a456-426614174001"]
serviceId	string (UUID)	No	ID of the service/template used	"123e4567-e89b-12d3-a456-426614174000"
userGroupId	string (UUID)	No	User group identifier	"1be7bf10-5c72-480b-b0d7-1c2bb023225d"
blocked	boolean	No	Whether the appointment is a block	false
blockedAppointmentId	string (UUID)	No	Block an existing appointment by reference	"123e4567-e89b-12d3-a456-426614174000"

👥 Guest Management

Property	Type	Required	Description	Example
guests	array	No	List of guests invited	See guests example below
guests[].email	string	No	Guest email	"[email protected]"
guests[].phone	string	No	Guest phone	"+1234567890"
guests[].firstName	string	No	Guest first name	"John"
guests[].lastName	string	No	Guest last name	"Doe"
guests[].status	string	No	Guest status	"invited"
guests[].canonicalId	string	No	Canonical ID	"guest-12345"

⏰ Reminders and Notifications

Property	Type	Required	Description	Example
reminders	array	No	Reminder configurations	See reminders example below
reminders[].time	number	Yes	Time value for reminder	10
reminders[].unit	enum	Yes	Time unit. One of: s (seconds), m (minutes), h (hours)	"m"
reminders[].direction	enum	Yes	Direction relative to the appointment: before or after	"before"
reminders[].executionDate	string (ISO 8601)	No	Exact execution datetime (calculated)	"2025-05-14T09:45:00Z"
reminders[].executedAt	string (ISO 8601)	No	When the reminder was executed (if executed)	"2025-05-14T09:45:10Z"

🎥 Event Details

Property	Type	Required	Description	Example
event	object	No	Arbitrary provider event properties	{ "eventId": "123e4567-..." }

---

🧩 Example Entry

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "externalId": "EXT-123",
  "title": "Product Demo Meeting",
  "description": "Demonstration of new product features to the client",
  "startAt": "2025-05-20T14:00:00Z",
  "endAt": "2025-05-20T15:00:00Z",
  "lang": "en-US",
  "calendarIds": ["123e4567-e89b-12d3-a456-426614174000"],
  "serviceId": "123e4567-e89b-12d3-a456-426614174000",
  "cancellationOrigin": "user",
  "status": "pending",
  "createdAt": "2025-05-22T10:30:00Z",
  "updatedAt": "2025-05-22T10:30:00Z",
  "guests": [
    {
      "email": "[email protected]",
      "firstName": "John",
      "lastName": "Doe"
    }
  ],
  "extraFields": {
    "area": "Madrid",
    "city": "Alcobendas",
    "street": "Carretera. De Fuencarral, 18",
    "country": "Spain"
  },
  "reminders": [
    {
      "time": 10,
      "unit": "m",
      "direction": "before"
    }
  ],
  "event": {
    "eventId": "123e4567-e89b-12d3-a456-426614174000",
    "iCallUrl": "https://meet.example.com/room/123",
    "room": "Demo Room 1"
  },
  "origin": "web",
  "organizationId": "bfc5b6b5-1d67-419e-9025-96336f2330c6",
  "cancelledAt": null
}

---

🔍 Interpretation

• Appointments can optionally be tied to a service (serviceId)
• Guests receive notifications based on their preferences
• Virtual meetings may include event details
• Appointments follow a status lifecycle (pending → confirmed → completed/cancelled)
• All times are in ISO 8601 format with UTC timezone

---

✅ Use Cases

• 📅 Basic Scheduling: Create standard appointments
• 🎥 Virtual Meetings: Schedule video conferences
• 👥 Group Events: Manage multi-participant appointments
• 🔄 Series Management: Handle recurring appointments
• 📋 Service Booking: Schedule service-based appointments

---

📘 Notes

• Timezone: All times must be in UTC
• Duration: End time must be after start time
• Overlap: By default, appointments cannot overlap
• Notifications: Configurable per guest
• Virtual Events: May include provider-specific fields
• Status/Sub-status: Use status and subStatus for lifecycle tracking
• Custom Fields: Use extraFields for additional data

---