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.

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

    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,
            title: e?.summary ?? '',
            description: e?.description ?? '',
            participantName: '',
            startTimeUtc: startUtc ? startUtc.toISOString() : null,
            durationMinutes,
            status: 'scheduled',
            contactId: '',
            attendees
        };
    });

    const hasCustomRange = range
        && typeof range === 'object'
        && !Array.isArray(range)
        && typeof range.startDate === 'string'