Get Appointments

This section covers endpoints for retrieving both individual appointments and lists of appointments.

🔹 Get Single Appointment

Retrieve detailed information about a specific appointment by its ID.

Endpoint Details

GET /api/v2/appointments/{id}

🔒 Authentication

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

🧩 Request Example

curl -X GET "https://openapi.onlive.site/api/v2/appointments/1610c525-f19a-40d0-8cd1-03daba3d2d98" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature"

📤 Response Format (HTTP 200)

{
  "id": "1610c525-f19a-40d0-8cd1-03daba3d2d98",
  "deletedAt": null,
  "createdAt": "2025-03-09T19:32:03.735Z",
  "updatedAt": "2025-03-09T19:32:06.669Z",
  "title": "Test Drive Standard",
  "description": "",
  "lang": "es",
  "startAt": "2025-03-10T08:00:00.000Z",
  "endAt": "2025-03-10T08:30:00.000Z",
  "event": null,
  "reminders": [
    {
      "time": 10,
      "unit": "m",
      "direction": "before"
    }
  ],
  "guests": [
    {
      "email": "[email protected]",
      "extraFields": {
        "phone": "+34600000000",
        "lastName": "Doe",
        "firstName": "John"
      }
    }
  ],
  "extraFields": {
    "area": "Madrid",
    "city": "Alcobendas",
    "street": "Carretera. De Fuencarral, 18",
    "country": "Spain"
  },
  "calendarIds": ["af6c6be0-689a-4cf3-a8c8-550dd97b3a6b"],
  "serviceId": "01392598-e4b2-4810-ac7c-8c9cf4286a26",
  "status": "pending",
  "origin": "onlive_public",
  "organizationId": "26d47eec-c742-4b1c-9d70-9a1486260abd",
  "userGroupId": "1be7bf10-5c72-480b-b0d7-1c2bb023225d"
}

❌ Error Responses

This endpoint follows the standard error format.

🔹 List Appointments

Retrieve a paginated list of appointments with optional filtering.

Endpoint Details

GET /api/v2/appointments

📝 Query Parameters

Parameter	Type	Required	Description	Example
search	string	No	Search by title, status, guest, or description	"client meeting"
resourceId	string	No	Filter by resource UUID	"123e4567-e89b-12d3-a456-426614174000"
calendarId	string	No	Filter by calendar UUID	"af6c6be0-689a-4cf3-a8c8-550dd97b3a6b"
startDate	string	No	Start of date range (ISO 8601)	"2025-05-01T00:00:00Z"
endDate	string	No	End of date range (ISO 8601)	"2025-05-31T23:59:59Z"
calendarType	string	No	agent or asset	"agent"
serviceId	string	No	Filter by service UUID	"01392598-e4b2-4810-ac7c-8c9cf4286a26"
status	string	No	Filter by status	"confirmed"
subStatus	string	No	Filter by sub-status	"pending"
origin	string	No	Filter by origin	"web"
model	string	No	Filter by model	"standard"
excludeIds	array	No	Exclude appointments by IDs	["123e4567-e89b-12d3-a456-426614174000"]
lang	string	No	Preferred language	"en"
blocked	boolean	No	Include blocked appointments	false
fields	array	No	Fields to include in the response	["id","title","startAt","endAt"]
page	number	No	Page number	1
limit	number	No	Results per page	20

🧩 Request Examples

Basic List Request

curl -X GET "https://openapi.onlive.site/api/v2/appointments" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature"

Filtered List Request

curl -X GET "https://openapi.onlive.site/api/v2/appointments?status=pending&startDate=2025-05-01T00:00:00Z&endDate=2025-05-31T23:59:59Z" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature"

📤 Response Format (HTTP 200)

{
  "items": [
    {
      "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]"
        }
      ],
      "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
    }
  ],
  "total": 45,
  "count": 10,
  "currentPage": 1,
  "totalPages": 5
}

❌ Error Responses

This endpoint follows the standard error format.

📘 Notes

1. Date Handling

   • All dates are in ISO 8601 format
   • Times are in UTC timezone
   • Date ranges are inclusive
   • Maximum date range is 6 months

2. Pagination

   • Default page size is 20
   • Maximum page size is 100
   • Page numbering starts at 1
   • Total count is included in metadata

3. Filtering

   • Multiple filters can be combined
   • Case-insensitive search
   • Partial matching for text fields
   • Exact matching for IDs

💡 Tips

1. Use pagination parameters (page and limit) to manage large result sets
2. Combine multiple filters to narrow down results
3. Use the search parameter for full-text search across appointments
4. Use date range filters to limit results to specific time periods
5. Keep date ranges reasonable to optimize response times
6. Cache results when appropriate

🔐 Required Permissions

1. View Single Appointment

   • Organization-level read permission
   • Calendar-specific read permission (if applicable)
   • Service-specific read permission (if appointment is tied to a service)

2. List Appointments

   • Organization-level list permission
   • Calendar-specific list permission (if filtering by calendar)
   • Service-specific list permission (if filtering by service)