API Documentation

ScheduCal enables scheduling software developers to send, update, and cancel real calendar invitations instead of emails with ICS files.

Overview

Endpoint and API Authentication

When you register, you are provided with an API key and secret as well as the REST API endpoint. The endpoint and key will never change. The API secret can be regenerated upon request.

Dates and Time Zones

Dates are required to be in full ISO 8601 UTC format. Both dates and times are required. Seconds may be supplied as :00 and are required. (e.g. "YYYY-MM-DDThh:mm:ss")

Microsoft Graph calendars limit the time zone identifiers that can be used for appointments. Only the time zones in this list are supported.

Names and Email Addresses

Names and email addresses are optional when an appointment is initially created. For example, a webinar appointment or a session at a conference can be created and then attendees can be added later when they register.

API Calls

Create Appointment

Creates a new calendar appointment and returns a unique ID for that appointment. Use this ID to modify, cancel, or send invitations for the appointment.

POST /api/v1/appointments
Request Body
{
  "apiKey": "<api key>",
  "apiSecret": "<api secret>",
  "appointmentSubject": "string (e.g. 'Haircut'), Email subject of calendar invitation",
  "appointmentBody": "string (e.g. '30-minute haircut with Casey'), Email body of calendar invitation",
  "appointmentStart": "dateTime (e.g. '2024-01-09T13:00:00')",
  "appointmentTimeZone": "time zone (e.g. 'America/Los_Angeles')",
  "appointmentEnd": "time (e.g. '2024-01-09T13:15:00')",
  "appointmentLocation": "string (optional) (e.g. 'The Salon')",
  "name": "string (optional) (e.g. 'First Last')",
  "address": "string (optional) (e.g. 'email@domain.com')"
}

Update Appointment

Updates an existing calendar appointment and sends the update to all invitees.

PUT /api/v1/appointments/{appointmentId}
Request Body
{
  "apiKey": "<api key>",
  "apiSecret": "<api secret>",
  "appointmentSubject": "string (optional) (e.g. 'Updated subject')",
  "appointmentBody": "string (optional) (e.g. 'Updated body')",
  "appointmentStart": "dateTime (e.g. '2024-01-09T16:00:00')",
  "appointmentTimeZone": "time zone (e.g. 'America/Phoenix')",
  "appointmentEnd": "time (e.g. '2024-01-09T17:00:00')",
  "appointmentLocation": "string (optional) (e.g. 'Updated location')"
}

Cancel Appointment

Cancels an existing calendar appointment and notifies all participants.

DELETE /api/v1/appointments/{appointmentId}
Request Body
{
  "apiKey": "<api key>",
  "apiSecret": "<api secret>",
  "comment": "string (optional) (e.g. 'Cancellation Reason')"
}

Send Appointment Invitation

Sends an invitation to a contact for an existing appointment, such as adding another attendee to a webinar.

POST /api/v1/appointments/{appointmentId}/invitations
Request Body
{
  "apiKey": "<api key>",
  "apiSecret": "<api secret>",
  "name": "string (e.g. 'First Last')",
  "address": "string (e.g. 'name@domain.com')"
}

Download the Postman collection here