Table of Contents
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."
}