Get Calendar Activities

Purpose

To retrieve calendar activities from CRM such as Meetings, Tasks, or Calls for a given view type(day/week/month). You can also get the calendar activities of a specific user or from a saved calendar view.

Endpoints

GET /__calendar_activities

Request Details

Request URL

{api-domain}/crm/{version}/__calendar_activities

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.settings.calendar.ALL
(or)
ZohoCRM.settings.calendar.READ

Parameters

modulestring, mandatory
The API name of the either Meetings, Tasks, or Calls module to fetch the calendar activities from. Use the Get Modules API for the API name of the module.
view_typestring, mandatory
The calendar granularity or time period to filter activities.Possible values are month to get the activities in that month, week to filter activities from that week, and day to get the activities of that day.
filtersJSON object, mandatory
JSON object to filter the response based on the Start_DateTime field of an activity. Note that you can filter only based on the Start_Datetime field using the equal comparator. Ensure to encode this parameter in the request. Example: %7B%22comparator%22%3A%22equal%22%2C%22field%22%3A%7B%22api_name%22%3A%22Start_DateTime%22%7D%2C%22value%22%3A%222019-05-01T00%3A00%3A00%2B05%3A30%22%7D for {"comparator":"equal","field":{"api_name":"Start_DateTime"},"value":"2019-05-01T00:00:00+05:30"}.
You can also apply filter on groups using the and or or operators.
user_idsstring, optional if you include the view_id parameter
The IDs of the users whose calendar activities you want to retrieve. You can specify up to 100 user IDs as comma-separated values. Use the Get Users API to get the users' IDs.
This parameter becomes mandatory if you do not include the view_idparameter.
view_idstring, optional if you include the user_ids parameter
The ID of a specific calendar view to retrieve calendar activities from. Use the Get Calendar Views API to get the details of different calendar views.
This parameter becomes mandatory if you do not include the view_idparameter.
includestring, optional
To include human-readable formatted values for date-time fields alongside their ISO8601 formats. Check the sample response for the structure of this key.
fieldsstring, optional
Comma-separated API names of the fields you want to retrieve when fetching the records. You can include a maximum of 50 field API names in this parameter. Use the GET Fields Metadata API to get the list of available fields in a module.
per_pageinteger, optional
The number of records you want to fetch per page. The default and the maximum possible value is 200. Accepts positive integer values only.
pageinteger, optional
To get the list of records from the respective pages. The default value is 1. Accepts positive integer values only.

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/__calendar_activities?module=Tasks&view_type=month&filters=%7B%22comparator%22%3A%22equal%22%2C%22field%22%3A%7B%22api_name%22%3A%22Start_DateTime%22%7D%2C%22value%22%3A%222019-05-01T00%3A00%3A00%2B05%3A30%22%7D&user_ids=554023000000235011&include=$formatted_values"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Response JSON keys

All_dayBoolean
Boolean key that represents if the event, task, or call happens for an entire day.
OwnerJSON object
Name, email address, and the unique ID of the owner of the record.
$shared_throughstring
Represents if the record was shared through data sharing rules.
Start_DateTimeISO8601 DateTime
The commencement date and time of the activity in the ISO8601 format.
Durationinteger
The duration in milliseconds that the activity lasted for.
$editableBoolean
Boolean key that represents whether the record is editable for that user.
ParticipantsJSON array
Name, email address, and the unique ID of the participants in this activity.
Event_Titlestring
The name of the event. Accepts alphanumeric and special characters.
$colour_codestring
The hexadecimal color code assigned to this activity in the UI calendar.
End_DateTimeISO8601 DateTime
The date and time in the ISO8601 format at which the activity concludes.
$completedBoolean
Boolean key that represents if the activity is completed.
idstring
Record ID of the call, task, or event.
$modulestring
The API name of the source module of the activity.
$formatted_valuesJSON object
Human-readable formatted values for date-time fields such as Start_DateTime , End_DateTime, alongside their ISO8601 formats. This object will be available only when you have included include=$formatted_values key-value in the parameters of the request.

Possible Errors

INVALID_REQUEST_METHODHTTP 400
The request method is incorrect.
Resolution: Use the HTTP GET method to make this API call. Any other request method will result in this error.
INVALID_DATAHTTP 400
You have specified an incorrect parameter in the request.
Resolution: Refer to the Parameters section for the list of accepted parameters.
INVALID_DATAHTTP 400
You have specified an incorrect value for the view_type parameter in the request.
Resolution: The possible values of the view_type parameter are day, week, and month.
INVALID_DATAHTTP 400
You have specified an incorrect user_id or view_id.
Resolution: Use the Get Users API and Get Calendar Views API to get the user ID and view ID, respectively.
INVALID_DATAHTTP 400
You have specified an incorrect value in the filters parameter or in an incorrect format.
Resolution: The filters parameter takes a JSON object as it's value and supports only the equal comparator applied on the Start_DateTime field. Encode this value to avoid any errors.
INVALID_DATAHTTP 400
You have specified an incorrect operator for the group operator in the filters parameter.
Resolution: The filters parameter takes only and and or group operators.
DEPENDENT_FIELD_MISSINGHTTP 400
You have included the group operator but not the fields in the group for the filters parameter.
Resolution: You must include group operator, group, fields in the filters parameter in the request.
EXPECTED_FIELD_MISSINGHTTP 400
You have not included group or field for the filters parameter.
Resolution: You must include either group or field for the filters parameter.
DEPENDENT_FIELD_MISMATCHHTTP 400
You have specified an unsupported comparator in the filters parameter.
Resolution: You can only apply equal comparator for the Start_DateTime field in the filters parameter.
REQUIRED_PARAM_MISSINGHTTP 400
You have not specified one or more mandatory parameters.
Resolution: Refer to the Parameters section for the mandatory and optional parameters for this request.
EXPECTED_PARAM_MISSINGHTTP 400
You have not specified view_id or user_ids parameter in the request.
Resolution: You must include either view_id or user_ids parameter in the request.
INVALID_MODULEHTTP 400
You have specified an incorrect module name in the request.
Resolution: Refer to Get Modules API for the API names of the module.
NOT_SUPPORTEDHTTP 400
The module you have specified in the request does not support calendar activities.
Resolution: You can get the calendar activities only for Tasks, Meetings, and Calls modules.
AUTHORIZATION_FAILEDHTTP 400
You do not have sufficient permission to view the calendar activities of the user(s).
Resolution: Contact your system administrator.
OAUTH_SCOPE_MISMATCHHTTP 401
The access token you have used to make this API call does not have the required scope.
Resolution: Generate a new access token with the scope mentioned in the Scopes section.
NO_PERMISSIONHTTP 403
The user does not have permission to view calendar preferences.
Resolution: Contact your system administrator.
INVALID_URL_PATTERNHTTP 404
The request URL is incorrect.
Resolution: Specify a valid request URL. Refer to the Request URL section for the right URL.
INTERNAL_ERRORHTTP 500
Unexpected and unhandled exception in the server.
Resolution: Contact the support team at support@zohocrm.com.

Sample Response

Copied{
    "__calendar_activities": [
        {
            "All_day": true,
            "Owner": {
                "name": "Patricia Boyle",
                "id": "554023000000235011",
                "email": "p.boyle@zylker.com"
            },
            "$shared_through": null,
            "Start_DateTime": "2019-05-01T00:00Z",
            "Duration": 86399999,
            "$editable": false,
            "Participants": null,
            "Event_Title": "Approval Follow-up task",
            "$colour_code": null,
            "End_DateTime": "2019-05-01T23:59:59.999Z",
            "$completed": true,
            "id": "554023000000518043",
            "$module": "Tasks",
            "$formatted_values": {
                "Start_DateTime": {
                    "date": "May 1, 2019",
                    "component_value": "2019-05-01T00:00:00",
                    "time": "12:00 AM"
                },
                "End_DateTime": {
                    "date": "May 1, 2019",
                    "component_value": "2019-05-01T23:59:59",
                    "time": "11:59 PM"
                }
            }
        },
        {
            "All_day": true,
            "Owner": {
                "name": "Patricia Boyle",
                "id": "554023000000235011",
                "email": "p.boyle@zylker.com"
            },
            "$shared_through": null,
            "Start_DateTime": "2019-05-08T00:00Z",
            "Duration": 86399999,
            "$editable": false,
            "Participants": null,
            "Event_Title": "Contact Added",
            "$colour_code": null,
            "End_DateTime": "2019-05-08T23:59:59.999Z",
            "$completed": false,
            "id": "554023000000556043",
            "$module": "Tasks",
            "$formatted_values": {
                "Start_DateTime": {
                    "date": "May 8, 2019",
                    "component_value": "2019-05-08T00:00:00",
                    "time": "12:00 AM"
                },
                "End_DateTime": {
                    "date": "May 8, 2019",
                    "component_value": "2019-05-08T23:59:59",
                    "time": "11:59 PM"
                }
            }
        },
        {
            "All_day": true,
            "Owner": {
                "name": "Patricia Boyle",
                "id": "554023000000235011",
                "email": "p.boyle@zylker.com"
            },
            "$shared_through": null,
            "Start_DateTime": "2019-05-08T00:00Z",
            "Duration": 86399999,
            "$editable": false,
            "Participants": null,
            "Event_Title": "Contact Added",
            "$colour_code": null,
            "End_DateTime": "2019-05-08T23:59:59.999Z",
            "$completed": false,
            "id": "554023000000556089",
            "$module": "Tasks",
            "$formatted_values": {
                "Start_DateTime": {
                    "date": "May 8, 2019",
                    "component_value": "2019-05-08T00:00:00",
                    "time": "12:00 AM"
                },
                "End_DateTime": {
                    "date": "May 8, 2019",
                    "component_value": "2019-05-08T23:59:59",
                    "time": "11:59 PM"
                }
            }
        },
        {
            "All_day": true,
            "Owner": {
                "name": "Patricia Boyle",
                "id": "554023000000235011",
                "email": "p.boyle@zylker.com"
            },
            "$shared_through": null,
            "Start_DateTime": "2019-05-08T00:00Z",
            "Duration": 86399999,
            "$editable": false,
            "Participants": null,
            "Event_Title": "Contact Added",
            "$colour_code": null,
            "End_DateTime": "2019-05-08T23:59:59.999Z",
            "$completed": false,
            "id": "554023000000556139",
            "$module": "Tasks",
            "$formatted_values": {
                "Start_DateTime": {
                    "date": "May 8, 2019",
                    "component_value": "2019-05-08T00:00:00",
                    "time": "12:00 AM"
                },
                "End_DateTime": {
                    "date": "May 8, 2019",
                    "component_value": "2019-05-08T23:59:59",
                    "time": "11:59 PM"
                }
            }
        },
        {
            "All_day": true,
            "Owner": {
                "name": "Patricia Boyle",
                "id": "554023000000235011",
                "email": "p.boyle@zylker.com"
            },
            "$shared_through": null,
            "Start_DateTime": "2019-05-10T00:00Z",
            "Duration": 86399999,
            "$editable": false,
            "Participants": null,
            "Event_Title": "Task_Recurring_Daily",
            "$colour_code": null,
            "End_DateTime": "2019-05-10T23:59:59.999Z",
            "$completed": false,
            "id": "554023000000550037",
            "$module": "Tasks",
            "$formatted_values": {
                "Start_DateTime": {
                    "date": "May 10, 2019",
                    "component_value": "2019-05-10T00:00:00",
                    "time": "12:00 AM"
                },
                "End_DateTime": {
                    "date": "May 10, 2019",
                    "component_value": "2019-05-10T23:59:59",
                    "time": "11:59 PM"
                }
            }
        },
        {
            "All_day": true,
            "Owner": {
                "name": "Patricia Boyle",
                "id": "554023000000235011",
                "email": "p.boyle@zylker.com"
            },
            "$shared_through": null,
            "Start_DateTime": "2019-05-12T00:00Z",
            "Duration": 86399999,
            "$editable": false,
            "Participants": null,
            "Event_Title": "Task_Recurring_Daily",
            "$colour_code": null,
            "End_DateTime": "2019-05-12T23:59:59.999Z",
            "$completed": false,
            "id": "554023000000550038",
            "$module": "Tasks",
            "$formatted_values": {
                "Start_DateTime": {
                    "date": "May 12, 2019",
                    "component_value": "2019-05-12T00:00:00",
                    "time": "12:00 AM"
                },
                "End_DateTime": {
                    "date": "May 12, 2019",
                    "component_value": "2019-05-12T23:59:59",
                    "time": "11:59 PM"
                }
            }
        },
        {
            "All_day": true,
            "Owner": {
                "name": "Patricia Boyle",
                "id": "554023000000235011",
                "email": "p.boyle@zylker.com"
            },
            "$shared_through": null,
            "Start_DateTime": "2019-05-14T00:00Z",
            "Duration": 86399999,
            "$editable": false,
            "Participants": null,
            "Event_Title": "Task_Recurring_Daily",
            "$colour_code": null,
            "End_DateTime": "2019-05-14T23:59:59.999Z",
            "$completed": false,
            "id": "554023000000550039",
            "$module": "Tasks",
            "$formatted_values": {
                "Start_DateTime": {
                    "date": "May 14, 2019",
                    "component_value": "2019-05-14T00:00:00",
                    "time": "12:00 AM"
                },
                "End_DateTime": {
                    "date": "May 14, 2019",
                    "component_value": "2019-05-14T23:59:59",
                    "time": "11:59 PM"
                }
            }
        },
        {
            "All_day": true,
            "Owner": {
                "name": "Patricia Boyle",
                "id": "554023000000235011",
                "email": "p.boyle@zylker.com"
            },
            "$shared_through": null,
            "Start_DateTime": "2019-05-15T00:00Z",
            "Duration": 86399999,
            "$editable": false,
            "Participants": null,
            "Event_Title": "new",
            "$colour_code": null,
            "End_DateTime": "2019-05-15T23:59:59.999Z",
            "$completed": false,
            "id": "554023000000554004",
            "$module": "Tasks",
            "$formatted_values": {
                "Start_DateTime": {
                    "date": "May 15, 2019",
                    "component_value": "2019-05-15T00:00:00",
                    "time": "12:00 AM"
                },
                "End_DateTime": {
                    "date": "May 15, 2019",
                    "component_value": "2019-05-15T23:59:59",
                    "time": "11:59 PM"
                }
            }
        },
        {
            "All_day": true,
            "Owner": {
                "name": "Patricia Boyle",
                "id": "554023000000235011",
                "email": "p.boyle@zylker.com"
            },
            "$shared_through": null,
            "Start_DateTime": "2019-05-15T00:00Z",
            "Duration": 86399999,
            "$editable": false,
            "Participants": null,
            "Event_Title": "subject",
            "$colour_code": null,
            "End_DateTime": "2019-05-15T23:59:59.999Z",
            "$completed": false,
            "id": "554023000000554022",
            "$module": "Tasks",
            "$formatted_values": {
                "Start_DateTime": {
                    "date": "May 15, 2019",
                    "component_value": "2019-05-15T00:00:00",
                    "time": "12:00 AM"
                },
                "End_DateTime": {
                    "date": "May 15, 2019",
                    "component_value": "2019-05-15T23:59:59",
                    "time": "11:59 PM"
                }
            }
        }
    ],
    "info": {
        "per_page": 2000,
        "count": 9,
        "page": 1,
        "more_records": false
    }
}