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