Create Calendar API V2

Synopsis

This API function creates a calendar defined in the JSON. The response will return an iCalendar file for download. Event details like title, description, location, start/end date and time, timezone, and “all-day- event” may be provided.

• A calendar must have some data added in the request.
• All calendar information is mandatory except “all-day-event”. The request will fail if any of the required information is missing.
• The date and time added in the “event-start-datetime” and “event-end-datetime” are converted to UTC and used in the iCalendar file.
• If the datetime value contains the timezone offset or any indication of timezone, then the timezone part of the datetime string is ignored and the event-timezone value is considered.
• The event can be set for the entire day by setting the “all-day-event” to the boolean value true i.e. the event will start at 12:00am UTC of the event start date and will end at 11:59pm UTC of the event end date.

Request: JSON

curl -X POST \ 
     -H "x-api-key: API_KEY" \
     -H "content-type: application/json" -d '
      {
          "action": "createcalendar",
          "event-title": "EVENT_TITLE",
          "event-description": "EVENT_DESCRIPTION",
          "event-location": "EVENT_LOCATION",
          "event-start-datetime": "EVENT_START_DATE_AND_TIME",
          "event-end-datetime": "EVENT_END_DATE_AND_TIME",
          "event-timezone": "EVENT_TIMEZONE",
          "all-day-event": true/false,
      }' \
  "API_ENDPOINT_URL"

Success Response: JSON

Output the iCalendar file to download (.ics file)
Content-type: text/calendar; charset=utf-8;
Content-Disposition: inline; filename=calendar.ics;

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//GENERIC//NONSGML iCal v1.0//EN
BEGIN:VEVENT
UID:UNIQUE_IDENTIFIER
DTSTAMP:DATE_TIME_STAMP
SUMMARY;ENCODING=QUOTED-PRINTABLE;CHARSET=UTF-8:EVENT_TITLE
DTSTART:EVENT_START_DATE_AND_TIME
DTEND:EVENT_END_DATE_AND_TIME
LOCATION;ENCODING=QUOTED-PRINTABLE;CHARSET=UTF-8:EVENT_LOCATION
DESCRIPTION;ENCODING=QUOTED-PRINTABLE;CHARSET=UTF-8:EVENT_DESCRIPTION
END:VEVENT
END:VCALENDAR

Failure Response: JSON

{
    "status": "failure",
    "error-code": "ERROR_CODE",
    "error-info": "ERROR_INFO",
}

Request Parameters

Param Name	Optional/Mandatory; Datatype	Description
x-api-key	Mandatory; Alphanumeric	Authentication Key for your account to access API service. Unique Alphanumeric Key can be reset under your Account->API Settings. Case-sensitive.
action	Mandatory; String	Explains the action for this API Request. Value is Case-Insensitive.
event-title	Mandatory; String	Title of the calendar event.
event-description	Mandatory; String	Description of the event.
event-location	Mandatory; String	Location of the event.
event-start-datetime	Mandatory; Date Time	Event start date time. Accepts ISO8601 Date format.
event-end-datetime	Mandatory; Date Time	Event end date time. Accepts ISO8601 Date format.
event-timezone	Mandatory; String	Time zone of the event. Accepts tz database time zone names.
all-day-event	Optional; Boolean	Set to true if the event is an all day event. Default: false

Response Parameters

Param Name	Presence	Description
status	Error Response	“failure”
error-code	Error Response	Error code associated with the error.
error-info	Error Response	Error message explaining the error code.

Request Example: JSON

curl -X POST \ 
     -H "x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     -H "content-type: application/json" -d '
      {
          "action": "createcalendar",
          "event-title": "Dunder Mifflin Christmas Party",
          "event-description": "Ugly sweaters encouraged! Also bring a gift for Yankee Swap!",
          "event-location": "Fake Address",
          "event-start-datetime": "2021-12-17T11:30:00Z",
          "event-end-datetime": "2021-12-17T13:30:00Z",
          "event-timezone": "America/New_York",
          "all-day-event": false
      }' \
  "API_ENDPOINT_URL"

Response: Success

Output the iCalendar file to download (.ics file)
Content-type: text/calendar; charset=utf-8;
Content-Disposition: inline; filename=calendar.ics;

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//GENERIC//NONSGML iCal v1.0//EN
BEGIN:VEVENT
UID:20211210T141205Z-1441339694
DTSTAMP:20211210T141205Z
SUMMARY;ENCODING=QUOTED-PRINTABLE;CHARSET=UTF-8:Dunder Mifflin Christmas Party
DTSTART:20211217T113000Z
DTEND:20211217T133000Z
LOCATION;ENCODING=QUOTED-PRINTABLE;CHARSET=UTF-8:Fake Address
DESCRIPTION;ENCODING=QUOTED-PRINTABLE;CHARSET=UTF-8:Ugly sweaters encouraged! Also bring a gift for Yankee Swap!
END:VEVENT
END:VCALENDAR

Response: Failure

{
    "status": "failure",
    "error-code": "E1703",
    "error-info": "Title cannot be empty for iCalendar."
}