CRUD operations on Layout customization for modules in Zoho CRM. Supports getting the details of all layouts or a specific layout of a module, updating a layout, deactivating/activating a layout, and deleting a layout.
{
"openapi": "3.1.0",
"info": {
"title": "Layouts API",
"description": "CRUD operations on Layout customization for modules in Zoho CRM. Supports getting the details of all layouts or a specific layout of a module, updating a layout, deactivating/activating a layout, and deleting a layout.",
"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"
}
}
}
],
"paths": {
"/settings/layouts": {
"get": {
"summary": "Get all layouts metadata for a module",
"description": "Retrieves comprehensive details of all layouts associated with a specified module in your Zoho CRM account. Returns layout configuration including sections, fields, profiles, and permissions in a single response without pagination.\n\n**Important Notes:**\n- The `profiles` array will be `null` if the user does not have \"Module Customization\" permission in their profile.\n- For Deals module: When the pipeline feature is enabled, multiple layouts exist per pipeline. Each pipeline can have its own set of layouts.\n- The `mode` parameter supports different values based on module type. Common modes include `business_card` and `quick_create`.\n- Score and Visit Summary sections are system-generated and read-only.\n- All layouts for the module are returned in a single response; pagination is not supported.",
"operationId": "getLayouts",
"parameters": [
{
"$ref": "#/components/parameters/ModuleParameter"
},
{
"$ref": "#/components/parameters/ModeParameter"
},
{
"$ref": "#/components/parameters/Includes"
},
{
"$ref": "#/components/parameters/IncludeInnerDetails"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/LayoutSuccessResponse"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/UnauthorizedResponse"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalServerErrorResponse"
}
},
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.settings.layouts.READ"
]
}
]
}
},
"/settings/layouts/{id}": {
"get": {
"summary": "Get a specific layout metadata by ID",
"description": "Retrieves comprehensive details of a specific layout by its unique identifier for a specified module in your Zoho CRM account. Returns layout configuration including sections, fields, profiles, and permissions.\n\n**Important Notes:**\n- The `profiles` array will be `null` if the user does not have \"Module Customization\" permission in their profile.\n- For Deals module: When the pipeline feature is enabled, multiple layouts exist per pipeline. Each pipeline can have its own set of layouts.\n- The `mode` parameter supports different values based on module type. Common modes include `business_card` and `quick_create`.\n- Score and Visit Summary sections are system-generated and read-only.\n\n**Prerequisite:** The Layout ID can be obtained from the Get All Layouts API.",
"operationId": "getLayoutById",
"parameters": [
{
"$ref": "#/components/parameters/LayoutIdParameter"
},
{
"$ref": "#/components/parameters/ModuleParameter"
},
{
"$ref": "#/components/parameters/ModeParameter"
},
{
"$ref": "#/components/parameters/Includes"
},
{
"$ref": "#/components/parameters/IncludeInnerDetails"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/LayoutSuccessResponse"
},
"204": {
"description": "No Content - No associations match the specified filter criteria or the requested page number exceeds available results"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/UnauthorizedResponse"
},
"500": {
"$ref": "#/components/responses/InternalServerErrorResponse"
}
},
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.settings.layouts.READ"
]
}
]
},
"patch": {
"operationId": "updateLayout",
"summary": "Update a Layout",
"description": "Update a custom layout in Zoho CRM. You can rename the layout, add/remove profile permissions, enable/disable business card, create/update/delete sections, and add/update/delete/move fields within sections. Limits: Maximum 5 sections per request and maximum 5 fields total across all sections per request.",
"tags": [
"Layouts"
],
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.settings.layouts.UPDATE"
]
}
],
"parameters": [
{
"$ref": "#/components/parameters/LayoutIdParameter"
},
{
"$ref": "#/components/parameters/ModuleParameter"
}
],
"requestBody": {
"required": true,
"description": "Layout update request body containing the layout modifications. Only a single layout can be updated per request. Maximum 5 sections and 5 fields (total across all sections) can be modified per request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateLayoutRequest"
}
}
}
},
"responses": {
"200": {
"description": "Layout updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateLayoutSuccessResponse"
}
}
}
},
"400": {
"description": "Bad Request - Invalid data or parameters provided",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateLayoutErrorResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedResponse"
},
"403": {
"description": "Forbidden - User lacks required permissions to update the layout",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"405": {
"description": "Method Not Allowed - Invalid request method used",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"$ref": "#/components/responses/InternalServerErrorResponse"
}
}
},
"delete": {
"operationId": "deleteLayout",
"summary": "Delete a custom layout",
"description": "Deletes a custom layout from a module in Zoho CRM. When deleting a layout that has associated records, you must specify a `transfer_to` layout ID to transfer those records. If the layout has an associated pipeline, you must also provide `pipeline` and `stage` parameters. The `transfer_to` parameter is only optional when the layout is deactivated and has no records associated with it. Note: The standard layout cannot be deleted.",
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.settings.layouts.DELETE"
]
}
],
"parameters": [
{
"$ref": "#/components/parameters/LayoutIdParameter"
},
{
"$ref": "#/components/parameters/ModuleParameter"
},
{
"$ref": "#/components/parameters/TransferToParameter"
},
{
"$ref": "#/components/parameters/PipelineParameter"
},
{
"$ref": "#/components/parameters/StageParameter"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/DeleteLayoutSuccessResponse"
},
"400": {
"$ref": "#/components/responses/DeleteLayoutBadRequestResponse"
},
"401": {
"$ref": "#/components/responses/UnauthorizedResponse"
},
"403": {
"description": "Forbidden - User lacks required permissions to delete the layout",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"$ref": "#/components/responses/InternalServerErrorResponse"
}
}
}
},
"/settings/layouts/{id}/convert_mapping": {}
},
"components": {
"parameters": {
"LayoutIdParameter": {
"name": "id",
"in": "path",
"required": true,
"description": "Unique identifier of the layout. Must be a valid 64-bit integer represented as a string. Can be obtained from the Get Layouts API.",
"schema": {
"$ref": "#/components/schemas/Id"
}
},
"ModuleParameter": {
"name": "module",
"in": "query",
"required": true,
"description": "Specify the API name of the required module. Supports both standard modules (Leads, Accounts, Contacts, Deals, Campaigns, Tasks, Cases, Events, Calls, Solutions, Products, Vendors, Price_Books, Quotes, Sales_Orders, Purchase_Orders, Invoices, Appointments, Services) and custom modules. Module API names are case-insensitive, can contain alphanumeric characters and underscores, must not contain spaces, and have a maximum length of 50 characters. Use the GET - Modules Metadata API to retrieve all available module API names.",
"schema": {
"$ref": "#/components/schemas/ModuleName"
}
},
"ModeParameter": {
"name": "mode",
"in": "query",
"required": false,
"description": "Filter layouts by mode. Available modes vary by module type:\n- `business_card`: Business card layout view\n- `quick_create`: Quick create form layout\n- `all`: Request all available modes\n\nIf not provided, the default mode for the module will be applied. Note: Mode availability depends on the module and its configuration.",
"schema": {
"type": "string",
"enum": [
"all",
"business_card",
"quick_create"
]
}
},
"TransferToParameter": {
"name": "transfer_to",
"in": "query",
"required": false,
"description": "The ID of the layout to which records associated with the layout being deleted should be transferred. This parameter is conditionally mandatory - it is required when the layout has records associated with it. It is only optional when the layout is deactivated and has no records associated. The target layout must be an active layout; transferring to a deactivated layout is not allowed.",
"schema": {
"$ref": "#/components/schemas/Id"
}
},
"PipelineParameter": {
"name": "pipeline",
"in": "query",
"required": false,
"description": "The ID of the pipeline to transfer records to. This parameter is conditionally mandatory - it must be provided along with the `stage` parameter when the layout being deleted has an associated pipeline. Required for modules like Deals that support pipeline stages.",
"schema": {
"$ref": "#/components/schemas/Id"
}
},
"StageParameter": {
"name": "stage",
"in": "query",
"required": false,
"description": "The ID of the stage within the pipeline to transfer records to. This parameter is conditionally mandatory - it must be provided along with the `pipeline` parameter when the layout being deleted has an associated pipeline. The stage must be a valid stage within the specified pipeline.",
"schema": {
"$ref": "#/components/schemas/Id"
}
},
"Includes": {
"name": "include",
"in": "query",
"required": false,
"description": "Specifies additional data to include in the response.",
"schema": {
"type": "string",
"enum": [
"total_profiles",
"portal_user_types"
]
}
},
"IncludeInnerDetails": {
"name": "include_inner_details",
"in": "query",
"required": false,
"description": "Specifies additional inner details to include in the response. Accepts a comma-separated list of dot-notation paths indicating which nested properties should return extended information.",
"schema": {
"type": "string",
"pattern": "^[a-z_]+(\\.[a-z_]+)?(,[a-z_]+(\\.[a-z_]+)?)*$",
"maxLength": 255
}
}
},
"responses": {
"LayoutSuccessResponse": {
"description": "Successfully retrieved all layouts for the specified module. Returns complete layout metadata including sections, fields, profiles, and permissions. Note: The `profiles` array will be `null` if the user lacks Module Customization permission. All layouts are returned in a single response without pagination.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LayoutResponseSchema"
}
}
}
},
"BadRequest": {
"description": "Bad Request - Invalid or missing parameters.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Error response for bad requests",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"description": "Error code indicating the type of bad request",
"enum": [
"REQUIRED_PARAM_MISSING",
"INVALID_MODULE",
"INVALID_REQUEST_METHOD",
"PATTERN_NOT_MATCHED",
"NOT_SUPPORTED"
]
},
"details": {
"type": "object",
"description": "Additional details about the error, such as the missing or invalid parameter name",
"additionalProperties": false,
"properties": {
"param_name": {
"type": "string",
"description": "Name of the parameter that caused the error",
"maxLength": 100
}
}
},
"message": {
"type": "string",
"description": "Human-readable error message",
"maxLength": 255
},
"status": {
"type": "string",
"description": "Status of the response, always 'error' for error responses",
"enum": [
"error"
]
}
},
"required": [
"code",
"details",
"message",
"status"
]
}
}
}
},
"DeleteLayoutSuccessResponse": {
"description": "Layout deleted successfully. The response contains the ID of the deleted layout.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteLayoutSuccessResponseBody"
}
}
}
},
"DeleteLayoutBadRequestResponse": {
"description": "Bad Request - Invalid or missing parameters, or operation not allowed",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/ErrorResponse"
},
{
"$ref": "#/components/schemas/LayoutErrorResponse"
}
]
}
}
}
},
"UnauthorizedResponse": {
"description": "Unauthorized - Authentication failed or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"NotFound": {
"description": "Not Found - Invalid URL pattern.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Error response for invalid URL patterns",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"description": "Error code indicating invalid URL pattern",
"enum": [
"INVALID_URL_PATTERN"
]
},
"details": {
"type": "object",
"description": "Additional details about the URL error",
"additionalProperties": false
},
"message": {
"type": "string",
"description": "Human-readable error message",
"maxLength": 255
},
"status": {
"type": "string",
"description": "Status of the response, always 'error' for error responses",
"enum": [
"error"
]
}
},
"required": [
"code",
"details",
"message",
"status"
]
}
}
}
},
"InternalServerErrorResponse": {
"description": "Internal Server Error - An unexpected error occurred on the server",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"schemas": {
"Id": {
"type": "string",
"format": "int64",
"pattern": "^[0-9]{1,19}$",
"minLength": 1,
"maxLength": 19,
"description": "Unique identifier (64-bit integer represented as string)"
},
"ApiName": {
"type": "string",
"pattern": "^[A-Za-z][A-Za-z0-9_]*$",
"minLength": 1,
"maxLength": 50,
"description": "API identifier using alphanumeric characters and underscores, must start with a letter"
},
"ModuleName": {
"type": "string",
"pattern": "^[A-Za-z0-9_]+$",
"minLength": 1,
"maxLength": 50,
"description": "Module API name"
},
"TypeNull": {
"type": "null",
"description": "Represents a null value"
},
"UserReference": {
"type": "object",
"description": "Reference to a user who performed an action",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"description": "Display name of the user",
"minLength": 1,
"maxLength": 100
},
"id": {
"$ref": "#/components/schemas/Id"
}
},
"required": [
"name",
"id"
]
},
"ActionsAllowed": {
"type": "object",
"description": "Permissions indicating which operations are allowed on a section",
"additionalProperties": false,
"properties": {
"add_field": {
"type": "boolean",
"description": "Permission to add new fields"
},
"rename": {
"type": "boolean",
"description": "Permission to rename the section"
},
"change_tab_traversal": {
"type": "boolean",
"description": "Permission to change tab traversal order"
},
"reorder": {
"type": "boolean",
"description": "Permission to reorder items"
},
"delete": {
"type": "boolean",
"description": "Permission to delete the section"
},
"remove_field": {
"type": "boolean",
"description": "Permission to remove fields"
},
"change_column_count": {
"type": "boolean",
"description": "Permission to change column layout"
}
},
"required": [
"add_field",
"rename",
"change_tab_traversal",
"reorder",
"delete",
"remove_field",
"change_column_count"
]
},
"LayoutActionsAllowed": {
"type": "object",
"description": "Permissions indicating which operations are allowed on a layout",
"additionalProperties": false,
"properties": {
"edit": {
"type": "boolean",
"description": "Permission to edit the layout"
},
"rename": {
"type": "boolean",
"description": "Permission to rename the layout"
},
"clone": {
"type": "boolean",
"description": "Permission to clone the layout"
},
"downgrade": {
"type": "boolean",
"description": "Permission to downgrade the layout"
},
"delete": {
"type": "boolean",
"description": "Permission to delete the layout"
},
"deactivate": {
"type": "boolean",
"description": "Permission to deactivate the layout"
},
"set_layout_permissions": {
"type": "boolean",
"description": "Permission to set layout-level permissions"
}
},
"required": [
"edit",
"rename",
"clone",
"downgrade",
"delete",
"deactivate",
"set_layout_permissions"
]
},
"ProfileReference": {
"type": "object",
"description": "Profile associated with a layout",
"additionalProperties": true,
"properties": {
"_default_assignment_view": {
"type": "object",
"description": "Default view used for record assignment",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"description": "Name of the assignment view",
"minLength": 1,
"maxLength": 100
},
"id": {
"$ref": "#/components/schemas/Id"
},
"type": {
"type": "string",
"description": "Type of view for assignment. Can be 'canvas' or 'layout'",
"enum": [
"canvas",
"layout"
]
}
},
"required": [
"name",
"id",
"type"
]
},
"default": {
"type": "boolean",
"description": "Indicates if this is the default profile for the layout"
},
"name": {
"type": "string",
"description": "Profile name",
"minLength": 1,
"maxLength": 60
},
"id": {
"$ref": "#/components/schemas/Id"
},
"_default_view": {
"type": "object",
"description": "Default view for this profile",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"description": "Name of the default view",
"minLength": 1,
"maxLength": 100
},
"id": {
"$ref": "#/components/schemas/Id"
},
"type": {
"type": "string",
"description": "Type of default view. Can be 'layout' or 'wizard'",
"enum": [
"layout",
"wizard"
]
}
},
"required": [
"name",
"id",
"type"
]
},
"type": {
"type": "string",
"description": "To identify the profile type",
"enum": [
"normal_profile",
"lite_profile"
]
}
},
"required": [
"_default_assignment_view",
"default",
"name",
"id",
"_default_view"
]
},
"ConvertMappingModule": {
"description": "Convert mapping configuration that defines how records are mapped during conversion. The structure varies based on the module type:\n- **Leads module**: Maps to Contacts, Deals, and Accounts modules during lead conversion.\n- **Quotes module**: Maps to SalesOrders and Invoices modules during quote conversion.\n- **Sales_Orders module**: Maps to Invoices module during sales order conversion.",
"oneOf": [
{
"type": "object",
"title": "Leads Convert Mapping",
"description": "Lead conversion mapping configuration for mapping lead data to Contacts, Deals, and Accounts modules.",
"additionalProperties": false,
"properties": {
"Contacts": {
"$ref": "#/components/schemas/ConvertMappingTargetModule"
},
"Deals": {
"$ref": "#/components/schemas/ConvertMappingTargetModuleWithFields"
},
"Accounts": {
"$ref": "#/components/schemas/ConvertMappingTargetModule"
}
},
"required": [
"Contacts",
"Deals",
"Accounts"
]
},
{
"type": "object",
"title": "Quotes Convert Mapping",
"description": "Quote conversion mapping configuration for mapping quote data to SalesOrders and Invoices modules.",
"additionalProperties": false,
"properties": {
"SalesOrders": {
"$ref": "#/components/schemas/ConvertMappingTargetModule"
},
"Invoices": {
"$ref": "#/components/schemas/ConvertMappingTargetModule"
}
},
"required": [
"SalesOrders",
"Invoices"
]
},
{
"type": "object",
"title": "Sales Orders Convert Mapping",
"description": "Sales order conversion mapping configuration for mapping sales order data to Invoices module.",
"additionalProperties": false,
"properties": {
"Invoices": {
"$ref": "#/components/schemas/ConvertMappingTargetModule"
}
},
"required": [
"Invoices"
]
},
{
"type": "object",
"title": "No Convert Mapping",
"description": "Empty object indicating no convert mapping is configured for this field. Returned for fields in modules that do not support conversion or fields that are not mapped during conversion.",
"additionalProperties": false,
"maxProperties": 0
}
]
},
"ConvertMappingTargetModule": {
"type": "object",
"description": "Target layout configuration for a module during record conversion.",
"additionalProperties": false,
"properties": {
"display_label": {
"type": "string",
"description": "Display label of the target layout shown in the UI.",
"maxLength": 255
},
"name": {
"type": "string",
"description": "API name of the target layout.",
"maxLength": 255
},
"id": {
"$ref": "#/components/schemas/Id",
"description": "Unique identifier of the target layout."
}
},
"required": [
"display_label",
"name",
"id"
]
},
"ConvertMappingTargetModuleWithFields": {
"type": "object",
"description": "Target layout configuration for a module during record conversion, including required fields that must be populated.",
"additionalProperties": false,
"properties": {
"display_label": {
"type": "string",
"description": "Display label of the target layout shown in the UI.",
"maxLength": 255
},
"name": {
"type": "string",
"description": "API name of the target layout.",
"maxLength": 255
},
"id": {
"$ref": "#/components/schemas/Id",
"description": "Unique identifier of the target layout."
},
"fields": {
"type": "array",
"description": "List of fields in the target layout that are relevant during conversion. Includes both mandatory and optional fields that can be populated during conversion.",
"maxItems": 100,
"items": {
"type": "object",
"description": "Field configuration for the target module during conversion.",
"additionalProperties": false,
"properties": {
"api_name": {
"$ref": "#/components/schemas/ApiName",
"description": "API name of the field in the target module."
},
"field_label": {
"type": "string",
"description": "Display label of the field shown in the UI.",
"maxLength": 255
},
"id": {
"$ref": "#/components/schemas/Id",
"description": "Unique identifier of the field."
},
"required": {
"type": "boolean",
"description": "Indicates whether this field is mandatory during conversion."
}
},
"required": [
"api_name",
"field_label",
"id",
"required"
]
}
}
},
"required": [
"display_label",
"name",
"id",
"fields"
]
},
"SectionProperties": {
"type": "object",
"description": "Additional properties for subform sections",
"additionalProperties": false,
"properties": {
"reorder_rows": {
"type": "boolean",
"description": "Allows reordering of subform rows"
},
"bulk_addition": {
"oneOf": [
{
"type": "boolean",
"description": "Enables bulk addition of subform entries"
},
{
"$ref": "#/components/schemas/T
# --- truncated at 32 KB (177 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho-crm/refs/heads/main/openapi/zoho-crm-layouts-openapi.json