Zoho CRM Notifications

{
  "openapi": "3.1.0",
  "info": {
    "title": "Notifications",
    "description": "Notifications management API for subscribing, listing and creating CRM notification channels.",
    "version": "8"
  },
  "servers": [
    {
      "url": "https://zohoapis.{dc}/crm/{version}",
      "description": "API Server URL",
      "variables": {
        "dc": {
          "enum": [
            "com",
            "eu",
            "in",
            "cn",
            "au"
          ],
          "default": "com",
          "description": "API Server URL TLD"
        },
        "version": {
          "default": "v8",
          "description": "API version"
        }
      }
    }
  ],
  "paths": {
    "/actions/watch": {
      "get": {
        "operationId": "getNotifications",
        "summary": "List active notification channels",
        "description": "Get a list of all active notification channels for the user.",
        "security": [
          {
            "iam-oauth2-schema": [
              "ZohoCRM.notifications.READ"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Module"
          },
          {
            "$ref": "#/components/parameters/ChannelId"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved the list of notification channels.",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "description": "A wrapper for the list of notification channels and pagination information.",
                  "properties": {
                    "watch": {
                      "type": "array",
                      "description": "List of active notification channels.",
                      "maxItems": 200,
                      "items": {
                        "additionalProperties": false,
                        "description": "Notification channel details.",
                        "type": "object",
                        "properties": {
                          "notify_on_related_action": {
                            "description": "Whether to notify on related associated record actions.",
                            "type": "boolean"
                          },
                          "channel_expiry": {
                            "type": "string",
                            "format": "date-time",
                            "description": "Channel expiry timestamp."
                          },
                          "return_affected_field_values": {
                            "description": "Whether to return affected field values in notification payloads.",
                            "type": "boolean"
                          },
                          "resource_uri": {
                            "maxLength": 255,
                            "description": "URI of the resource.",
                            "type": "string"
                          },
                          "resource_id": {
                            "maxLength": 64,
                            "description": "Identifier of the resource.",
                            "type": "string"
                          },
                          "notify_url": {
                            "maxLength": 255,
                            "description": "Callback URL for notifications.",
                            "type": "string"
                          },
                          "resource_name": {
                            "maxLength": 128,
                            "description": "Name of the resource.",
                            "type": "string"
                          },
                          "fields": {
                            "description": "Fields to include in the notification.",
                            "type": [
                              "array",
                              "null"
                            ],
                            "items": {}
                          },
                          "notification_condition": {
                            "description": "Conditions for notifications.",
                            "type": [
                              "array",
                              "null"
                            ],
                            "items": {
                              "additionalProperties": false,
                              "description": "Notification condition details.",
                              "type": "object",
                              "properties": {
                                "field_selection": {
                                  "additionalProperties": false,
                                  "description": "Field selection details.",
                                  "type": "object",
                                  "properties": {
                                    "group_operator": {
                                      "maxLength": 3,
                                      "description": "Operator for grouping conditions.",
                                      "type": "string"
                                    },
                                    "group": {
                                      "maxItems": 2,
                                      "description": "Group of field conditions.",
                                      "type": "array",
                                      "items": {
                                        "additionalProperties": false,
                                        "description": "Field condition details.",
                                        "type": "object",
                                        "properties": {
                                          "field": {
                                            "additionalProperties": false,
                                            "description": "Field details.",
                                            "type": "object",
                                            "properties": {
                                              "api_name": {
                                                "maxLength": 128,
                                                "description": "API name of the field.",
                                                "type": "string"
                                              },
                                              "id": {
                                                "maxLength": 64,
                                                "description": "Identifier of the field.",
                                                "type": "string"
                                              }
                                            }
                                          },
                                          "group_operator": {
                                            "description": "Operator for grouping sub-conditions.",
                                            "type": [
                                              "string",
                                              "null"
                                            ],
                                            "enum": [
                                              "and",
                                              "or",
                                              null
                                            ]
                                          },
                                          "group": {
                                            "description": "Sub-group of field conditions.",
                                            "type": [
                                              "array",
                                              "null"
                                            ],
                                            "items": {}
                                          }
                                        }
                                      }
                                    }
                                  }
                                },
                                "module": {
                                  "additionalProperties": false,
                                  "description": "Module details.",
                                  "type": "object",
                                  "properties": {
                                    "api_name": {
                                      "maxLength": 255,
                                      "description": "API name of the module.",
                                      "type": "string"
                                    },
                                    "id": {
                                      "maxLength": 64,
                                      "description": "Identifier of the module.",
                                      "type": "string"
                                    }
                                  }
                                },
                                "type": {
                                  "maxLength": 32,
                                  "description": "Type of notification condition.",
                                  "type": "string"
                                }
                              }
                            }
                          },
                          "channel_id": {
                            "maxLength": 64,
                            "description": "Identifier of the notification channel.",
                            "type": "string"
                          },
                          "events": {
                            "maxItems": 10,
                            "description": "Events subscribed for notifications.",
                            "type": "array",
                            "items": {
                              "maxLength": 128,
                              "description": "Event name.",
                              "type": "string"
                            }
                          },
                          "token": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "maxLength": 255,
                            "description": "Verification token for the notification channel."
                          }
                        }
                      }
                    },
                    "info": {
                      "additionalProperties": false,
                      "description": "Information about the pagination and record count.",
                      "type": "object",
                      "properties": {
                        "per_page": {
                          "maximum": 200,
                          "description": "Number of records per page.",
                          "type": "integer",
                          "format": "int32"
                        },
                        "count": {
                          "maximum": 100,
                          "description": "Total number of records returned.",
                          "type": "integer",
                          "format": "int32"
                        },
                        "page": {
                          "maximum": 100,
                          "description": "Current page number.",
                          "type": "integer",
                          "format": "int32"
                        },
                        "more_records": {
                          "description": "Indicates if more records are available.",
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "post": {
        "operationId": "createNotifications",
        "summary": "Create notification channels",
        "description": "Create one or more notification channels.",
        "security": [
          {
            "iam-oauth2-schema": [
              "ZohoCRM.notifications.CREATE"
            ]
          },
          {
            "iam-oauth2-schema": [
              "ZohoCRM.notifications.ALL"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Create channels request wrapper.",
                "additionalProperties": false,
                "properties": {
                  "watch": {
                    "type": "array",
                    "description": "Channels to create.",
                    "maxItems": 50,
                    "items": {
                      "type": "object",
                      "description": "Create channel payload.",
                      "additionalProperties": false,
                      "properties": {
                        "notify_url": {
                          "type": "string",
                          "description": "Callback URL.",
                          "maxLength": 255
                        },
                        "channel_id": {
                          "type": "string",
                          "description": "client channel identifier.",
                          "maxLength": 64
                        },
                        "channel_expiry": {
                          "type": "string",
                          "description": "Channel expiry time.",
                          "format": "date-time"
                        },
                        "events": {
                          "type": "array",
                          "description": "Events to subscribe.",
                          "maxItems": 50,
                          "items": {
                            "type": "string",
                            "description": "Event name.",
                            "maxLength": 128
                          }
                        },
                        "token": {
                          "type": "string",
                          "description": "Optional token echoed in callbacks.",
                          "maxLength": 256
                        }
                      },
                      "required": [
                        "notify_url",
                        "events"
                      ]
                    }
                  }
                },
                "required": [
                  "watch"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Notification channels created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Creation results wrapper.",
                  "additionalProperties": false,
                  "properties": {
                    "watch": {
                      "type": "array",
                      "description": "List of create result entries.",
                      "maxItems": 50,
                      "items": {
                        "type": "object",
                        "description": "Single create result.",
                        "additionalProperties": false,
                        "properties": {
                          "code": {
                            "type": "string",
                            "description": "Result code.",
                            "maxLength": 32
                          },
                          "details": {
                            "type": "object",
                            "description": "Created event channel details.",
                            "additionalProperties": false,
                            "properties": {
                              "events": {
                                "type": "array",
                                "description": "Event channel details.",
                                "maxItems": 50,
                                "items": {
                                  "type": "object",
                                  "description": "Event channel detail.",
                                  "additionalProperties": false,
                                  "properties": {
                                    "channel_expiry": {
                                      "type": "string",
                                      "format": "date-time",
                                      "description": "Expiry timestamp."
                                    },
                                    "resource_uri": {
                                      "type": "string",
                                      "description": "Resource URI.",
                                      "maxLength": 255
                                    },
                                    "resource_id": {
                                      "type": "string",
                                      "description": "Resource identifier.",
                                      "maxLength": 64
                                    },
                                    "resource_name": {
                                      "type": "string",
                                      "description": "Resource name.",
                                      "maxLength": 128
                                    },
                                    "channel_id": {
                                      "type": "string",
                                      "description": "Channel identifier.",
                                      "maxLength": 64
                                    }
                                  },
                                  "required": [
                                    "channel_expiry",
                                    "resource_uri",
                                    "resource_id",
                                    "resource_name",
                                    "channel_id"
                                  ]
                                }
                              }
                            },
                            "required": [
                              "events"
                            ]
                          },
                          "message": {
                            "type": "string",
                            "description": "Human readable message.",
                            "maxLength": 255
                          },
                          "status": {
                            "type": "string",
                            "description": "Status string.",
                            "maxLength": 32
                          }
                        },
                        "required": [
                          "code",
                          "details",
                          "message",
                          "status"
                        ]
                      }
                    }
                  },
                  "required": [
                    "watch"
                  ]
                }
              }
            }
          },
          "207": {
            "$ref": "#/components/responses/MultiStatus"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "put": {
        "operationId": "updateNotificationDetails",
        "summary": "Update full notification details",
        "description": "Replace all details of an existing notification channel, overwriting its previous configuration.",
        "security": [
          {
            "iam-oauth2-schema": [
              "ZohoCRM.notifications.UPDATE"
            ]
          },
          {
            "iam-oauth2-schema": [
              "ZohoCRM.notifications.ALL"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Full details update request wrapper (replaces existing).",
                "additionalProperties": false,
                "properties": {
                  "watch": {
                    "type": "array",
                    "description": "Channels to update.",
                    "maxItems": 50,
                    "items": {
                      "type": "object",
                      "description": "Full channel details replacement payload.",
                      "additionalProperties": false,
                      "properties": {
                        "channel_id": {
                          "type": "string",
                          "description": "Channel identifier.",
                          "maxLength": 64
                        },
                        "notify_url": {
                          "type": "string",
                          "description": "Callback URL.",
                          "maxLength": 255
                        },
                        "channel_expiry": {
                          "type": "string",
                          "format": "date-time",
                          "description": "Expiry timestamp (<= 1 week)."
                        },
                        "events": {
                          "type": "array",
                          "description": "Event subscriptions replacing current list.",
                          "maxItems": 50,
                          "items": {
                            "type": "string",
                            "description": "Event spec module.operation",
                            "maxLength": 128
                          }
                        },
                        "notification_condition": {
                          "type": "array",
                          "description": "Conditions replacing existing (see update_info).",
                          "maxItems": 2,
                          "items": {
                            "type": "object",
                            "description": "Condition object.",
                            "additionalProperties": false,
                            "properties": {
                              "type": {
                                "type": "string",
                                "description": "Condition type",
                                "enum": [
                                  "field_selection"
                                ]
                              }
                            },
                            "required": [
                              "type"
                            ]
                          }
                        },
                        "notify_on_related_action": {
                          "type": "boolean",
                          "description": "Notify on related associated record actions."
                        },
                        "return_affected_field_values": {
                          "type": "boolean",
                          "description": "Return affected field values in notification payloads."
                        },
                        "token": {
                          "type": "string",
                          "description": "Verification token.",
                          "maxLength": 256
                        }
                      },
                      "required": [
                        "channel_id",
                        "notify_url",
                        "events"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Notification details replaced successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Full replacement result wrapper.",
                  "additionalProperties": false,
                  "properties": {
                    "watch": {
                      "type": "array",
                      "description": "List of replacement result entries.",
                      "maxItems": 50,
                      "items": {
                        "type": "object",
                        "description": "Single replacement result.",
                        "additionalProperties": false,
                        "properties": {
                          "code": {
                            "type": "string",
                            "description": "Result code.",
                            "maxLength": 32
                          },
                          "details": {
                            "type": "object",
                            "description": "Replacement details container.",
                            "additionalProperties": false,
                            "properties": {
                              "events": {
                                "type": "array",
                                "description": "Replaced event channel details.",
                                "maxItems": 50,
                                "items": {
                                  "type": "object",
                                  "description": "Event channel detail.",
                                  "additionalProperties": false,
                                  "properties": {
                                    "channel_expiry": {
                                      "type": "string",
                                      "format": "date-time",
                                      "description": "Expiry timestamp."
                                    },
                                    "resource_uri": {
                                      "type": "string",
                                      "description": "Resource URI.",
                                      "maxLength": 255
                                    },
                                    "resource_id": {
                                      "type": "string",
                                      "description": "Resource identifier.",
                                      "maxLength": 64
                                    },
                                    "resource_name": {
                                      "type": "string",
                                      "description": "Resource name.",
                                      "maxLength": 128
                                    },
                                    "channel_id": {
                                      "type": "string",
                                      "description": "Channel identifier.",
                                      "maxLength": 64
                                    }
                                  },
                                  "required": [
                                    "channel_expiry",
                                    "resource_uri",
                                    "resource_id",
                                    "resource_name",
                                    "channel_id"
                                  ]
                                }
                              }
                            },
                            "required": [
                              "events"
                            ]
                          },
                          "message": {
                            "type": "string",
                            "description": "Human readable message.",
                            "maxLength": 255
                          },
                          "status": {
                            "type": "string",
                            "description": "Status string.",
                            "maxLength": 32
                          }
                        },
                        "required": [
                          "code",
                          "details",
                          "message",
                          "status"
                        ]
                      }
                    }
                  },
                  "required": [
                    "watch"
                  ]
                }
              }
            }
          },
          "207": {
            "$ref": "#/components/responses/MultiStatus"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "patch": {
        "operationId": "updateNotificationInfo",
        "summary": "Update specific notification information",
        "description": "Partially update selected properties of a notification channel (URL, events, expiry, conditions, token).",
        "parameters": [
          {
            "$ref": "#/components/parameters/ChannelId"
          }
        ],
        "security": [
          {
            "iam-oauth2-schema": [
              "ZohoCRM.notifications.UPDATE"
            ]
          },
          {
            "iam-oauth2-schema": [
              "ZohoCRM.notifications.ALL"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Update specific notification info request wrapper.",
                "additionalProperties": false,
                "properties": {
                  "channel_id": {
                    "type": "string",
                    "description": "Channel identifier to update.",
                    "maxLength": 64
                  },
                  "notify_url": {
                    "type": "string",
                    "description": "Destination callback URL.",
                    "maxLength": 255
                  },
                  "channel_expiry": {
                    "type": "string",
                    "format": "date-time",
                    "description": "New expiry timestamp (<= 1 week)."
                  },
                  "events": {
                    "type": "array",
                    "description": "Updated event subscriptions.",
                    "maxItems": 50,
                    "items": {
                      "type": "string",
                      "description": "Event spec module.operation",
                      "maxLength": 128
                    }
                  },
                  "notification_condition": {
                    "type": "array",
                    "description": "Conditional field selection groups (max 2 objects).",
                    "maxItems": 2,
                    "items": {
                      "type": "object",
                      "description": "Single condition definition.",
                      "additionalProperties": false,
                      "properties": {
                        "type": {
                          "type": "string",
                          "description": "Condition type: field_selection",
                          "enum": [
                            "field_selection"
                          ]
                        },
                        "module": {
                          "type": "object",
                          "description": "Module context for field selection.",
                          "additionalProperties": false,
                

# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho-crm/refs/heads/main/openapi/zoho-crm-notifications-openapi.json