Skip to main content

Roles APIs

In Zoho CRM, Administrators assign roles to the users. Roles, such as Managers, Sales Reps, Supervisors, Product Management Staff, etc., denote the different levels of employees in a company. Use this API to retrieve information about various roles in Zoho CRM.

Get Roles

Purpose

To retrieve the details about roles in your organization.

Endpoints

  • GET /settings/roles
  • GET /settings/roles/{role_ID}

Request Details

Request URL

To retrieve all roles:
{api-domain}/crm/{version}/settings/roles

To get a specific role:
{api-domain}/crm/{version}/settings/roles/{role_ID}

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.settings.roles.{operation_type}

Possible operation types

ALL - Full access to roles data
READ - Retrieve roles data

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/roles/3652397000010189001"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
Copiedresponse = invokeurl
[
	url: "https://www.zohoapis.com/crm/v8/settings/roles/3652397000010189001"
	type: GET
	connection:"crm_oauth_connection"
];
info response;

Response JSON

  • display_labelstring

    Represents the display name of the current role.

  • share_with_peersboolean

    Represents if the users with the current role have the permission to share records.
    Possible Values:
    true: The users with the current role can share records with other users.
    false: The users with the current role cannot share records with other users.

Possible Errors

  • INVALID_REQUEST_METHODHTTP 400

    The http request method type is not a valid one
    Resolution: You have specified an invalid HTTP method to access the API URL. Specify a valid request method. Refer to endpoints section at the beginning of this page.

  • AUTHORIZATION_FAILEDHTTP 400

    User does not have sufficient privilege to read roles
    Resolution: The user does not have the permission to retrieve roles data. Contact your system administrator.

  • OAUTH_SCOPE_MISMATCHHTTP 401

    The access token you have used to make this API call does not have the required scope.
    Resolution: Generate a new access token with the required scopes for this API. Refer to the Scope section at the beginning of this page for the list of required scopes.

  • NO_PERMISSIONHTTP 403

    Permission denied to read
    Resolution: The user does not have permission to read roles data. Contact your system administrator.

  • INVALID_URL_PATTERNHTTP 404

    The request URL is incorrect.
    Resolution: Specify a valid request URL. Refer to the Request URL section at the beginning of this page for more details.

  • INTERNAL_ERRORHTTP 500

    Internal Server Error
    Resolution: Unexpected and unhandled exception in Server. Contact support team.

Sample Response

Copied{
    "roles": [
        {
            "display_label": "SalesRep",
            "created_by__s": {
                "name": "Patricia Boyle",
                "id": "3652397000000186017"
            },
            "modified_by__s": {
                "name": "Patricia Boyle",
                "id": "3652397000000186017"
            },
            "forecast_manager": null,
            "share_with_peers": true,
            "modified_time__s": "2022-11-10T17:25:02+05:30",
            "name": "SalesRep",
            "description": null,
            "reporting_to": {
                "name": "Manager",
                "id": "3652397000000026008"
            },
            "id": "3652397000010189001",
            "created_time__s": "2022-11-10T17:25:02+05:30"
        }
    ]
}