CRM Developer Update: Mandatory field behavior changes in Zoho CRM APIs

CRM Developer Update: Mandatory field behavior changes in Zoho CRM APIs

                                                                                                
We are planning a few updates to Zoho CRM APIs that are expected to be rolled out by the end of October 2026. These changes are not live yet. We are sharing this early so developers and partners can review the impact and prepare in advance.

What is changing?

The Last_Name field in the Leads and Contacts modules will no longer be a system-mandatory field. Instead, you can configure either First_Name or Last_Name as the mandatory field based on your layout settings.

Where do these changes apply?

The updates impact the following APIs:

1. Metadata APIs:
  1. Fields Metadata API
  2. Layouts Metadata API (breaking change)
2. Records APIs:
  1. Create Records API
  2. Update Records API
  3. Upsert Records API
  4. Get Records API (breaking change)

1. Fields Metadata API and Layouts Metadata API (Breaking changes)

  1. The system_mandatory property for Last_Name in the Leads and Contacts module will be updated to false in both the Fields Metadata API and Layouts Metadata API responses.
  2. The child_fields key for the Full_Name field, which currently returns null, will now return details of the First_Name and Last_Name child fields.

Fields Metadata API

Breaking Change 1: Full_Name field

The Full_Name field will now include the child_fields property, which lists its child fields (First_Name and Last_Name).

                   Current response (V8)

      Future response (V8)

{

    "fields": [

        {

            "field_label": "Full Name",

            "display_label": "Full Name",

            "id": "2284759000000000597",

            "searchable": true,

            "show_type": 0,

            "external": null,

            "api_name": "Full_Name",

            "parent_field": null,

            "unique": {},

            "enable_colour_code": false,

            "child_fields": null

          ...//other fields

 

        }

    ]

}

{

    "fields": [

        {

            "field_label": "Full Name",

            "display_label": "Full Name",

            "id": "2284759000000000597",

            "searchable": true,

            "show_type": 0,

            "external": null,

            "api_name": "Full_Name",

            "parent_field": null,

            "unique": {},

            "enable_colour_code": false,

            "child_fields": [

                {

                    "sequence_number": 1,

                    "field": {

                        "api_name": "First_Name",

                        "name": "First Name",

                        "id": "2284759000003713005"

                    }

                },

                {

                    "sequence_number": 2,

                    "field": {

                        "api_name": "Last_Name",

                        "name": "Last Name",

                        "id": "2284759000003713006"

                    }

                }

            ],

           .

           .

           .

        }

    ]

}

  1. The required property in the Layouts Metadata API will be set to either true or false based on the user’s mandatory field configuration.
      Example:
    1. If First_Name is configured as mandatory, required will be true for First_Name.
    2. If Last_Name is configured as mandatory, required will be true for Last_Name.
Breaking change 2: Last_Name field

The system_mandatory property for the Last_Name field will change from true to false.

                   Current response (V8)

      Future response (V8)

{

    "fields": [

        {

            "field_label": "Last Name",

            "api_name": "Last_Name",

            "system_mandatory": true,

            ...//other fields

 

        }

    ]

}

{

    "fields": [

        {

            "field_label": "Last Name",

            "api_name": "Last_Name",

            "system_mandatory": false,

              ...//other fields

 

        }

    ]

}



Layouts metadata API (Breaking change)

The system_mandatory property for the Last_Name field will change from true to false. The required property indicates whether the field is mandatory in the current layout configuration.

                   Current response (V8)

      Future response (V8)

{

    "layouts": [

        {

            "sections": [

                {

                    "field_label": "Last Name",

                    "display_label": "Last Name",

                    "id": "5725767000000002595",

                    "api_name": "Last_Name",

                   "required": true,

                    "system_mandatory": true,

                },

               ...//other fields

 

            ]

        }

    ]

}

{

    "layouts": [

        {

            "sections": [

                {

                    "field_label": "Last Name",

                    "display_label": "Last Name",

                    "id": "5725767000000002595",

                    "api_name": "Last_Name",

                   "required": true,

                    "system_mandatory": false,

                },

                 ...//other fields

 

            ]

        }

    ]

}


Note: After this change, use the required property in the Layouts Metadata API to determine whether Last_Name is mandatory for a layout.

In a layout, either First_Name or Last_Name must always be mandatory, ensuring that the Full_Name field has a value.
Example:
  1. If an admin configures First_Name as mandatory and Last_Name as optional:
    1. First_Name: "required": true
    2. Last_Name: "required": false
  1. If an admin configures Last_Name as mandatory:
    1. First_Name: "required": false
    2. Last_Name: "required": true
In both cases, the system_mandatory property for Last_Name will remain "system_mandatory": false.

2. Record APIs: Create Record API, Update Record API, Upsert Records API, and Get Records API 

Currently, the Last_Name field is a system-mandatory field in the Leads and Contacts modules and is indicated by system_mandatory: true in the Fields Metadata API and Layouts Metadata API responses.
  1. The system_mandatory property for Last_Name will change from true to false. 
  2.  You can configure Last_Name as optional or mandatory based on your business requirements. 
  3.  You can also configure First_Name as a mandatory field. 
To determine whether a field is mandatory during record creation:
  1. Use the required property from the Layouts Metadata API to identify user-configured mandatory fields. 
  2. Do not rely solely on the system_mandatory property for the Last_Name field.

What's New?

  1. The Last_Name field will no longer be a system-mandatory field. Instead, it will be a layout-mandatory field by default, allowing administrators to configure it as optional if needed.
  2. As a result, the "system_mandatory" property will be updated to false ("system_mandatory": false).
Note: User-configured mandatory fields are indicated using the "required" property.

Record Creation Validation

The validation behavior depends on the following scenarios.

Common Validation

  1. The Full_Name field is stored as a combination of its child fields, First_Name and Last_Name. Therefore, the system validates that Full_Name is not null or empty. You must provide a value in either First_Name or Last_Name.
  2. If both First_Name and Last_Name are empty, the system returns the mandatory field validation error for the Last_Name field, even though the validation is performed on the Full_Name field. This preserves the existing error response for backward compatibility.

Scenario 1: No layout is specified

If no layout ID is provided in the request, the system validates the Full_Name field using its child fields (First_Name and Last_Name) at the module level.

Scenario 2: A layout is specified

If a layout ID is provided, the system validates all mandatory fields configured in the specified layout.
For example, if the layout is configured with:
  1. First_Name as mandatory 
  2. Email as mandatory 
both fields must be included in the request.

Example:
All mandatory fields defined in that layout must be provided in the request.

{

    "data": [

        {

            "Layout": {

                "id": "554023000002734009"

            },

            "First_Name": "Patricia",

            "Email": "patricia@zoho.com"

        }

    ]

}



Scenario 3: A layout is specified and skip_mandatory is true

If a layout ID is provided and skip_mandatory is set to true, the system skips validation of the user-configured mandatory fields in the specified layout.
Instead, it validates the Full_Name field using its child fields (First_Name and Last_Name) at the module level.

Get Records API (Breaking change)

Once this update goes live, users may configure First_Name as the mandatory field and Last_Name as non-mandatory.

If Last_Name is not provided during record creation or is cleared during an update:
  1. The API response will return an empty string ("") for the Last_Name ("Last_Name": "") field across all API versions.
  2. If Last_Name contains a value, it will be returned as usual.

Impact:

Existing integrations may assume that Last_Name always contains a value because it has historically been a system-mandatory field. After this update, Last_Name may be empty, and integrations should handle empty string values appropriately.

What you should do

  1. Review integrations that explicitly specify layouts during record creation.
  2. Handle empty values for Last_Name in Get Records API responses.
  3. Update any logic that depends on the system_mandatory property or the Field Metadata API and Layouts Metadata API.

📌 For Extension Users

Extension Consumers:

If you are using a Zoho CRM extension, be aware that these API changes may affect your extension once they are rolled out. We recommend checking with your extension provider to understand whether any updates are required.

Extension Developers:

If your extension uses the affected APIs, please review these changes and update your implementation before they go live. We also recommend notifying your customers about the upcoming changes and ensuring your extension is compatible before the rollout.

These changes are expected to be rolled out by the end of October 2026. We will share the exact rollout date and supporting documentation closer to the release.


Thank you for reviewing these upcoming changes and preparing your integrations.