POST - Create a New Event

Purpose

This API is used to create a new event in a user's calendar.

Request URL

https://calendar.zoho.com/api/v1/calendars/<calendar_uid>/events

OAuth Scope

scope=ZohoCalendar.event.ALL

(or)

scope=ZohoCalendar.event.CREATE

scope=ZohoMeeting.meeting.ALL (Needs to be added while adding meetings to the event)

ALL - Grants full access to events.

CREATE - Grants permission to create events.

Path Parameters

calendar_uid string, mandatory
- This parameter represents the unique identifier for the calendar in which a new event is created.

Query Parameters

eventdata JSONObject, mandatory
This JSON object is passed to define or update the data of a particular event in the calendar using the following keys and values.
Input JSON keys:
- title string
  Specifies the title of the event to be added.
- dateandtime JSONObject, mandatory
  Send JSON Object of the start time, end time in Unix time format along with the time zone information, in case, different from the current user time zone.
  - start string, mandatory
    Specifies the start date and time of the event. Use the following formats:
    For a specific time: yyyyMMdd'T'HHmmss'Z' in GMT format (e.g., 20241028T103000Z).
    For an all-day event: yyyyMMdd (e.g., 20241028).
  - end string, mandatory
    Specifies the end date and time of the event. Use the following formats:
    For a specific time: yyyyMMdd'T'HHmmss'Z' in GMT format (e.g., 20241028T103000Z).
    For an all-day event: yyyyMMdd (e.g., 20241028).
  - timezone string
    Mention the timezone in which the event is being created.
- isallday boolean
  Specifies whether the event is an all-day event or not. Allowed values: true | false
  - true - If true, use all-day event format in dateandtime JSONobject.
  - false
- isprivate boolean
  Specifies whether the event is private or not. Allowed values: true | false
  - true - When true, the event details are hidden from others, even if the calendar is public or shared, except for users with delegate permissions.
  - false - The event is public.
- url string
  Specifies the URL details that need to be shared for the event, along with the description, if any. Example: "https://mail.zoho.com"
- location string
  Specifies the location details for the event. Maximum length- 255 characters.
- description string
  Specifies the description of the event, to provide more details about the event to the attendees. Maximum length- 10000 characters.
- richtext_description string
  This parameter is used to provide a rich-text formatted description for the event. If the description includes formatting (e.g., bold, italic, links), it should be provided in richtext_description. Maximum length- 12000 characters. Note: Either description or richtext_description should be sent in the API request, but not both. If both fields are sent, there is a risk of one overwriting the other.
- color string
  Specifies the hex-color for the event. Use this to set a specific color for the event that differs from the default color. Example- #E574B0
- attendees JSONArray
  - This parameter is used to include the attendee details for the event.
  - Example: "attendees": [{"email":"user1@domain.com", "permission":"1"},{"email":"user2@domain.com","permission":"1"}]
  - This JSON Array includes the below parameters as JSONObject:
    - email string, mandatory
      Specifies the email id of the attendee.
    - zid long
      Specifies the zuid of the attendee.
    - permission integer
      Specifies the attendee's permission for the event.
      Allowed values : 0 | 1 | 2 | 3
      0 - Guest
      1 - View
      2 - Invite
      3 - Edit
    - attendance integer
      Specifies the attendance of the attendee.
      Allowed values : 0 | 1 | 2
      0- Non-participant
      1- Required participant
      2 - Optional participant
- group_attendees JSONArray
  - This parameter is used if group is added as attendee.
  - Example: "group_attendees":[{"zid":"123565"}]
  - This JSONArray includes the below parameters as JSONObject:
    - zid long, mandatory
      Specifies the zuid of the group.
- reminders JSONArray
  - Specifies the type of reminders to be set for the event.
  - Example: "reminders":[{"action": "email", "minutes": 30}, {"action": "popup", "minutes": 15}]
  - This JSONArray includes the below parameters as JSONObject:
    - action string
      Specifies the reminder type.
      Allowed values: email | popup | notification
    - minutes integer, mandatory
      Specifies the time before the event (in minutes) when the reminder will trigger.
- calendar_alarm boolean
  - Specifies whether to enable a calendar alarm for the event.
  - Allowed values: true | false
    - true - Enables a calendar alarm for the event.
    - false - Disables the calendar alarm.
- notify_attendee integer
  - Used to notify the attendees of the event.
  - Allowed values : 0 | 1 | 2
    - 0- None.
    - 1- Notify attendees only.
    - 2- Notify both attendees and myself.
- attach JSONObject
  - This parameter allows files to be attached to an event by including their unique file IDs in a comma-separated format.
  - This JSONObject has the below parameters:
    - fileId string
      Specifies the file(s) to be attached to the event. Multiple file IDs should be separated by commas.
      The file IDs correspond to files previously uploaded and retrievable through the Get Attachment API.
- transparency integer
  - Specifies whether the event should be added to the free/busy schedule.
  - Allowed values : 0 | 1
    - 0 - Add to free/busy schedule.
    - 1 - Don't add to your free/busy schedule. The grid will be shown as free even if events are present at that time.
- conference string
  - Specifies the conference option to associated with the event.
  - Allowed values : zmeeting | none
- notifyType integer
  - Specifies the notification type for the event. Currently, only the default notification type is supported.
  - Allowed values : 1
    - 1 - Default Notification
- allowForwarding boolean
  - Specifies whether the attendees are allowed to forward the event or not.
  - Allowed values: true | false
    - true - The attendees are allowed to forward the event.
    - false - The attendees are not allowed to forward the event.
- rrule string
  - This parameter is used to create repeat/recurring events.
  - Allowed values :
    - FREQ string
      Specifies the frequency of the recurrence.
      Allowed values: DAILY | WEEKLY | MONTHLY | YEARLY
    - INTERVAL integer
      Specifies the interval between each occurrence.
      For example:
      INTERVAL = 1 - Event occurs everyday.
      INTERVAL = 2 - Event occurs every 2 days.
      Default value is 1
    - COUNT integer
      Specifies the number of times the event occurs.
    - BYDAY string
      Specifies the days of the week on which the event occurs.
      Used when FREQ is WEEKLY, MONTHLY, or YEARLY.
      Example :
      In Monthly and Yearly Events: 4FR (indicating the fourth Friday).The first number defines which weekday in the month: possible values are 1 (first), 2 (second), 3 (third), 4 (fourth), and -1 (last). The two-letter code represents the day of the week: possible values are MO (Monday), TU (Tuesday), WE (Wednesday), TH (Thursday), FR (Friday), SA (Saturday), and SU (Sunday).
      In Daily Events: Possible values depend on the weekdays set in the settings (e.g., MO, TU, WE, TH, FR, SA, SU).
      In Weekly Events: Possible values are MO, TU, WE, TH, FR, SA, SU
    - UNTIL string
      Specifies the end date of the recurrence.
      Use yyyyMMdd'T'HHmmss'Z' in GMT format or yyyyMMdd for all-day events.
      Example: UNTIL=20250818T094500Z means the event repeats until 18 Aug 2025.
    - BYSETPOS integer
      Specifies the occurrence of the week in a month or year.
      Used when FREQ is MONTHLY or YEARLY.
      Possible values are: 1 - First, 2 - Second, 3 - Third, 4 - Fourth, -1 - Last.
      For example, 1MO for the first Monday, -1MO for the last Monday.
    - BYMONTHDAY integer
      Specifies the day of the month.
      Used when FREQ is MONTHLY or YEARLY.
      Values range from 1 to 31.
    - BYMONTH integer
      Specifies the month of the year.
      Used when FREQ is YEARLY.
      Values range from 1 (January) to 12 (December).
  - Example:
    - For daily recurring event :
      "FREQ=DAILY;COUNT=5;INTERVAL=1" (Every day for 5 occurrences.)
      "FREQ=DAILY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR;COUNT=5" (Every weekday for 5 occurrences.)
    - For weekly recurring event:
      "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU;UNTIL=20250817T064600Z" (Every week on Monday,Tuesday Until 17 Aug 2025.)
    - For monthly recurring event:
      "FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=17" (On the 17th day of every month.)
      "FREQ=MONTHLY;INTERVAL=1;BYDAY=TU;BYSETPOS=-1;COUNT=2" (Last Tuesday of every month for 2 occurrences.)
    - For yearly recurring event:
      "FREQ=YEARLY;INTERVAL=1;BYDAY=MO;BYSETPOS=3;BYMONTH=7" (Every third Monday of July each year.)
      "FREQ=YEARLY;INTERVAL=1;BYMONTH=7;BYMONTHDAY=17;COUNT=1" (On July 17 every year, for 1 occurrence.)
- repeat JSON Array (Use either rrule or repeat parameter to create recurring/repeat events)
  This parameter is used to add/create repeat events.This JSONArray includes below parameters as JSONObject:
  - Allowed values :
    - freq string
      Specifies the frequency of the recurrence.
      Allowed values: DAILY | WEEKLY | MONTHLY | YEARLY
    - interval integer
      Specifies the interval between each occurrence.
      For example:
      interval = 1 - Event occurs everyday.
      interval = 2 - Event occurs every 2 days.
    - count integer
      Specifies the number of times the event occurs.
    - byday string
      Specifies the days of the week on which the event occurs.
      Used when FREQ is WEEKLY, MONTHLY, or YEARLY.
      Example :
      In Monthly and Yearly Events: 4FR (indicating the fourth Friday).The first number defines which weekday in the month: possible values are 1 (first), 2 (second), 3 (third), 4 (fourth), and -1 (last). The two-letter code represents the day of the week: possible values are MO (Monday), TU (Tuesday), WE (Wednesday), TH (Thursday), FR (Friday), SA (Saturday), and SU (Sunday).
      In Daily Events: Possible values depend on the weekdays set in the settings (e.g., MO, TU, WE, TH, FR, SA, SU).
      In Weekly Events: Possible values are MO, TU, WE, TH, FR, SA, SU
    - until string
      Specifies the end date of the recurrence.
      Use yyyyMMdd'T'HHmmss'Z' in GMT format or yyyyMMdd for all-day events.
      Example: UNTIL=20250818T094500Z means the event repeats until 18 Aug 2025.
    - bymonthday integer
      Specifies the day of the month.
      Used when freq is MONTHLY or YEARLY.
      Values range from 1 to 31.
    - bymonth integer
      Specifies the month of the year.
      Used when freq is YEARLY.
      Values range from 1 (January) to 12 (December).
  Examples:
  - For daily recurring event :
    "repeat": [{"freq": "daily", "interval": "1", "count": 5}] (Every day for 5 occurrences)
    "repeat": [{"freq": "daily", "byday": "MO,TU,WE,TH,FR", "count": 5}] (Every weekday for 5 occurrences)
  - For weekly recurring event:
    "repeat": [{"freq": "weekly", "interval": "1", "byday": "MO,TU", "until": "20241121T040000"}] (Every week on Monday and Tuesday until November 21, 2024)
  - For monthly recurring event:
    "repeat": [{"freq": "monthly", "interval": "1", "bymonthday": 27}] (On the 27th day of every month)
    "repeat": [{"freq": "monthly", "byday": "-1TU", "interval": "1", "count": 2}] (Last Tuesday of every month, for 2 occurrences)
  - For yearly recurring event:
    "repeat": [{"freq": "yearly", "interval": "1", "bymonth": 11, "bymonthday": 29, "count": "1"}] (On November 29 every year, for 1 occurrence)
    "repeat": [{"freq": "yearly", "byday": "3FR", "bymonth": 11}] (Every third Friday of November each year)

Note:

If User A creates an event with allowForwarding set to "true" and adds User B, User B can forward the event to User C. User C will receive an invite email, and the event will only be added to their calendar if they accept the invitation.
When sending parameters in Postman, ensure they are URL-encoded.

Sample Request

Copiedhttps://calendar.zoho.com/api/v1/calendars/849d6badb4e04acc91860c43db0fb109/events?eventdata={
    "reminders": [
        {
            "action": "popup",
            "minutes": -60
        }
    ],
    "dateandtime": {
        "timezone": "Asia/Kolkata",
        "start": "20221130T180000Z",
        "end": "20221130T183000Z"
    },
    "attach": {
        "fileId": "1669786154601000001,1669786188806000001"
    },
    "title": "test invitation",
    "attendees": [
        {
            "email": "user@domain.com",
            "status": "NEEDS-ACTION"
        }
    ],
    "richtext_description": "<div><ul><li><u>Checking</u><u><br /></u></li><li>richtext<br /></li></ul></div>",
    "conference": "zmeeting"
}

Sample Response

Copied{
    "events": [
        {
            "reminders": [
                {
                    "minutes": "-60",
                    "action": "popup"
                }
            ],
            "enable_eventmanagement": false,
            "conference": "zmeeting",
            "role": "organizer",
            "color": "",
            "orgDName": "user10",
            "richtext_description": "<div><ul><li><u>Checking</u><u><br /></u></li><li>richtext<br /></li></ul></div>",
            "calid": "293770000000002003",
            "description": "Checking\n\nrichtext\n\n\n",
            "has_attachment": true,
            "title": "test invitation",
            "calendar_alarm": false,
            "duration": "1800000",
            "uid": "78fb74a782f94f7bb307201f5b43f086@zoho.com",
            "createdby": "user10@domain.com",
            "etype": "EVENT",
            "attach": [
                {
                    "fileName": "",
                    "size": 0,
                    "contentType": "",
                    "fileId": "1669788842017000001"
                },
                {
                    "fileName": "",
                    "size": 0,
                    "contentType": "",
                    "fileId": "1669788842020000002"
                }
            ],
            "id": "293770000000010005",
            "app_data": {
                "meetingdata": {
                    "meetinglink": "https://meeting.zoho.com/meeting/meeting-start?key=1074329242"
                }
            },
            "isApproved": true,
            "viewEventURL": "https://calendar.zoho.com/zc/viewevent/849d6badb4e04acc91860c43db0fb109_EID78fb74a782f94f7bb307201f5b43f086@zoho.com",
            "dateandtime": {
                "timezone": "Asia/Kolkata",
                "start": "20221130T233000+0530",
                "end": "20221201T000000+0530"
            },
            "lastmodifiedtime": "20221130T061401Z",
            "isprivate": false,
            "rsvpStatus": 1,
            "attendees": [
                {
                    "dName": "User2",
                    "id": 70256353,
                    "privilege": 1,
                    "email": "user@domain.com",
                    "attendance": 1,
                    "status": "NEEDS-ACTION"
                },
                {
                    "dName": "",
                    "id": 70421263,
                    "privilege": 4,
                    "email": "user10@domain.com",
                    "attendance": 1,
                    "status": "ACCEPTED"
                }
            ],
            "createdtime_millis": "1669788841981",
            "createdtime": "20221130T061401Z",
            "user_timezone": "Asia/Kolkata",
            "notifyType": 0,
            "estatus": "added",
            "organizer": "user10@domain.com",
            "isallday": false,
            "transparency": 0,
            "conference_data": {
                "meetingdata": {
                    "zoho_meeting_id": "1074329242",
                    "meeting_id": "1074329242",
                    "meeting_link": "https://meeting.zoho.com/meeting/meeting-start?key=1074329242",
                    "status": "needsAction"
                }
            },
            "modifiedby": "user10@domain.com",
            "etag": "1669788841981",
            "caluid": "849d6badb4e04acc91860c43db0fb109",
            "multiday": false,
            "allowForwarding": false
        }
    ]
}