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/v1/appointments/{appointmentId}

🔒 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/v1/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",
  "start": "2025-03-10T08:00:00.000Z",
  "end": "2025-03-10T08:30:00.000Z",
  "event": null,
  "reminders": [
    {
      "time": 10,
      "unit": "m"
    }
  ],
  "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",
  "state": "pending",
  "blocked": false,
  "origin": "onlive_public",
  "organizationId": "26d47eec-c742-4b1c-9d70-9a1486260abd",
  "userGroupId": "1be7bf10-5c72-480b-b0d7-1c2bb023225d"
}

❌ Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid appointment ID format",
  "errors": [
    {
      "field": "appointmentId",
      "message": "Must be a valid UUID"
    }
  ]
}

403 Forbidden

{
  "statusCode": 403,
  "message": "Insufficient permissions to access the appointment"
}

404 Not Found

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

🔹 List Appointments

Retrieve a paginated list of appointments with optional filtering.

Endpoint Details

GET /openapi/v1/appointments

📝 Query Parameters

Parameter	Type	Required	Description	Example
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
page	number	No	Page number for pagination (default: 1)	1
limit	number	No	Results per page (default: 20)	20
state	string	No	Filter by appointment state	pending
calendarIds	array	No	Filter by calendar UUIDs	["af6c6be0-689a-4cf3-a8c8-550dd97b3a6b"]
serviceId	string	No	Filter by service UUID	01392598-e4b2-4810-ac7c-8c9cf4286a26
userGroupId	string	No	Filter by user group UUID	1be7bf10-5c72-480b-b0d7-1c2bb023225d
search	string	No	Full-text search across appointments	"Test Drive"

🧩 Request Examples

Basic List Request

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

Filtered List Request

curl -X GET "https://openapi.onlive.site/api/v1/appointments?state=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",
      "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
    }
  ],
  "total": 45,
  "count": 10,
  "currentPage": 1,
  "totalPages": 5
}

❌ Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid input parameters",
  "errors": [
    {
      "field": "startDate",
      "message": "Must be a valid ISO 8601 date"
    }
  ]
}

403 Forbidden

{
  "statusCode": 403,
  "message": "Insufficient permissions to list appointments"
}

📘 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)