Retrieve Roles in the CRM - Manage user roles and permissions within the Zoho CRM system
{
"openapi": "3.1.0",
"info": {
"title": "Roles",
"description": "Retrieve Roles in the CRM - Manage user roles and permissions within the Zoho CRM system",
"version": "8.0"
},
"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.roles.ALL"
]
}
],
"paths": {
"/settings/roles": {
"get": {
"operationId": "getRoles",
"summary": "Get all roles",
"description": "Retrieve a list of all CRM roles in the organization",
"responses": {
"200": {
"description": "Retrieve list of CRM roles",
"content": {
"application/json": {
"schema": {
"description": "Response containing list of CRM roles",
"type": "object",
"additionalProperties": false,
"properties": {
"roles": {
"description": "Array of role objects",
"type": "array",
"maxItems": 250,
"items": {
"description": "Individual role object",
"type": "object",
"additionalProperties": false,
"properties": {
"display_label": {
"description": "Display label for the role",
"type": "string",
"maxLength": 200
},
"forecast_manager": {
"description": "Information about the forecast manager for this role",
"type": [
"object",
"null"
],
"additionalProperties": false,
"properties": {
"id": {
"description": "Unique identifier of the forecast manager",
"type": "string",
"maxLength": 19
},
"name": {
"description": "Display name of the forecast manager",
"type": "string",
"maxLength": 255
}
},
"required": [
"id",
"name"
]
},
"reporting_to": {
"description": "Information about the role this role reports to",
"type": [
"object",
"null"
],
"additionalProperties": false,
"properties": {
"id": {
"description": "Unique identifier of the parent role",
"type": "string",
"maxLength": 19
},
"name": {
"description": "Display name of the parent role",
"type": "string",
"maxLength": 255
}
},
"required": [
"id",
"name"
]
},
"api_name": {
"description": "API name identifier for the role",
"type": "string",
"maxLength": 100
},
"share_with_peers": {
"description": "Whether this role can share data with peer roles",
"type": "boolean"
},
"description": {
"description": "Detailed description of the role and its responsibilities",
"type": [
"string",
"null"
],
"maxLength": 1000
},
"id": {
"description": "Unique identifier for the role",
"type": "string",
"maxLength": 19
},
"name": {
"description": "Display name of the role",
"type": "string",
"maxLength": 200
},
"created_by__s": {
"description": "Information about the user who created this role",
"type": [
"object",
"null"
],
"additionalProperties": false,
"properties": {
"name": {
"description": "Display name of the user who created the role",
"type": "string",
"maxLength": 255
},
"id": {
"description": "Unique identifier of the user who created the role",
"type": "string",
"maxLength": 19
}
},
"required": [
"name",
"id"
]
},
"modified_by__s": {
"description": "Information about the user who last modified this role",
"type": [
"object",
"null"
],
"additionalProperties": false,
"properties": {
"name": {
"description": "Display name of the user who last modified the role",
"type": "string",
"maxLength": 255
},
"id": {
"description": "Unique identifier of the user who last modified the role",
"type": "string",
"maxLength": 19
}
},
"required": [
"name",
"id"
]
},
"modified_time__s": {
"description": "Timestamp when the role was last modified",
"type": [
"string",
"null"
],
"format": "date-time"
},
"created_time__s": {
"description": "Timestamp when the role was created",
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"required": [
"display_label",
"forecast_manager",
"reporting_to",
"share_with_peers",
"description",
"id",
"name",
"created_by__s",
"modified_by__s",
"modified_time__s",
"created_time__s"
]
}
}
},
"required": [
"roles"
]
}
}
}
}
},
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.settings.roles.READ"
]
}
]
},
"post": {
"operationId": "createRoles",
"summary": "Create new roles",
"description": "Create one or more new CRM roles in the organization",
"requestBody": {
"content": {
"application/json": {
"schema": {
"description": "Request body for creating roles",
"type": "object",
"additionalProperties": false,
"properties": {
"roles": {
"description": "Array of role objects to create",
"type": "array",
"maxItems": 100,
"items": {
"description": "Role object to create",
"type": "object",
"additionalProperties": false,
"properties": {
"reporting_to": {
"description": "Parent role information",
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"description": "Unique identifier of the parent role",
"type": [
"string",
"null"
],
"maxLength": 19
}
}
},
"share_with_peers": {
"description": "Whether this role can share data with peer roles",
"type": [
"boolean",
"null"
]
},
"description": {
"description": "Detailed description of the role",
"type": [
"string",
"null"
],
"maxLength": 250
},
"name": {
"description": "Display name of the role",
"type": "string",
"maxLength": 200
}
},
"required": [
"name",
"reporting_to"
]
}
}
},
"required": [
"roles"
]
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Role created successfully",
"content": {
"application/json": {
"schema": {
"description": "Response for successful role creation",
"type": "object",
"additionalProperties": false,
"properties": {
"roles": {
"description": "Array of creation results",
"type": "array",
"maxItems": 100,
"items": {
"description": "Individual creation result",
"type": "object",
"additionalProperties": false,
"properties": {
"code": {
"description": "Operation result code",
"type": "string",
"enum": [
"SUCCESS"
]
},
"details": {
"description": "Additional details about the operation",
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"description": "Unique identifier of the created role",
"type": "string",
"maxLength": 19
}
},
"required": [
"id"
]
},
"message": {
"description": "Human readable success message",
"type": "string",
"maxLength": 100
},
"status": {
"description": "Operation status",
"type": "string",
"enum": [
"success"
]
}
},
"required": [
"code",
"details",
"message",
"status"
]
}
}
},
"required": [
"roles"
]
}
}
}
},
"400": {
"description": "Bad request | The request is invalid",
"content": {
"application/json": {
"schema": {
"description": "Error response for role creation",
"oneOf": [
{
"description": "Individual role creation failure results",
"type": "object",
"additionalProperties": false,
"properties": {
"roles": {
"description": "Array of error details",
"type": "array",
"maxItems": 100,
"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"
]
},
"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": [
"roles"
]
},
{
"description": "Individual role creation failure results",
"type": "object",
"additionalProperties": false,
"properties": {
"roles": {
"description": "Array of error details",
"type": "array",
"maxItems": 100,
"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": [
"INVALID_DATA"
]
},
"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": [
"roles"
]
},
{
"description": "Individual role creation failure results",
"type": "object",
"additionalProperties": false,
"properties": {
"roles": {
"description": "Array of error details",
"type": "array",
"maxItems": 100,
"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": [
"INVALID_DATA"
]
},
"message": {
"description": "Human readable error message",
"type": "string",
"maxLength": 500
},
"details": {
"description": "Additional error details",
"type": "object",
"additionalProperties": false,
"properties": {
"maximum_length": {
"description": "Maximum allowed length",
"type": "integer",
"format": "int32"
},
"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": [
"maximum_length",
"api_name",
"json_path"
]
}
},
"required": [
"status",
"code",
"message",
"details"
]
}
}
},
"required": [
"roles"
]
},
{
"description": "Mandatory parameter missing error",
"type": "object",
"additionalProperties": false,
"properties": {
"code": {
"description": "Error code",
"type": "string",
"enum": [
"MANDATORY_PARAM_MISSING"
]
},
"message": {
"description": "Human readable error message",
"type": "string",
"maxLength": 500
},
"status": {
"description": "Error status",
"type": "string",
"enum": [
"error"
]
},
"details": {
"description": "Additional error details",
"type": "object",
"additionalProperties": false,
"properties": {
"api_name": {
"description": "Name of the missing parameter",
"type": "string",
"maxLength": 100
}
}
}
},
"required": [
"code",
"message",
"status"
]
},
{
"description": "Operation not allowed error",
"type": "object",
"additionalProperties": false,
"properties": {
"code": {
"description": "Error code",
"type": "string",
"enum": [
"NOT_ALLOWED"
]
},
"message": {
"description": "Human readable error message",
"type": "string",
"maxLength": 500
},
"status": {
"description": "Error status",
"type": "string",
"enum": [
"error"
]
},
"details": {
"description": "Additional error details",
"type": "object",
"additionalProperties": true
}
},
"required": [
"code",
"message",
"status"
]
}
]
}
}
}
}
},
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.settings.roles.CREATE"
]
}
]
},
"put": {
"operationId": "updateRoles",
"summary": "Update multiple roles",
"description": "Update multiple CRM roles in the organization",
"requestBody": {
"content": {
"application/json": {
"schema": {
"description": "Request body for updating multiple roles",
"type": "object",
"additionalProperties": false,
"properties": {
"roles": {
"description": "Array of role objects to update",
"type": "array",
"maxItems": 100,
"items": {
"description": "Role object with updated values",
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"description": "Unique identifier of the role to update",
"type": "string",
"maxLength": 19
},
"reporting_to": {
"description": "Parent role information",
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"description": "Unique identifier of the parent role",
"type": [
"string",
"null"
],
"maxLength": 19
}
}
},
"forecast_manager": {
"description": "Forecast manager information",
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"description": "Unique identifier of the forecast manager",
"type": [
"string",
"null"
],
"maxLength": 19
},
"name": {
"description": "Display name of the forecast manager",
"type": [
"string",
"null"
],
"maxLength": 255
}
}
},
"share_with_peers": {
"description": "Whether this role can share data with peer roles",
"type": "boolean"
},
"description": {
"description": "Detailed description of the role",
"type": [
"string",
"null"
],
"maxLength": 250
},
"name": {
"description": "Display name of the role",
"type": "string",
"maxLength": 200
}
},
"required": [
"id"
]
}
}
},
"required": [
"roles"
]
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Roles updated successfully",
"content": {
"application/json": {
"schema": {
"description": "Response for successful roles update",
"type": "object",
"additionalProperties": false,
"properties": {
"roles": {
"description": "Array of update results",
"type": "array",
"maxItems": 100,
"items": {
"description": "Individual update result",
"type": "object",
# --- truncated at 32 KB (81 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho-crm/refs/heads/main/openapi/zoho-crm-roles-openapi.json