openapi: 3.1.0 info: title: Helpcenter Layouts API version: 1.0.0 tags: - name: Layouts paths: /settings/layouts/{id}: 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' components: parameters: 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' 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' schemas: UpdateLayoutErrorResponse: type: object description: Error response for layout update operation. properties: layouts: type: array description: Array containing the error result of the layout update operation. items: $ref: '#/components/schemas/LayoutUpdateErrorResult' minItems: 1 maxItems: 1 code: type: string description: Error code for non-layout-wrapped errors. maxLength: 255 details: $ref: '#/components/schemas/ErrorDetails' message: type: string description: Error message. maxLength: 255 status: type: string description: Status indicator. enum: - error additionalProperties: false ProfileUpdateObject: type: object description: Profile object for adding or removing profile permissions. required: - id properties: id: $ref: '#/components/schemas/Id' description: Unique identifier of the profile. _delete: type: boolean description: Set to true to remove this profile's access to the layout. additionalProperties: false ModuleName: type: string pattern: ^[A-Za-z0-9_]+$ minLength: 1 maxLength: 50 description: Module API name ErrorResponse: type: object description: Standard error response structure required: - code - details - message - status properties: code: type: string description: Machine-readable error code enum: - REQUIRED_PARAM_MISSING - DEPENDENT_PARAM_MISSING - INVALID_MODULE - INVALID_DATA - NOT_SUPPORTED - NOT_ALLOWED - AUTHENTICATION_FAILURE - OAUTH_SCOPE_MISMATCH - INVALID_REQUEST_METHOD - INTERNAL_ERROR - NO_PERMISSION details: $ref: '#/components/schemas/ErrorDetails' message: type: string description: Human-readable error message maxLength: 1000 status: type: string enum: - error description: Status indicator for the response additionalProperties: false UpdateLayoutRequest: type: object description: Request body for updating a layout. Only a single layout can be updated per request. required: - layouts properties: layouts: type: array description: Array containing exactly one layout object with update properties. Only single layout updates are supported per request. minItems: 1 maxItems: 1 items: $ref: '#/components/schemas/LayoutUpdateObject' additionalProperties: false LayoutUpdateErrorResult: type: object description: Error result for a layout update. required: - code - details - message - status properties: code: type: string description: Error code. enum: - INVALID_DATA - MANDATORY_NOT_FOUND - NOT_ALLOWED - LIMIT_EXCEEDED - DUPLICATE_DATA - EXPECTED_FIELD_MISSING - DEPENDENT_FIELD_MISSING details: $ref: '#/components/schemas/LayoutUpdateErrorDetails' message: type: string description: Human-readable error message. maxLength: 1000 status: type: string description: Status indicator. enum: - error additionalProperties: false DeleteObject: type: object description: Delete configuration object. required: - permanent properties: permanent: type: boolean description: If true, permanently deletes the resource. If false, moves it to unused section (for fields). additionalProperties: false LayoutUpdateSuccessResult: type: object description: Success result for a layout update. required: - code - details - message - status properties: code: type: string description: Success code. enum: - SUCCESS details: type: object description: Details about the updated layout. required: - id properties: id: $ref: '#/components/schemas/Id' description: Unique identifier of the updated layout. additionalProperties: false message: type: string description: Success message. maxLength: 255 status: type: string description: Status indicator. enum: - success additionalProperties: false FieldUpdateObject: type: object description: Field object for adding, updating, creating, or removing fields from a section. For adding an existing field, provide only id. For updating field position, provide id and sequence_number. For creating a new field, provide field_label, data_type, and optionally length and sequence_number. For removing/moving a field, provide id and _delete object. minProperties: 1 properties: id: $ref: '#/components/schemas/Id' description: Unique identifier of an existing field. Required when adding, updating position, or removing an existing field. Omit when creating a new custom field. field_label: type: string description: Display label for the field. Required when creating a new custom field. minLength: 1 maxLength: 255 data_type: type: string description: Data type of the field. Required when creating a new custom field. Determines the field's input type and validation. enum: - text - textarea - email - phone - website - integer - bigint - currency - double - percent - date - datetime - boolean - picklist - multiselectpicklist - lookup - multiselectlookup - autonumber - fileupload - imageupload - formula - rollup_summary - consent_lookup - profileimage - richtextarea - userlookup - multiuserlookup - event_reminder length: type: integer format: int32 description: Maximum length of the field value in characters. Applicable for text-type fields (text, textarea, richtextarea). minimum: 1 maximum: 32000 sequence_number: type: integer format: int32 description: Position/order of the field within the section (1-based). Lower numbers appear first. minimum: 1 _delete: $ref: '#/components/schemas/DeleteObject' description: Delete configuration for removing the field. Set permanent to false to move to unused section (can be re-added later), true to permanently delete the field and its data. additionalProperties: false ErrorDetails: type: object description: Additional context-specific error details. Properties vary based on error type. properties: param_name: type: string description: Name of the parameter that caused the error. maxLength: 100 id: $ref: '#/components/schemas/Id' description: Resource ID related to the error, if applicable. expected_data_type: type: string description: Expected data type for the parameter. maxLength: 50 supported_values: type: array description: List of supported values when applicable. items: description: A supported value type: string maxLength: 100 maxItems: 10 dependee: type: object description: Details about the parameter that the missing dependent parameter depends on. additionalProperties: false properties: param_name: type: string description: Name of the dependee parameter that requires the dependent parameter to be specified. maxLength: 100 resource_path_index: type: integer format: int32 description: Index in the resource path where the error occurred. Typically indicates the position of the invalid ID in the URL path. permissions: type: array description: List of permissions required to perform the action. Returned when the user lacks necessary permissions. items: type: string description: Permission identifier required for the action. maxLength: 100 maxItems: 20 additionalProperties: true UpdateLayoutSuccessResponse: type: object description: Successful response for layout update operation. required: - layouts properties: layouts: type: array description: Array containing the result of the layout update operation. items: $ref: '#/components/schemas/LayoutUpdateSuccessResult' minItems: 1 maxItems: 1 additionalProperties: false SectionUpdateObject: type: object description: Section object for creating, updating, or deleting sections. For creating a new section, provide name, display_label, sequence_number, tab_traversal, and column_count. For updating an existing section, provide id along with properties to update. For deleting a section, provide id and _delete object. minProperties: 1 properties: id: $ref: '#/components/schemas/Id' description: Unique identifier of the section. Required for updating or deleting existing sections. Omit when creating a new section. name: type: string description: Internal API name of the section. Required when creating a new section. Should be unique within the layout. minLength: 1 maxLength: 255 display_label: type: string description: Display label shown in the UI for the section. Required when creating a new section. minLength: 1 maxLength: 255 sequence_number: type: integer format: int32 description: Position/order of the section in the layout (1-based). Required when creating a new section. Lower numbers appear first. minimum: 1 maximum: 100 tab_traversal: type: string description: Tab traversal mode for the section. Defines how tab key navigation works within the section. 1 = column-wise, 2 = row-wise. enum: - left_to_right - top_to_bottom column_count: type: integer format: int32 description: Number of columns in the section layout. minimum: 1 maximum: 2 fields: type: array description: 'Array of field objects to add, update, create, or remove from this section. Note: Total fields across all sections in the request must not exceed 5.' items: $ref: '#/components/schemas/FieldUpdateObject' minItems: 1 maxItems: 5 _delete: $ref: '#/components/schemas/DeleteObject' description: Delete configuration for removing the section. When provided, the section identified by id will be deleted. additionalProperties: true Id: type: string format: int64 pattern: ^[0-9]{1,19}$ minLength: 1 maxLength: 19 description: Unique identifier (64-bit integer represented as string) LayoutUpdateErrorDetails: type: object description: Error details specific to layout update operations. properties: api_name: type: string description: API name of the field that caused the error. maxLength: 100 json_path: type: string description: JSON path to the field that caused the error. maxLength: 500 expected_data_type: type: string description: Expected data type for the field. maxLength: 50 maximum_length: type: integer format: int32 description: Maximum allowed length for the field. limit: type: integer format: int32 description: Maximum limit exceeded. additionalProperties: true LayoutUpdateObject: type: object description: Layout object containing the fields to update. At least one property must be provided. Maximum 5 sections and 5 fields (total across all sections) can be modified per request. minProperties: 1 properties: name: type: string description: New name for the layout. Must be unique within the module. minLength: 1 maxLength: 255 show_business_card: type: boolean description: Enable or disable the business card display for this layout. profiles: type: array description: Array of profile objects to add or remove from the layout. items: $ref: '#/components/schemas/ProfileUpdateObject' minItems: 1 maxItems: 50 sections: type: array description: Array of section objects to create, update, or delete. Maximum 5 sections allowed per request. Total fields across all sections must not exceed 5. items: $ref: '#/components/schemas/SectionUpdateObject' minItems: 1 maxItems: 5 additionalProperties: false responses: InternalServerErrorResponse: description: Internal Server Error - An unexpected error occurred on the server content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' UnauthorizedResponse: description: Unauthorized - Authentication failed or invalid credentials content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: iam-oauth2-schema: $ref: ./Common.json#/components/securitySchemes/iam-oauth2-schema x-entity: Helpcenter