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"
cancellationToken	string	No	Yes	Token used to authorize cancellation	"cancel-abc123"
cancellationOrigin	string	No	Yes	Source or reason category for cancellation	"user"
origin	string	No	No	Source from which the appointment was created	"web"
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"
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"
start	string (ISO 8601)	Yes	No	Start time of the appointment	"2025-05-20T14:00:00Z"
end	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"
state	string	No	No	Current state of the appointment	"pending"

🗓️ 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"
allowOverlapping	boolean	No	Allow overlap with other appointments	false
state	string	No	Current state of the appointment	"confirmed"

👥 Guest Management

Property	Type	Required	Description	Example
guests	array	No	List of guests invited	See guests example below
guests[].email	string	Yes	Guest's email address	"[email protected]"
guests[].extraFields	object	No	Additional guest information	{"company": "Acme Corp"}

⏰ 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	string	Yes	Time unit (s/m/h)	"m"

🎥 Event Details

Property	Type	Required	Description	Example
event.eventId	string (UUID)	Yes	Virtual event identifier	"123e4567-e89b-12d3-a456-426614174000"
event.iCallUrl	string (URL)	Yes	Video call URL	"https://meet.example.com/room/123"
event.room	string	Yes	Virtual room name	"Demo Room 1"

---

🧩 Example Entry

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "externalId": "EXT-123",
  "title": "Product Demo Meeting",
  "description": "Demonstration of new product features to the client",
  "start": "2025-05-20T14:00:00Z",
  "end": "2025-05-20T15:00:00Z",
  "lang": "en-US",
  "calendarIds": ["123e4567-e89b-12d3-a456-426614174000"],
  "serviceId": "123e4567-e89b-12d3-a456-426614174000",
  "cancellationToken": "tkn_cancel_123",
  "cancellationOrigin": "user",
  "state": "pending",
  "createdAt": "2025-05-22T10:30:00Z",
  "updatedAt": "2025-05-22T10:30:00Z",
  "guests": [
    {
      "email": "[email protected]"
    }
  ],
  "extraFields": {
    "area": "Madrid",
    "city": "Alcobendas",
    "street": "Carretera. De Fuencarral, 18",
    "country": "Spain"
  },
  "reminders": [
    {
      "time": 10,
      "unit": "m"
    }
  ],
  "event": {
    "eventId": "123e4567-e89b-12d3-a456-426614174000",
    "iCallUrl": "https://meet.example.com/room/123",
    "room": "Demo Room 1"
  },
  "origin": "web",
  "agentComment": null,
  "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 include event details with video call information
• Appointments follow a state 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: Automatically generate meeting links
• States: Follow defined state transition rules
• Custom Fields: Use extraFields for additional data

---