Zoho Cliq Reminders API

openapi: 3.2.0
info:
  title: Reminders API
  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.
  contact: {}
  version: 1.0.0
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.<br>

          <b>Maximum limit</b>: 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.<br>To retrieve this ID, use the <a href="#get-reminders-in-a-chat">Get reminders in a chat</a> endpoint or the <a href="https://www.zoho.com/cliq/help/restapi/v2/reminders/#get-list-of-all-reminders">List all reminders (v2)</a>.
        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.<br>\n<b>Allowed values</b>:<br>\n<ul>\n  <li><code>completed</code>: Marks the reminder as done. When used with <code>apply_to: all_occurrences</code>, marks all occurrences of a recurring reminder as completed.</li>\n</ul>\n"
                apply_to:
                  type: string
                  enum:
                  - all_occurrences
                  description: "Scope of the status update. Required for all status changes.<br>\n<b>Allowed values</b>:<br>\n<ul>\n  <li><code>all_occurrences</code>: Applies the status update across every occurrence of a recurring reminder. Not applicable for one-time reminders.</li>\n</ul>\n"
            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.<br>To retrieve this ID, use the <a href="#get-reminders-in-a-chat">Get reminders in a chat</a> endpoint or the <a href="https://www.zoho.com/cliq/help/restapi/v2/reminders/#get-list-of-all-reminders">List all reminders (v2)</a>.
        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.<br>

                    <b>Maximum items</b>: 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
  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
externalDocs:
  description: Find out more about Zoho Cliq APIs V3
  url: https://www.zoho.com/cliq/help/restapi/v3/