Update Custom Layout

Purpose

To update a custom layout.

Endpoints

PATCH /settings/layouts/{layout_id}?module={module_api_name}

Request Details

Request URL

{api-domain}/crm/{version}/settings/layouts/{layout_id}

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

scope = ZohoCRM.settings.layouts.UPDATE (or)
scope = ZohoCRM.settings.layouts.ALL (or)
scope = ZohoCRM.settings.ALL

Parameter

modulestring, mandatory
Specify the module API name where you want to update the custom a layout. Use the GET Module Metadata API to get the module API names. Supported modules are Leads, Contacts, Accounts, Deals, Products, Quotes, Sales Orders, Purchase, Orders, Invoices, Campaigns, Vendors, Price Books, Cases, Solutions, and Custom.

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v6/settings/layouts/5725767000002277002?module=Leads"
-X PATCH
-d "@input.json"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Input JSON Keys

sectionJSON array, optional
Each object in the array represents the details of sections in the current layout.
- idstring, optional (mandatory to update en existing section)
  Represents the unique ID of the section. Use the GET Layouts Metadata API, to retrieve unique section IDs.
- display_labelstring, mandatory (mandatory for section creation)
  Represents the display label of the section. A maximum of 50 characters, including spaces, is allowed. Note that the value of this field should not be empty, and only letters, numbers, and spaces are supported.
- fieldsJSON array, optional
  To create custom fields in a layout, refer to the Create Custom Field API. Each object in the fields JSON array represents the details of a field in the section.
  - field_labelstring, optional
    Represents the label of the field.
  - data_typestring, optional(The "datatype" or "id" is mandatory for updating a field)
    Represents the datatype of the field.
  - idstring, optional (The "datatype" or "id" is mandatory for updating a field)
    Represents the unique ID of the field.
  - _deleteJSON object, optional
    This key lets you to move fields from the current layout to Unused Items.
    - permanentboolean, mandatory
      Represents whether the fields should be temporarily moved to Unused Items. Possible Value : false.
  - requiredboolean, optional
    Specify whether a field should be mandatory or not. Note that you can only mark a field as mandatory using the Layouts API.

Notes

A maximum of five actions (create, update, or delete) can be performed on fields within the specified sections of a layout in a single APIcall.
Maximum of five sections can be created in a single API call.
The data types email and textarea do not support external fields.
In the tooltip key, the static_text value is limited to 35 characters, and the info_icon value is limited to 255 characters.
You can create a maximum of two unique fields per module in all editions.
You can create a maximum of one auto-number field in a module.
For more details about fields creation, see Create Custom Field API help document.
The unique key is not allowed for the imageupload data type.
The API name of a layout cannot be changed.
All the field types and their possible error cases, as explained in the Create Custom Field API and Update Custom Field API help documents, are applicable for creating and updating fields in a layout.

Sample input for manipulating fields within an existing layout

Copied{ //Creating, Updating, moving fields to "Unsed Items" in an existing sections in a layout
    "layouts": [
        {
            "sections": [
                {
                    "id": "5725767000002277007",
                    //manipulating fields in an existing layout under an existing section
                    "fields": [
                        {
                            "field_label": "Subcriber Namee",
                            "data_type": "text" //creating a new field
                        },
                        {
                            "id": "5725767000002235077", //existing field ID
                            "field_label": "Multiple Notes" //updating an existing field
                        },
                        {
                            "id": "5725767000002288647",
                            "_delete": {
                                "permanent": false //moving field to the "Unused Items"
                            }
                        },
                        {
                            "id": "5725767000003613091",
                            "required": true //Marking the field as mandatory. 
                        }
                    ]
                }
            ]
        }
    ]
}

Sample input to create a "New Section" and to update an existing section

Copied{ //Actions on creating a new section, updating an existing section
    "layouts": [
        {
            "sections": [
                {
                    "display_label": "Personal Details",
                    "fields": [
                        {
                            "field_label": "Age",
                            "data_type": "integer"
                        }
                    ]
                },
                {
                    "id": "5725767000002277006",
                    "display_label": "Profile"
                },
                {
                    "id": "5725767000002324138",
                    "_delete": {
                        "permanent": false //moving field to the "Unused Items"
                    }
                }
            ]
        }
    ]
}

Possible Errors

INVALID_DATAHTTP 400
- API name cannot be changed
  Resolution: Field API names in layouts can be edited only via UI.
- Invalid data.
  Resolution: The given input data seems to be invalid. Specify a valid input to update a layout. Refer to the Input JSON Keyssection above.
- Invalid ID
  Resolution: The provided field or section ID seems to be invalid. Please specify valid inputs to update a layout. To know the section IDs of the layouts, use the Layouts Metadata API.
- Invalid section name.
  Resolution: The provided section name seems to be invalid. Please specify a valid section name to update a layout.
- Invalid value of the tab_traversal key
  Resolution: Specify a valid value for the tab_traversal key. Supported values are top_to_bottom and left_to_right.
- Invalid value of the column_count key
  Resolution: Arrange a set of fields in a section in columns. Supported values are 1 and 2.
- Invalid value given for the name key of the tooltip
  Resolution: Specify a valid data. Supported values are static_text and info_icon.
EXPECTED_FIELD_MISSINGHTTP 400
One or more expected keys are missing
Resolutions:
- To update a section in a layout, section ID is mandatory. Use the Layouts Metadata API, to retrieve unique section IDs.
- To create a new section, the display_label key is mandatory. Refer to the above Input JSON Keys section.
NOT_ALLOWEDHTTP 400
- API name cannot be changed
  Resolutions: Field API names in layouts can be edited only via UI.
- The text area length cannot be changed
  Resolutions: The type value cannot be updated to another type, for example, from small to rich_text. Sample: "textarea" : { "type": "small" }.
- The API name of the Layout cannot be changed
  Resolutions: You cannot change the API name of the layout.
DEPENDENT_FIELD_MISSINGHTTP 400
One or more dependent fields are missing
Resolution: Specify all the dependent fields in the input body. Please refer above to the
DUPLICATE_DATAHTTP 400
Given input contains one or more duplicate section labels
Resolutions: Please specify unique section labels and a unique layout name. Refer to the above Input JSON Keys section.
EXPECTED_DEPENDENT_FIELD_MISSINGHTTP 400
Either global_picklist or picklist values is expected
Resolution: Specify the dependent fields to create a picklist or global picklist field in a layout. Refer to the Create Custom Field API for more information.
DEPENDENT_MISMATCHHTTP 400
The dependent keys of a field seem to be mismatched
Resolution: Specify valid dependent keys and their corresponding values for the fields. Refer to the Create Custom Field API for details on the fields and their dependent keys, along with examples.
NO_PERMISSIONHTTP 400
Permission denied
Resolution: You have no permission to update the layout. Contact your system administrator.
REQUIRED_PARAM_MISSINGHTTP 400
Required parameter is missing
Resolution: Specify a mandatory parameter. Refer to the Parameter section above.
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 the endpoints section above.
OAUTH_SCOPE_MISMATCHHTTP 401
Unauthorized
Resolution: The client does not have a valid scope to update a custom layout. Create a new token with the required scopes. Refer to the scope section above.
AUTHENTICATION_FAILUREHTTP 401
Authentication failed
Resolution: Pass the access token in the request header of the API call.
INVALID_URL_PATTERNHTTP 404
Please check if the URL trying to access is a correct one
Resolution: The request URL specified is incorrect. Specify a valid request URL. Refer to the request URL section above.
INTERNAL_ERRORHTTP 500
Internal Server Error
Resolution: Unexpected and unhandled exception in the server. Contact support team.

Sample Response

Copied{
    "layouts": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "5725767000002277002"
            },
            "message": "layout updated",
            "status": "success"
        }
    ]
}