listAppointments

This interface retrieves upcoming appointments from the connected CRM so they can be displayed within App Connect's appointment panel. It is called whenever a user opens or refreshes the appointments view.

Input parameters

Parameter	Description
user	An object describing the Chrome extension user associated with the action that triggered this interface.
authHeader	The HTTP Authorization header to be transmitted with the API request to the target CRM.
range	(Optional) An object with startTime and endTime ISO-8601 strings defining the window of appointments to fetch.
mineOnly	(Optional) Boolean. When true, return only appointments owned by the current user.

Return value(s)

An object with the following property:

Parameter	Description
appointments	An array of appointment objects.

Appointment object

Property	Type	Description
id	string	The unique identifier of the appointment in the CRM.
thirdPartyAppointmentId	string	Same as id — the CRM's native ID for the appointment.
title	string	The appointment title or subject.
description	string	Notes or body text for the appointment.
startTimeUtc	string	ISO-8601 UTC timestamp of the appointment start time.
durationMinutes	number	Duration of the appointment in minutes.
status	string	Current status. Typically "scheduled", "cancelled", or "confirmed".
contactId	string	ID of the primary contact associated with the appointment (empty string if none).
attendees	array	Array of attendee objects, each with id, name, and type.

Example

return {
  appointments: [
    {
      id: "12345",
      thirdPartyAppointmentId: "12345",
      title: "Intake call with Jane Smith",
      description: "Initial consultation",
      startTimeUtc: "2024-03-15T14:00:00.000Z",
      durationMinutes: 60,
      status: "scheduled",
      contactId: "67890",
      attendees: [
        { id: 67890, name: "Jane Smith", type: "Contact" }
      ]
    }
  ]
};

Reference

Clio

    const externalPropertyPayload = existingProp?.id != null
        ? [{ id: existingProp.id, name, value: `${value}` }]
        : [{ name, value: `${value}` }];

    await axios.patch(
        `https://${user.hostname}/api/v4/calendar_entries/${appointmentId}.json`,
        { data: { external_properties: externalPropertyPayload } },
        { headers: { 'Authorization': authHeader } }
    );
}

async function listAppointments({ user, authHeader, range, mineOnly }) {
    const listRes = await axios.get(
        `https://${user.hostname}/api/v4/calendar_entries.json`,
        {
            headers: { 'Authorization': authHeader },
            params: {
                fields: 'id,summary,start_at,end_at,description,attendees{id,name,type}'
            }
        }
    );

    const entries = listRes?.data?.data ?? [];

    const appointments = entries.map(e => {
        const startUtc = e?.start_at ? moment.parseZone(e.start_at).utc() : null;
        const endUtc = e?.end_at ? moment.parseZone(e.end_at).utc() : null;
        const durationMinutes = (startUtc && endUtc)
            ? Math.max(0, Math.round(endUtc.diff(startUtc, 'minutes', true)))
            : 0;

        const id = e?.id != null ? `${e.id}` : null;
        const attendees = (e?.attendees ?? [])
            .map(a => (a?.id != null ? { id: a?.id, name: a?.name, type: a?.type } : null))
            .filter(Boolean);
        return {
            thirdPartyAppointmentId: id,
            id,