Update Calendar Preferences

Purpose

Use this API to update the user's calendar configuration settings such as the working hours, holiday settings, week start preference, default activity durations, reminder configurations, notification channels, and CalDAV integration status.

Endpoints

PUT /settings/calendar/user_calendar_preferences

Request Details

Request URL

{api-domain}/crm/{version}/settings/calendar/user_calendar_preferences

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

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

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/calendar/user_calendar_preferences"
-X PUT
-d "@input.json"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Request JSON Keys

idstring, optional
The unique ID of the user calendar preference record to update. Use the Get Calendar Preferences API to retrieve the record ID.
activity_typeJSON array, optional
The types of activities to display in the calendar view. Accepted values are appointments, calls, events, and tasks.
caldav_detailsJSON object, optional
Represents the CalDAV integration settings. You can update the following key:
- caldav_status - Boolean - Set to true to enable CalDAV synchronization or false to disable it.
day_end_atstring, optional
Represents the time at which the user's working day ends. Specify the value in HH:MM:SS format (for example, "18:00:00" for 6 PM).
day_start_atstring, optional
Represents the time at which the user's working day starts. Specify the value in HH:MM:SS format (for example, "08:00:00" for 8 AM).
default_call_durationJSON object, optional
The default duration for calls created by the user in the calendar. For example, if the period is "minutes" and the unit is 60, the default call duration is 60 minutes. Specify the following keys:
- unit - integer - The numeric duration value (for example, 60).
- period - string - The time period unit (for example, "minutes" or "hours").
default_event_durationJSON object, optional
The default duration for events created by the user in the calendar. For example, if the period is "minutes" and the unit is 60, the default event duration is 60 minutes. Specify the following keys:
- unit - integer - The numeric duration value (for example, 60).
- period - string - The time period unit (for example, "minutes" or "hours").
hide_declined_eventsBoolean, optional
Set to true to hide events that the user has declined from the calendar view, or false to display them.
hide_eventsJSON object, optional
Configuration for automatically hiding older events from the calendar view after a specified number of days. Specify the following keys:
- enabled - Boolean - Set to true to enable automatic hiding of older events, or false to disable it.
- duration - JSON object - Specifies the cutoff period after which events are hidden. Includes the unit key (integer, for example, 30) for the numeric value.
holiday_1string, optional
The primary weekly holiday. Accepted values are sunday, monday, tuesday, wednesday, thursday, friday, and saturday.
holiday_2string, optional
The secondary weekly holiday. Accepted values are sunday, monday, tuesday, wednesday, thursday, friday, and saturday.
meeting_preferencesJSON array, optional
Represents the meeting service provider preferences for the user. Pass an empty array to reset the meeting preferences.
remindersJSON object, optional
Represents the complete reminder configuration for the user's calendar. Specify the following keys:
- notificationsJSON array
  The notification channels for calendar reminders. You can configure a maximum of 6 channels. Each object in this array can include the following keys:
  - type - string - The notification channel type. Accepted values are cisco, slack, google_chat, microsoft_teams, sms, and email.
  - turn_off_reminder - Boolean - Set to true to disable reminders for this channel, or false to enable them.
  - team_id - string - The team or workspace identifier for team-based channels such as Slack.
- remind_atJSON object
  The reminder timing configuration for different activity types. Specify any of the following JSON objects:
  - events - JSON object - Reminder configuration for events. Includes available (Boolean) to enable or disable the reminder, and reminder (JSON object) with unit (integer) and period (string) to specify how far in advance the reminder should trigger (for example, unit: 30, period: "minutes").
  - appointments - JSON object - Reminder configuration for appointments. Includes available (Boolean) and reminder (JSON object) with unit (integer) and period (string), similar to the events object.
  - all_day_events - JSON object - Reminder configuration for all-day events. Includes available (Boolean) and reminder (JSON object) with unit (integer) and period (string, for example, "days"), similar to the events object.
send_notification_appointmentBoolean, optional
Set to true to enable notifications for appointment reminders, or false to disable them.
send_notification_eventBoolean, optional
Set to true to enable notifications for event reminders, or false to disable them.
show_week_numberBoolean, optional
Set to true to display ISO week numbers in the calendar view, or false to hide them.
week_include_holidaysBoolean, optional
Set to true to include holidays when calculating weekly working hours, or false to exclude them.
week_starts_onstring, optional
The day the calendar week starts on. Accepted values are sunday, monday, tuesday, wednesday, thursday, friday, and saturday.

Note

The invitation_count key is read-only and cannot be updated using this API.

Sample Input

Copied{
    "user_calendar_preferences": [
        {
            "reminders": {
                "remind_at": {
                    "appointments": {
                        "reminder": {
                            "unit": 30,
                            "period": "minutes"
                        },
                        "is_available": true
                    },
                    "events": {
                        "reminder": {
                            "unit": 30,
                            "period": "minutes"
                        },
                        "is_available": true
                    },
                    "all_day_events": {
                        "reminder": {
                            "unit": 2,
                            "period": "days"
                        },
                        "is_available": true
                    }
                },
                "notifications": [
                    {
                        "type": "cliq",
                        "turn_off_reminder": false
                    },
                    {
                        "type": "email",
                        "turn_off_reminder": true
                    }
                ]
            },
            "shift_hours": {
                "is_shift": false
            },
            "holiday_1": "monday",
            "holiday_2": "tuesday",
            "hide_events": {
                "is_enabled": false,
                "duration": null
            },
            "day_end_at": "19:00:00",
            "hide_declined_events": true,
            "default_call_duration": {
                "unit": 30,
                "period": "minutes"
            },
            "meeting_preferences": null,
            "week_include_holidays": true,
            "day_start_at": "11:00:00",
            "activity_type": [
                "appointments",
                "calls"
            ],
            "caldav_details": {
                "caldav_status": false
            },
            "send_notification_event": true,
            "week_starts_on": "wednesday",
            "default_event_duration": {
                "unit": 30,
                "period": "minutes"
            },
            "send_notification_appointment": true,
            "show_week_number": false
        }
    ]
}

Possible Errors

INVALID_DATAHTTP 400
The input has a value of an invalid data type or an invalid value for the specified key.
Resolution: Refer to the "details" key in the response for the exact error. Refer to the Request JSON section for the accepted keys and their data types.
DEPENDENT_MISMATCHHTTP 400
The value specified for the unit key is not valid for the given period.
Resolution: Refer to the "details" key in the response for the exact field. Ensure that the unit value is compatible with the specified period.
MANDATORY_NOT_FOUNDHTTP 400
You have not specified one or more mandatory fields in the input.
Resolution: Refer to the Request JSON section for all the mandatory keys. Ensure that you include the id key in the request body.
INVALID_REQUEST_METHODHTTP 400
The request method is incorrect.
Resolution: Use the HTTP PUT method to make this API call. Any other request method will result in this error.
AUTHORIZATION_FAILEDHTTP 400
You do not have sufficient permission to update the calendar preferences.
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 ZohoCRM.settings.calendar.UPDATE or ZohoCRM.settings.calendar.ALL.
NO_PERMISSIONHTTP 403
You do not have permission to update 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{
    "user_calendar_preferences": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "554023000000235011"
            },
            "message": "User calendar preferences updated",
            "status": "success"
        }
    ]
}