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.
status	string	(Optional) Non-empty initial status, such as scheduled. Passed to the connector; supported values and behavior depend on the CRM.
contacts	array	(Optional) Array of contact IDs (strings or numbers) or contact objects with an id property to add as attendees.

Contact objects may include type, contactType, name, and other client contact metadata. The server validates the contact ID and forwards the reference to the connector. Omitting status preserves the connector's default create behavior.

Contact IDs may be non-empty strings, including UUIDs and alphanumeric CRM IDs, or positive integers. String IDs are not required to be numeric.

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

    return {
        id: calendarEntry?.id != null ? `${calendarEntry.id}` : null,
        participantName: props[APPOINTMENT_EXTERNAL_PROPERTIES.participantName]?.value ?? attendee?.name ?? null,
        contactId,
        contactType,
        attendeeIds,
        title: props[APPOINTMENT_EXTERNAL_PROPERTIES.title]?.value ?? calendarEntry?.summary ?? null,
        summary: calendarEntry?.description ?? null,
        startTimeUtc: startAt ?? null,
        durationMinutes,
        status: props[APPOINTMENT_EXTERNAL_PROPERTIES.status]?.value ?? 'tentative'
    };
}

async function getWriteableUserCalendarId({ user, authHeader }) {
    const res = await axios.get(
        `https://${user.hostname}/api/v4/calendars.json`,
        {
            headers: { 'Authorization': authHeader },
            params: {
                owner: true,
                writeable: true,
                visible: true,
                type: 'UserCalendar',
                order: 'id(desc)',
                limit: 1,
                fields: 'id,type,permission,visible'
            }
        }
    );
    const calendarId = res?.data?.data?.[0]?.id;
    if (calendarId == null) {
        const fallbackRes = await axios.get(
            `https://${user.hostname}/api/v4/calendars.json`,
            {
                headers: { 'Authorization': authHeader },
                params: {
                    writeable: true,
                    visible: true,
                    order: 'id(desc)',
                    limit: 1,
                    fields: 'id,type,permission,visible'
                }
            }
        );
        return fallbackRes?.data?.data?.[0]?.id ?? null;
    }
    return calendarId;
}

async function getCalendarEntryById({ user, authHeader, appointmentId }) {
    const res = await axios.get(
        `https://${user.hostname}/api/v4/calendar_entries/${appointmentId}.json`,