Create a User Group

Purpose

To create a user group.

Endpoints

Request Details

Request URL

{api-domain}/crm/{version}/settings/user_groups

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

scope=ZohoCRM.settings.user_groups.CREATE

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v5/settings/user_groups"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@input.json"
-X POST

Input JSON

  • namestring, mandatory

    The name of the user group. Accepts alphanumeric characters. Note that the name must be unique for each group.

  • descriptionstring, optional

    The description of the user group.

  • sourcesJSON array, mandatory

    Each JSON object in this array consists of the following keys:

    • type - string, mandatory - The type of member you want to add to the user group. The possible values are users, roles, groups, and territories.
    • source - JSON object, mandatory - The API name and ID of the user, group, role, or territory you want to add to the user group. If your "type" is "roles", you must only give the details of the role, here.
    • subordinates - boolean, optional - When you type is "roles" or "territories", this key represents whether you want to assign the subordinate roles or child territories to the user group, too.

Sample Input

Copied{
    "user_groups": [
        {
            "name": "test group",
            "description": "my group",
            "sources": [
                {
                    "source": {
                        "name": "Patricia Boyle",
                        "id": "3652397000000186017"
                    },
                    "type": "users"
                },
                {
                    "source": {
                        "name": "Manager",
                        "id": "3652397000000026008"
                    },
                    "type": "roles",
                    "subordinates": true
                },
                {
                    "source": {
                        "name": "New York",
                        "id": "3652397000007622003"
                    },
                    "type": "territories",
                    "subordinates": true
                },
                {
                    "source": {
                        "name": "Deborah Gill",
                        "id": "3652397000000281001"
                    },
                    "type": "users"
                }
            ]
        }
    ]
}

Possible Errors

  • DUPLICATE_DATAHTTP 400

    Group name already exists.
    Resolution: Group name is unique. Specify another name for the group you are trying to create.

  • MANDATORY_NOT_FOUNDHTTP 400

    You have not included the key "name" in the input.
    Resolution: "name" is a mandatory key. Ensure that you give a name to the user group you want to create.

  • INVALID_DATAHTTP 400

    The role or territory ID is invalid.
    Resolution: Refer to the "details" key in the response for the exact error and rectify it accordingly.

  • NO_PERMISSIONHTTP 403

    You do not have permission to create a user group.
    Resolution: Contact your administrator to obtain the "Manage Groups" permission to be able to create a user group.

Sample Response

Copied{
    "user_groups": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "5725767000002350003"
            },
            "message": "User Group Created successfully",
            "status": "success"
        }
    ]
}