openapi: 3.0.0
info:
title: Reminders
description: |
The Reminders API takes a significant leap forward with v3, enabling developers to attach time-based alerts to specific messages across any chat type - direct messages, group chats, or channels. With support for multi-participant assignment and flexible recurrence, it is well suited for building notification-driven and accountability-focused workflows.
Key Capabilities
- Get Reminders: Retrieve all reminders associated with messages in a chat, spanning direct messages, group chats, and channels in a single query.
- Update Status: Resolve a recurring reminder by marking it as completed across all its occurrences simultaneously.
- Trigger Notification: Proactively push an immediate alert to all assignees of a reminder, without waiting for the scheduled trigger. Available exclusively for reminders assigned to other users.
- Batch Edit: Reschedule multiple reminders in one operation by supplying reminder IDs alongside their updated epoch timestamps.
Reminder Types
| Type |
Description |
| One-time |
Fires once at the specified time. Use batch edit to reschedule. |
| Recurring |
Repeats on a defined schedule. Supports apply_to: all_occurrences for status updates. |
Base URL Note
- GET Reminders:
https://cliq.zoho.com/v3 (without /api)
- All other Reminders APIs:
https://cliq.zoho.com/api/v3
contact: {}
version: 1.0.0
externalDocs:
description: Find out more about Zoho Cliq APIs V3
url: https://www.zoho.com/cliq/help/restapi/v3/
servers:
- url: https://cliq.zoho.com/api/v3
description: Zoho Cliq US DC
tags:
- name: reminders
description: Reminders Module
paths:
/chats/{CHAT_ID}/reminders:
get:
summary: Get reminders in a chat
operationId: getRemindersInChatV3
description: |
Retrieves all reminders set on messages within a specific chat. Use this to list all active reminder alerts across direct messages, group chats, and channels, including single-user and multi-user assigned reminders.
Threshold limit: 20 requests per min per user
Number of API calls allowed within a minute.
Lock period: 10 minutes
Wait time before consecutive API requests.
Note: This endpoint uses a different base URL: https://cliq.zoho.com/v3 (without /api).
!
Possible Error Codes
Click to expand
| Error Code |
Description |
| param_missing |
A required parameter is missing. The limit query parameter must be provided. |
Error Response Format
When an error occurs, the API returns a JSON response in this format:
{"message": "A human-readable description of the error.", "code": "error_code"}
where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
servers:
- url: https://cliq.zoho.com/v3
description: Zoho Cliq US DC (GET reminders)
tags:
- reminders
parameters:
- name: CHAT_ID
in: path
required: true
description: Unique identifier of the chat or channel. Use this to scope the reminders retrieval to a specific conversation.
example: CHAT_ID
schema:
type: string
- name: limit
in: query
required: true
description: |
Number of results per page.
Maximum limit: 100
schema:
type: integer
maximum: 200
- name: next_token
in: query
required: false
description: Pagination cursor returned from a previous response. Pass this value to retrieve the next page of results.
schema:
type: string
responses:
'200':
description: Reminders retrieved successfully.
content:
application/json:
schema:
type: object
examples:
channel_recurring_reminder:
summary: Channel with recurring reminder
value:
category: chat
time: '2026-05-29T03:57:43-07:00'
list:
- id: '1901318000012651019'
time: '2026-05-31T19:30:00-07:00'
timezone: Asia/Kolkata
content: Weekly Finance Sync
completed: false
creation_time: '2026-05-29T04:05:57-07:00'
creator:
name: Priya
id: '697322516'
users:
- name: Priya
id: '697322516'
completed: false
deleted: false
message:
msgid: '1780052699342'
msg: 'Weekly Finance Sync: Review all pending expense approvals and flag any claims older than 7 days for escalation. Ensure the expense tracker is updated before the sync.'
chat_id: CT_1424569695482328362_631836344
sender_id: '697322516'
dname: Priya
- id: '1901318000012651010'
time: '2026-06-09T21:30:00-07:00'
timezone: Asia/Kolkata
content: Vendor Payment Review
completed: false
creation_time: '2026-05-29T03:51:46-07:00'
creator:
name: Priya
id: '697322516'
users:
- name: Priya
id: '697322516'
completed: false
deleted: false
message:
msgid: '1780051880491'
msg: 'Vendor Payment Review: Review and approve all pending vendor payment requests before the monthly finance sync on June 6.'
chat_id: CT_1424569695482328362_631836344
sender_id: '697322516'
dname: Priya
group_chat_multi_user_assigned:
summary: Group chat with multi-user assigned reminder
value:
category: chat
time: '2026-05-29T03:57:43-07:00'
list:
- id: '1901318000012651028'
time: '2026-06-15T04:30:00-07:00'
timezone: Asia/Kolkata
content: Action Item followup reminder
completed: false
creation_time: '2026-05-29T04:08:17-07:00'
creator:
name: Priya
id: '697322516'
users:
- name: Scott
id: '631830848'
completed: false
deleted: false
- name: Olivia Palmer
id: '631830846'
completed: false
deleted: false
message:
msgid: '1780051988899'
msg: 'Action Item Follow-up: Check the status of all open action items from last week''s sprint review. Update the tracker and post a summary in this channel before EOD.'
chat_id: '1608865438186287622'
sender_id: '697322516'
dname: Priya
empty_chat:
summary: Empty chat
value:
category: chat
time: '2026-05-29T03:57:42-07:00'
list: []
'400':
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
'401':
description: Unauthorized.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Request was rejected because of invalid AuthToken.
'403':
description: Forbidden.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
'429':
description: Too many requests.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Too many requests within a certain time frame.
'500':
description: Internal Server Error.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Cliq server encountered an error which prevents it from fulfilling the request.
security:
- Cliq_Auth:
- ZohoCliq.Reminders.READ
/reminders/{REMINDER_ID}:
put:
summary: Update reminder status
operationId: updateReminderStatusV3
description: |
Marks a recurring reminder as completed across all occurrences. Use this to close out a recurring reminder entirely once the associated task or event no longer requires follow-up.
Threshold limit: 20 requests per min per user
Number of API calls allowed within a minute.
Lock period: 10 minutes
Wait time before consecutive API requests.
Note: apply_to: all_occurrences is applicable only for recurring reminders. For one-time reminders, use batch edit to reschedule instead.
!
Possible Error Codes
Click to expand
| Error Code |
Description |
| reminder_missing_apply_to |
The apply_to field is required. Supported value: all_occurrences. |
| reminder_not_recurring |
apply_to: all_occurrences is only applicable for recurring reminders. |
Error Response Format
When an error occurs, the API returns a JSON response in this format:
{"message": "A human-readable description of the error.", "code": "error_code"}
where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
tags:
- reminders
parameters:
- name: REMINDER_ID
in: path
required: true
description: Unique identifier of the reminder to update. Use this to target the specific recurring reminder whose status needs to be marked as completed.
To retrieve this ID, use the Get reminders in a chat endpoint or the List all reminders (v2).
example: REMINDER_ID
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- status
- apply_to
properties:
status:
type: string
enum:
- completed
description: |
New status to apply to the reminder.
Allowed values:
completed: Marks the reminder as done. When used with apply_to: all_occurrences, marks all occurrences of a recurring reminder as completed.
apply_to:
type: string
enum:
- all_occurrences
description: |
Scope of the status update. Required for all status changes.
Allowed values:
all_occurrences: Applies the status update across every occurrence of a recurring reminder. Not applicable for one-time reminders.
example:
status: completed
apply_to: all_occurrences
responses:
'204':
description: Recurring reminder marked as completed across all occurrences. No response body returned.
content:
application/json:
schema:
$ref: '#/components/schemas/NoResponse'
'400':
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
'401':
description: Unauthorized.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Request was rejected because of invalid AuthToken.
'403':
description: Forbidden.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
'429':
description: Too many requests.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Too many requests within a certain time frame.
'500':
description: Internal Server Error.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Cliq server encountered an error which prevents it from fulfilling the request.
security:
- Cliq_Auth:
- ZohoCliq.Reminders.UPDATE
/reminders/{REMINDER_ID}/notifications:
post:
summary: Trigger reminder notification to assignees
operationId: triggerReminderNotificationV3
description: |
Immediately notifies all assignees of a reminder, bypassing the scheduled time. Use this to push a reminder notification to all assigned users on demand, without waiting for the reminder to fire automatically. Supported only for reminders assigned to other users.
Threshold limit: 20 requests per min per user
Number of API calls allowed within a minute.
Lock period: 10 minutes
Wait time before consecutive API requests.
!
Possible Error Codes
Click to expand
| Error Code |
Description |
| remind_self_not_allowed |
Notification trigger is not applicable for self-assigned reminders. |
Error Response Format
When an error occurs, the API returns a JSON response in this format:
{"message": "A human-readable description of the error.", "code": "error_code"}
where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
tags:
- reminders
parameters:
- name: REMINDER_ID
in: path
required: true
description: Unique identifier of the reminder whose assignees should be notified immediately. Must be a reminder assigned to other users, not a self-assigned reminder.
To retrieve this ID, use the Get reminders in a chat endpoint or the List all reminders (v2).
example: REMINDER_ID
schema:
type: string
responses:
'200':
description: Notification triggered. Returns the list of notified assignees.
content:
application/json:
schema:
type: object
examples:
notification_triggered:
summary: Notification triggered successfully
value:
data:
- name: Scott
id: '631830848'
completed: false
deleted: false
- name: Olivia Palmer
id: '631830846'
completed: false
deleted: false
'400':
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
'401':
description: Unauthorized.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Request was rejected because of invalid AuthToken.
'403':
description: Forbidden.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
'429':
description: Too many requests.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Too many requests within a certain time frame.
'500':
description: Internal Server Error.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Cliq server encountered an error which prevents it from fulfilling the request.
security:
- Cliq_Auth:
- ZohoCliq.Reminders.CREATE
/reminders/edits:
put:
summary: Batch edit reminders
operationId: batchEditRemindersV3
description: |
Reschedules multiple reminders in a single request. Use this to update the delivery time of several reminders at once, avoiding the need to make individual edit calls for each one.
Threshold limit: 20 requests per min per user
Number of API calls allowed within a minute.
Lock period: 10 minutes
Wait time before consecutive API requests.
Note: Use reminder_id (not id) as the key for each reminder object. Timezone is not a supported field in the request body, convert to epoch milliseconds in the desired timezone before sending.
Response status values
The top-level status field reflects the overall result of the batch operation across all submitted reminders.
success: All reminders in the batch were rescheduled successfully.partial: One or more reminders failed while the rest succeeded. Check the individual status field inside each object in the data array to identify which ones failed.failure: All reminders in the batch failed to reschedule.
Each object in the data array carries its own status and reminder_id, allowing you to handle successes and failures per reminder regardless of the overall batch outcome.
!
Possible Error Codes
Click to expand
| Error Code |
Description |
| param_missing |
A required parameter is missing. Ensure reminder_id and time are provided for each reminder object. |
| extra_key_found |
An unsupported key was included in the request body. For example, timezone is not accepted. |
Error Response Format
When an error occurs, the API returns a JSON response in this format:
{"message": "A human-readable description of the error.", "code": "error_code"}
where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
tags:
- reminders
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- reminders
properties:
reminders:
type: array
maxItems: 25
description: |
List of reminder objects to reschedule.
Maximum items: 25 per request.
items:
type: object
required:
- reminder_id
- time
properties:
reminder_id:
type: string
description: Unique identifier of the reminder to reschedule.
time:
type: integer
format: int64
description: New reminder time in epoch milliseconds.
examples:
single_reminder:
summary: Reschedule a single reminder
value:
reminders:
- reminder_id: '1901318000012651019'
time: 1749369000000
multiple_reminders:
summary: Reschedule multiple reminders
value:
reminders:
- reminder_id: '1901318000012651010'
time: 1749282600000
- reminder_id: '1901318000012651016'
time: 1748930400000
responses:
'200':
description: Returns per-reminder result with updated data for each ID.
content:
application/json:
schema:
type: object
examples:
batch_edit_success:
summary: Multiple reminders rescheduled successfully
value:
status: success
data:
- status: success
reminder_id: '1901318000012651010'
data:
id: '1901318000012651010'
time: '2026-06-09T21:30:00-07:00'
timezone: Asia/Kolkata
content: Vendor Payment Review
completed: false
creation_time: '2026-05-29T03:51:46-07:00'
creator:
name: Priya
id: '697322516'
users:
- name: Priya
id: '697322516'
completed: false
deleted: false
message:
msgid: '1780051880491'
msg: 'Vendor Payment Review: Review and approve all pending vendor payment requests before the monthly finance sync on June 6.'
chat_id: CT_1424569695482328362_631836344
sender_id: '697322516'
dname: Priya
- status: success
reminder_id: '1901318000012651016'
data:
id: '1901318000012651016'
time: '2026-06-04T20:30:00-07:00'
timezone: Asia/Kolkata
completed: false
creation_time: '2026-05-29T03:53:32-07:00'
creator:
name: Priya
id: '697322516'
users:
- name: Priya
id: '697322516'
completed: false
deleted: false
message:
msgid: '1780051988899'
msg: 'Sprint Review Prep: All team members to update their task status in the project tracker before the sprint review on June 4.'
chat_id: '1608865438186287622'
sender_id: '697322516'
dname: Priya
'400':
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
'401':
description: Unauthorized.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Request was rejected because of invalid AuthToken.
'403':
description: Forbidden.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
'429':
description: Too many requests.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Too many requests within a certain time frame.
'500':
description: Internal Server Error.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Cliq server encountered an error which prevents it from fulfilling the request.
security:
- Cliq_Auth:
- ZohoCliq.Reminders.UPDATE
components:
schemas:
NoResponse:
type: object
description: Response object returned when no content is available.
properties:
Response Code:
type: string
description: HTTP response code and message indicating no content.
example: 204 No response
error-response:
type: object
properties:
code:
type: string
message:
type: string
required:
- code
- message
securitySchemes:
Cliq_Auth:
type: oauth2
x-authorization-example: Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f
flows:
implicit:
authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
scopes:
ZohoCliq.Reminders.READ: Read reminders
ZohoCliq.Reminders.CREATE: Create reminder notifications
ZohoCliq.Reminders.UPDATE: Update reminders
ZohoCliq.Reminders.DELETE: Delete reminders