User Groups

In Zoho CRM, you can create different types of 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, roles and subordinates, territories and sub-territories. These combinations allow you to share common records through data sharing rules. For more details, refer to Users and Groups.

Purpose

To get the details of the user groups created for your organization.

Endpoints

Request Details

Request URL

Get all user groups - {api-domain}/crm/{version}/settings/user_groups
Get a specific user group - {api-domain}/crm/{version}/settings/user_groups/{user_group_id}

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

scope=ZohoCRM.settings.user_groups.READ

Parameters

  • includeoptional

    This parameter takes the value sources_count that renders the number of other groups(roles, territories etc) that this group is also a part of.

  • nameoptional

    Use this parameter when you want to filter out a user group by its name.

  • pageoptional

    To get the list of records from the respective pages. Default value for page is 1. Possible values: Positive integer values only.

  • per_pageoptional

    To get the list of records available per page. The default and the maximum possible value is 200. Possible values: Positive integer values only.

  • filtersstring, optional

    The parameter allows you to filter the users group.

    The following is the JSON structure for the value to provide in the filters parameter for single criteria:
    {
       "field": {
           "api_name": "name"
       },
       "comparator": "{{comparator_value}}",
      "value": "{{user_group_API_name}}"
    }  
     

    The following is the JSON structure for the value to provide in the filters parameter for multiple criteria:
    {
        "group_operator": "and",
        "group": [
            {
                "field": {
               "api_name": "name"
                },
                "comparator": "{{comparator_value}}",
                "value": "{{user_group_API_name}}"
            },
            {
                "field": {
                    "api_name": "name"
                },
            "comparator": "{{comparator_value}}",
                "value": "{{value}}"
            }
        ]
    }
     

    • fieldsJSON object, mandatory

      Represents the field used to filter the users group.

      • api_namestring, mandatory

        Represents the API name of the filter to query. Supported value : "name"

    • comparatorstring, mandatory

      Represents the comparison operator used in the criterion. Supported value : "contains" and "starts_with"

    • valuestring, mandatory

      Specifies the value used in the criteria. Specify the users group API name using the User Groups API.

    • group_operatorstring (it is mandatory to include the group_operator key when specifying the group key.)

      Represents the group operator used in the criteria. Supported value : "and"

    • groupJSON array 

      Represents the group of criteria used to retrieve the users group.

Sample Request with "include=sources_count"

Copiedcurl "https://www.zohoapis.com/crm/v7/settings/user_groups?include=sources_count"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Sample Response

Copied{
    "user_groups": [
        {
            "created_time": "2022-11-21T12:33:12+05:30",
            "sources_count": {
                "territories": 1,
                "roles": 2,
                "users": 2
            },
            "modified_time": "2022-11-21T13:21:46+05:30",
            "name": "group 1",
            "modified_by": {
                "name": "Patricia Boyle",
                "id": "3652397000000186017"
            },
            "description": "groups API",
            "id": "3652397000009949005",
            "created_by": {
                "name": "Patricia Boyle",
                "id": "3652397000000186017"
            }
        },
        {
            "created_time": "2022-11-23T9:59:12+05:30",
            "sources_count": {
                "users": 2
            },
            "modified_time": null,
            "name": "group test",
            "modified_by": null,
            "description": null,
            "id": "3652397000009952001",
            "created_by": {
                "name": "Patricia Boyle",
                "id": "3652397000000186017"
            }
        }
    ],
    "info": {
        "per_page": 200,
        "count": 2,
        "page": 1,
        "more_records": false
    }
}

Possible Errors

  • NO_CONTENTHTTP 204

    There are no user groups created for your org.
    Resolution: Create user groups under Setup > Users & Control > Users > Groups > Create New Group.

  • NO_PERMISSIONHTTP 403

    You do not have permission to view the user groups.
    Resolution: Contact your system administrator.

Sample Request with "name"

Copiedcurl "https://www.zohoapis.com/crm/v7/settings/user_groups?name=group 1"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Sample Response

Copied{
    "user_groups": [
        {
            "created_time": "2022-11-21T12:33:12+05:30",
            "sources_count": {
                "territories": 1,
                "roles": 2,
                "users": 2
            },
            "modified_time": "2022-11-21T13:21:46+05:30",
            "name": "group 1",
            "modified_by": {
                "name": "Patricia Boyle",
                "id": "3652397000000186017"
            },
            "description": "groups API",
            "id": "3652397000009949005",
            "created_by": {
                "name": "Patricia Boyle",
                "id": "3652397000000186017"
            }
        }
],
    "info": {
        "per_page": 200,
        "count": 1,
        "page": 1,
        "more_records": false
    }
}

Note

Encode the value of the filters parameter before sending a request.

Sample Request using "single criteria" in the "filters" parameter

Copiedcurl "https://www.zohoapis.com/crm/v7/settings/user_groups?filters=%7B%22field%22%3A%20%7B%22api_name%22%3A%20%22name%22%7D%2C%22comparator%22%3A%20%22starts_with%22%2C%20%22value%22%3A%20%22Test%22%7D"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Sample Response

Copied{
    "user_groups": [
        {
            "created_time": "2024-07-08T21:37:06+05:30",
            "modified_time": "2024-07-08T21:37:19+05:30",
            "name": "Test",
            "modified_by": {
                "name": "Patricia",
                "id": "2276164000000471001"
            },
            "description": null,
            "id": "2276164000001042069",
            "created_by": {
                "name": "Patricia",
                "id": "2276164000000471001"
            }
        }
    ],
    "info": {
        "per_page": 200,
        "count": 1,
        "page": 1,
        "more_records": false
    }
}