Zoho CRM User Groups

{
  "openapi": "3.1.0",
  "info": {
    "title": "User Groups",
    "description": "In Zoho CRM, you can create user groups (set of users) to manage a set of common records. Every group can consist of members that are grouped based on the users, roles (with/without subordinates), territories (with/ without sub-territories) and groups. These combinations allow you to share common records through data sharing rules.",
    "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"
        }
      }
    }
  ],
  "security": [
    {
      "iam-oauth2-schema": [
        "ZohoCRM.settings.user_groups.ALL"
      ]
    }
  ],
  "paths": {
    "/settings/user_groups": {
      "get": {
        "security": [
          {
            "iam-oauth2-schema": [
              "ZohoCRM.settings.user_groups.ALL"
            ]
          }
        ],
        "summary": "Get Groups",
        "description": "Get the list of user groups available in your organization.",
        "operationId": "getGroups",
        "parameters": [
          {
            "$ref": "#/components/parameters/Filters"
          },
          {
            "$ref": "#/components/parameters/Include"
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/PerPage"
          }
        ],
        "responses": {
          "200": {
            "description": "List of user groups available in your organization.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Response containing list of user groups",
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "user_groups": {
                      "description": "Array of user groups",
                      "type": "array",
                      "maxItems": 200,
                      "items": {
                        "description": "User group details",
                        "type": "object",
                        "additionalProperties": false,
                        "properties": {
                          "created_by": {
                            "description": "User who created this group",
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                              "name": {
                                "description": "Name of the creator",
                                "type": "string",
                                "maxLength": 512
                              },
                              "id": {
                                "description": "ID of the creator",
                                "type": "string",
                                "maxLength": 19
                              }
                            },
                            "required": [
                              "name",
                              "id"
                            ]
                          },
                          "modified_by": {
                            "description": "User who last modified this group",
                            "oneOf": [
                              {
                                "description": "Modifier user information",
                                "type": "object",
                                "additionalProperties": false,
                                "properties": {
                                  "name": {
                                    "description": "Name of the modifier",
                                    "type": "string",
                                    "maxLength": 512
                                  },
                                  "id": {
                                    "description": "ID of the modifier",
                                    "type": "string",
                                    "maxLength": 19
                                  }
                                },
                                "required": [
                                  "name",
                                  "id"
                                ]
                              },
                              {
                                "description": "No modifier information available",
                                "type": "null"
                              }
                            ]
                          },
                          "modified_time": {
                            "description": "Last modification timestamp",
                            "oneOf": [
                              {
                                "description": "Timestamp in ISO 8601 format",
                                "type": "string",
                                "format": "date-time"
                              },
                              {
                                "description": "No modification time available",
                                "type": "null"
                              }
                            ]
                          },
                          "created_time": {
                            "description": "Creation timestamp",
                            "type": "string",
                            "format": "date-time"
                          },
                          "description": {
                            "description": "Group description",
                            "oneOf": [
                              {
                                "description": "Group description text",
                                "type": "string",
                                "maxLength": 250
                              },
                              {
                                "description": "No description provided",
                                "type": "null"
                              }
                            ]
                          },
                          "id": {
                            "description": "Unique identifier for the group",
                            "type": "string",
                            "maxLength": 19
                          },
                          "name": {
                            "description": "Name of the group",
                            "type": "string",
                            "maxLength": 250
                          },
                          "sources_count": {
                            "description": "Count of sources by type",
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                              "territories": {
                                "description": "Number of territories",
                                "type": "integer",
                                "format": "int32"
                              },
                              "roles": {
                                "description": "Number of roles",
                                "type": "integer",
                                "format": "int32"
                              },
                              "groups": {
                                "description": "Number of groups",
                                "type": "integer",
                                "format": "int32"
                              },
                              "users": {
                                "description": "User count by status",
                                "type": "object",
                                "additionalProperties": false,
                                "properties": {
                                  "inactive": {
                                    "description": "Number of inactive users",
                                    "type": "integer",
                                    "format": "int32"
                                  },
                                  "deleted": {
                                    "description": "Number of deleted users",
                                    "type": "integer",
                                    "format": "int32"
                                  },
                                  "active": {
                                    "description": "Number of active users",
                                    "type": "integer",
                                    "format": "int32"
                                  }
                                },
                                "required": [
                                  "inactive",
                                  "deleted",
                                  "active"
                                ]
                              }
                            }
                          }
                        },
                        "required": [
                          "created_by",
                          "modified_by",
                          "modified_time",
                          "created_time",
                          "description",
                          "id",
                          "name"
                        ]
                      }
                    },
                    "info": {
                      "type": "object",
                      "description": "Information about pagination",
                      "additionalProperties": false,
                      "properties": {
                        "per_page": {
                          "type": "integer",
                          "format": "int32",
                          "description": "Number of records per page"
                        },
                        "count": {
                          "type": "integer",
                          "format": "int32",
                          "description": "Number of records"
                        },
                        "page": {
                          "type": "integer",
                          "format": "int32",
                          "description": "Current page number"
                        },
                        "more_records": {
                          "type": "boolean",
                          "description": "Indicates if there are more records available"
                        }
                      },
                      "required": [
                        "per_page",
                        "count",
                        "page",
                        "more_records"
                      ]
                    }
                  },
                  "required": [
                    "user_groups",
                    "info"
                  ]
                }
              }
            }
          },
          "204": {
            "description": "There are no user groups created for your org."
          },
          "400": {
            "description": "Forbidden - You do not have permission to access this resource",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Error response for groups permission issue",
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "code": {
                      "description": "Error code",
                      "type": "string",
                      "enum": [
                        "INVALID_DATA"
                      ]
                    },
                    "details": {
                      "description": "Additional error details",
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "param_name": {
                          "description": "Name of the parameter with invalid data",
                          "type": "string",
                          "maxLength": 100
                        }
                      },
                      "required": [
                        "param_name"
                      ]
                    },
                    "message": {
                      "description": "Human readable error message",
                      "type": "string",
                      "maxLength": 500
                    },
                    "status": {
                      "description": "Error status",
                      "type": "string",
                      "enum": [
                        "error"
                      ]
                    }
                  },
                  "required": [
                    "code",
                    "details",
                    "message",
                    "status"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - You do not have permission to access this resource",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Error response for groups permission issue",
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "code": {
                      "description": "Error code",
                      "type": "string",
                      "enum": [
                        "NO_PERMISSION"
                      ]
                    },
                    "details": {
                      "description": "Additional error details",
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "permissions": {
                          "description": "Missing permissions required to access the resource",
                          "type": "string",
                          "maxLength": 100
                        }
                      },
                      "required": [
                        "permissions"
                      ]
                    },
                    "message": {
                      "description": "Human readable error message",
                      "type": "string",
                      "maxLength": 500
                    },
                    "status": {
                      "description": "Error status",
                      "type": "string",
                      "enum": [
                        "error"
                      ]
                    }
                  },
                  "required": [
                    "code",
                    "details",
                    "message",
                    "status"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "security": [
          {
            "iam-oauth2-schema": [
              "ZohoCRM.settings.user_groups.CREATE"
            ]
          }
        ],
        "summary": "Create Group",
        "description": "Create a new user group in your organization.",
        "operationId": "createGroup",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "description": "Request body for creating a user group",
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "user_groups": {
                    "description": "Array of user groups to create",
                    "type": "array",
                    "maxItems": 1,
                    "items": {
                      "description": "User group creation details",
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "description": {
                          "description": "Description of the user group",
                          "oneOf": [
                            {
                              "description": "User group description text",
                              "type": "string",
                              "maxLength": 250
                            },
                            {
                              "description": "No description provided",
                              "type": "null"
                            }
                          ]
                        },
                        "name": {
                          "description": "Name of the user group",
                          "type": "string",
                          "maxLength": 250
                        },
                        "sources": {
                          "description": "Array of sources for the user group",
                          "type": "array",
                          "maxItems": 200,
                          "items": {
                            "description": "Source details for the user group",
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                              "type": {
                                "description": "Type of source",
                                "type": "string",
                                "enum": [
                                  "territories",
                                  "roles",
                                  "users"
                                ]
                              },
                              "source": {
                                "description": "Source identifier",
                                "type": "object",
                                "additionalProperties": false,
                                "properties": {
                                  "id": {
                                    "description": "ID of the source",
                                    "type": "string",
                                    "maxLength": 19
                                  }
                                },
                                "required": [
                                  "id"
                                ]
                              },
                              "subordinates": {
                                "description": "Include subordinates flag",
                                "oneOf": [
                                  {
                                    "description": "Boolean flag to include subordinates",
                                    "type": "boolean"
                                  },
                                  {
                                    "description": "No subordinates flag provided",
                                    "type": "null"
                                  }
                                ]
                              },
                              "sub_territories": {
                                "description": "Include sub-territories flag",
                                "oneOf": [
                                  {
                                    "description": "Boolean flag to include sub-territories",
                                    "type": "boolean"
                                  },
                                  {
                                    "description": "No sub-territories flag provided",
                                    "type": "null"
                                  }
                                ]
                              }
                            },
                            "required": [
                              "type",
                              "source"
                            ]
                          }
                        }
                      },
                      "required": [
                        "name",
                        "sources"
                      ]
                    }
                  }
                },
                "required": [
                  "user_groups"
                ]
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "User group successfully created",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Response for user group creation",
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "user_groups": {
                      "description": "Array of user group creation results",
                      "type": "array",
                      "maxItems": 1,
                      "items": {
                        "description": "User group creation result details",
                        "type": "object",
                        "additionalProperties": false,
                        "properties": {
                          "code": {
                            "description": "Response code indicating success or scheduled status",
                            "type": "string",
                            "enum": [
                              "SUCCESS"
                            ]
                          },
                          "message": {
                            "description": "Response message describing the result",
                            "type": "string",
                            "maxLength": 500
                          },
                          "status": {
                            "description": "Status of the operation",
                            "type": "string",
                            "enum": [
                              "success"
                            ]
                          },
                          "details": {
                            "description": "Details containing the created group ID",
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                              "id": {
                                "description": "ID of the created user group",
                                "type": "string",
                                "maxLength": 19
                              }
                            },
                            "required": [
                              "id"
                            ]
                          }
                        },
                        "required": [
                          "code",
                          "message",
                          "status",
                          "details"
                        ]
                      }
                    }
                  },
                  "required": [
                    "user_groups"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Invalid input or request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Response for user group creation failures",
                  "oneOf": [
                    {
                      "description": "user group creation failure results",
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "user_groups": {
                          "description": "Array of error details",
                          "type": "array",
                          "maxItems": 1,
                          "items": {
                            "description": "Individual error object",
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                              "status": {
                                "description": "Status of the operation",
                                "type": "string",
                                "enum": [
                                  "error"
                                ]
                              },
                              "code": {
                                "description": "Error code",
                                "type": "string",
                                "enum": [
                                  "DUPLICATE_DATA",
                                  "INVALID_DATA",
                                  "MANDATORY_NOT_FOUND"
                                ]
                              },
                              "message": {
                                "description": "Human readable error message",
                                "type": "string",
                                "maxLength": 500
                              },
                              "details": {
                                "description": "Additional error details",
                                "type": "object",
                                "additionalProperties": false,
                                "properties": {
                                  "api_name": {
                                    "description": "API name of the field with error",
                                    "type": "string",
                                    "maxLength": 100
                                  },
                                  "json_path": {
                                    "description": "JSON path to the field with error",
                                    "type": "string",
                                    "maxLength": 200
                                  }
                                },
                                "required": [
                                  "api_name",
                                  "json_path"
                                ]
                              }
                            },
                            "required": [
                              "status",
                              "code",
                              "message",
                              "details"
                            ]
                          }
                        }
                      },
                      "required": [
                        "user_groups"
                      ]
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/settings/user_groups/{group}": {
      "get": {
        "security": [
          {
            "iam-oauth2-schema": [
              "ZohoCRM.settings.user_groups.READ"
            ]
          }
        ],
        "operationId": "getGroup",
        "summary": "Get Group",
        "description": "Get details of the specified user group.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Group"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved the specified user group details",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Response containing list of user groups",
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "user_groups": {
                      "description": "Array of user groups",
                      "type": "array",
                      "maxItems": 200,
                      "items": {
                        "description": "User group details",
                        "type": "object",
                        "additionalProperties": false,
                        "properties": {
                          "created_by": {
                            "description": "User who created this group",
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                              "name": {
                                "description": "Name of the creator",
                                "type": "string",
                                "maxLength": 512
                              },
                              "id": {
                                "description": "ID of the creator",
                                "type": "string",
                                "maxLength": 19
                              }
                            },
                            "required": [
                              "name",
                              "id"
                            ]
                          },
                          "modified_by": {
                            "description": "User who last modified this group",
                            "oneOf": [
                              {
                                "description": "Modifier user information",
                                "type": "object",
                                "additionalProperties": false,
                                "properties": {
                                  "name": {
                                    "description": "Name of the modifier",
                                    "type": "string",
                                    "maxLength": 512
                                  },
                                  "id": {
                                    "description": "ID of the modifier",
                                    "type": "string",
                                    "maxLength": 19
                                  }
                                },
                                "required": [
                                  "name",
                                  "id"
                                ]
                              },
                              {
                                "description": "No modifier information available",
                                "type": "null"
                              }
                            ]
                          },
                          "modified_time": {
                            "description": "Last modification timestamp",
                            "oneOf": [
                              {
                                "description": "Timestamp in ISO 8601 format",
                                "type": "string",
                                "format": "date-time"
                              },
                              {
                                "description": "No modification time available",
                                "type": "null"
                              }
                            ]
                          },
                          "created_time": {
                            "description": "Creation timestamp",
                            "type": "string",
                            "format": "date-time"
                          },
                          "description": {
                            "description": "Group description",
                            "oneOf": [
                              {
                                "description": "Group description text",
                                "type": "string",
                                "maxLength": 250
                              },
                              {
                                "description": "No description provided",
                                "type": "null"
                              }
                            ]
                          },
                          "id": {
                            "description": "Unique identifier for the group",
                            "type": "string",
                            "maxLength": 19
                          },
                          "name": {
                            "description": "Name of the group",
                            "type": "string",
                            "maxLength": 250
                          },
                          "sources_count": {
                        

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