createAppointment

This interface creates a new appointment in the connected CRM. It is called when a user schedules a new appointment from within App Connect's appointment panel.

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.
payload	An object describing the appointment to create. See Payload schema.

Payload schema

Property	Type	Description
title	string	The appointment title or subject.
summary	string	Notes or body text for the appointment.
startTimeUtc	string	ISO-8601 UTC timestamp for the appointment start time.
durationMinutes	number	Duration of the appointment in minutes.
contacts	array	(Optional) Array of contact IDs (strings or numbers) or contact objects with an id property to add as attendees.

Return value(s)

An object with the following properties:

Parameter	Description
appointmentId	The ID of the newly created appointment in the CRM.
appointment	The full appointment object representing the created record.

If the appointment cannot be created, return:

Parameter	Description
successful	false
returnMessage	An object with message, messageType, and ttl.

Example

return {
  appointmentId: "12345",
  appointment: {
    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: "",
    attendees: [{ id: 67890, name: "Jane Smith", type: "Contact" }]
  }
};

Reference

Clio

            description: e?.description ?? '',
            participantName: '',
            startTimeUtc: startUtc ? startUtc.toISOString() : null,
            durationMinutes,
            status: 'scheduled',
            contactId: '',
            attendees
        };
    });
    return { appointments };
}

async function createAppointment({ user, authHeader, payload }) {
    const calendarId = await getWriteableUserCalendarId({ user, authHeader });
    if (calendarId == null) {
        return {
            successful: false,
            returnMessage: {
                message: 'No writeable calendar found in Clio.',
                messageType: 'warning',
                ttl: 5000
            }
        };
    }

    const startAt = payload?.startTimeUtc ?? payload?.startTime ?? null;
    const durationMinutes = Number(payload?.durationMinutes ?? 0);
    const endAt = startAt ? moment.utc(startAt).add(durationMinutes, 'minutes').toISOString() : null;

    const toAttendee = (id) => {
        const n = typeof id === 'number' ? id : Number(id);
        if (!Number.isFinite(n)) return null;
        return { id: n, type: 'Contact' };
    };

    const attendees = (() => {
        if (Array.isArray(payload?.contacts) && payload.contacts.length) {
            return payload.contacts
                .map(c => (c && typeof c === 'object' ? toAttendee(c.id) : toAttendee(c)))
                .filter(Boolean);
        }
        return [];
    })();

    const data = {
        calendar_owner: { id: calendarId },
        summary: payload?.title ?? payload?.summary ?? 'Appointment',
        description: payload?.summary ?? '',
        start_at: startAt,
        end_at: endAt,
        send_email_notification: false,
        ...(attendees.length ? { attendees } : {})
    };