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; String	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`	Optional, Mandatory if dynamic calendar is added; String	Title of the calendar event.
`event-description`	Optional, Mandatory if dynamic calendar is added; String	Description of the event.
`event-location`	Optional, Mandatory if dynamic calendar is added; String	Location of the event.
`event-start-datetime`	Optional, Mandatory if dynamic calendar is added; String	Event start date time. Accepts ISO8601 Date format.
`event-end-datetime`	Optional, Mandatory if dynamic calendar is added; String	Event end date time. Accepts ISO8601 Date format.
`event-timezone`	Optional, Mandatory if dynamic calendar is added; 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."
}