Zoho CRM Layouts API

openapi: 3.2.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
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:
  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'
  schemas:
    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
    ModuleName:
      type: string
      pattern: ^[A-Za-z0-9_]+$
      minLength: 1
      maxLength: 50
      description: Module API name
    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
    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
    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
    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
    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
    Id:
      type: string
      format: int64
      pattern: ^[0-9]{1,19}$
      minLength: 1
      maxLength: 19
      description: Unique identifier (64-bit integer represented as string)
    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
    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
    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
    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
  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'
  securitySchemes:
    iam-oauth2-schema:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          tokenUrl: https://accounts.zoho.com/oauth/v2/token
          refreshUrl: https://accounts.zoho.com/oauth/v2/token
          scopes:
            ZohoCRM.settings.ALL: All access to CRM settings
            ZohoCRM.settings.layouts.ALL: All access to CRM layouts
            ZohoCRM.settings.layouts.READ: Read access to CRM layouts
            ZohoCRM.settings.layouts.UPDATE: Update access to CRM layouts
            ZohoCRM.settings.layouts.DELETE: Delete access to CRM layouts
            ZohoCRM.settings.convert_mapping.UPDATE: Update access to CRM layout convert mappings