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.

Notes
Note: These changes will also be reflected in the currently supported API versions (V2 to V8). 

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

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 (V2 to V8)

      Future response (V2 to 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.
Change 2: Last_Name field

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

                  Current response (V2 to V8)

      Future response (V2 to 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 (V2 to V8)

      Future response (V2 to 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 First_Name and Last_Name fields at the module level to ensure that the Full_Name field is not empty.

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.

Response behavior:

if First_Name is configured as mandatory and no value is provided for Last_Name, the Get Records API response in V2 to V8 will return: "Last_Name": ""

This approach is intended to preserve the existing response format and minimize breaking changes across the current API versions. If your integration assumes that Last_Name always contains a value, review and update your business logic to handle empty values appropriately.

Upcoming API version:

For API versions V2 to V8, the Last_Name field will return an empty string ("") when no value is available. Fom V9, the Last_Name field will return null instead of an empty string.

If V9 is released before this change is ready, this behavior will be introduced in V10 instead.

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.


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


    • Sticky Posts

    • Announcing the new SKILL.md for Zoho CRM and the updated OAS repository!

      We are introducing a new zoho-crm skill to make working with Zoho CRM Developer tools (like APIs, functions, widgets, client scripts, queries etc) easier and faster, with the help of AI in your preferred AI harness like Claude Code, Codex, Cursor, VSCode

    • Kaizen #256 - Build an Arrival Readiness Web Tab in Zoho CRM

      Hi everyone! Welcome back to the Kaizen series! In the post, we discuss a use case in hospitality industry: how an Arrival Readiness web tab widget can be used to let reception staff identify and resolve issues before arrival of guests. Use case In the

    • Kaizen #198: Using Client Script for Custom Validation in Blueprint

      Nearing 200th Kaizen Post – 1 More to the Big Two-Oh-Oh! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.

    • Kaizen #226: Using ZRC in Client Script

      Hello everyone! Welcome to another week of Kaizen. In today's post, lets see what is ZRC (Zoho Request Client) and how we can use ZRC methods in Client Script to get inputs from a Salesperson and update the Lead status with a single button click. In this

    • Kaizen #222 - Client Script Support for Notes Related List

      Hello everyone! Welcome to another week of Kaizen. The final Kaizen post of the year 2025 is here! With the new Client Script support for the Notes Related List, you can validate, enrich, and manage notes across modules. In this post, we’ll explore how

      • Recent Topics

      • Automate customer follow-ups with Sequences in Bigin

        Greetings, We hope you're all doing well! We're happy to announce a new feature that we've added to Bigin. Following up with every lead at the right time can be challenging, especially when your team is managing multiple conversations across emails, calls,

      • Dashboards for Customers

        Is it possible to build dashboards for each customers in the community for their tickets?

      • Displaying only unread tickets in ticket view

        Hello, I was wondering if someone might be able to help me with this one. We use filters to display our ticket list, typically using a saved filter which displays the tickets which are overdue or due today. What I'd really like is another filter that

      • Adding Custom Status Options in Work Order Action Menu

        Hello FSM Team, We would like to inquire if it is possible to add more custom options in the Work Order action/status dropdown (e.g., Cancel, Terminate, Non-Billable, Void, etc.). Currently, the available options are limited, and we are unable to customize

      • Can we have an automated TDS Receivable Recon with Form 26AS of Income Tax Portal ?

        Can we have an automated TDS Receivable Recon with Form 26AS of Income Tax Portal ?

      • Tag Limi?

        is there any way to create more than 20 tags? 

      • prefill_data for Creator + Merge & Sign

        Hello, Is there an option to use prefill_data for signer fields from creator? I see the option for CRM but it will not work with creator? I have tried passing the value in the signer data, and that also does not work. Alternatively, is there a way to

      • Delug script

        I have been looking at auto-update a amount (home currency) field from another module. Zoho native multicurrency was used in the other module (we have 4 here). Custom script was input with no error, but the field was not updated on trigger. Script as

      • Can I Build a Gaming Website Using Zoho? Need a Quick Roadmap

        Hi Dear Members, I want to create a gaming website using Zoho. Is it possible? My goal is to build a sleek, unique, easy-to-navigate, and fast-loading website for a gaming project. I want the site to look professional, user-friendly, and optimized for

      • Remove Due Date from Statements

        Is it possible to remove the Due Date on the Invoice transation line on statements? I have figured work arounds to get the Invoice detail on the Statement but cannot work out haw to simplify the stament by removing the "- due on xx/xx/2026" - it really

      • unable to join meeting due to speaker issue

        unable to join meeting due to speaker issue

      • How to add formatting in zoho.cliq.postToUser(...) message?

        In a CRM Deluge function, I'm trying to use the message formatting guidelines given here: https://www.zoho.com/deluge/help/cliq/posting-to-zoho-cliq.html#message-formats My message is: message: #Title text. The result in Cliq is: #Title text. (no large

      • Marketing Tip #50: Sell digital products and use them to grow your store

        Physical products need packaging, shipping, and stock management. Digital products need none of that. Once created, they can be sold an unlimited number of times, delivered instantly, and never go out of stock. What counts as a digital product? A digital

      • Checkbox not displaying correctly in subform

        Greetings: I have shared my app (wv) with support.  I am having problems with a checkbox field not displaying correctly in a subform.  The main form is called volunteers and the subform is called volunteers_subform.  The field in question is called roles. When you access the subform by itself the checkbox lookup displays as checkboxes.  But when you view it in the main volunteers form, it displays as a multi-select dropdown instead.   I have attached jpegs showing the difference.   Any thoughts?

      • Turn off Mobile Optimize

        Hello is it possible to stop the automatic mobile optimization of my site as it looks much better on a mobile in full site format rather than mobile format. Thanks

      • How to select from pricebook when creating a salesorder or quote

        I am creating a sales order and when selecting the Products I do not see any where to select from pricebooks. How do i associate this to my orders?

      • API - Available Stock Definitions

        Okay, Zoho team... your copywriters fell down on the job for this one :) I think these warrant a bit more explanation as to what they include and what they don't.

      • Cross-application Deluge calls fail when application link name starts with a number

        I encountered an issue when calling a custom function in another Zoho Creator application within the same account. The target application’s URL/application link name began with a number, similar to: 27_example_application The following cross-application

      • Transformez vos webinaires en opérations automatisées

        Organiser un webinaire, c’est bien plus que passer en direct. Il faut gérer les inscriptions, suivre les participants, envoyer les enregistrements, mettre à jour le CRM… et s’assurer que chaque étape se déroule au bon moment. L’automatisation des workflows

      • Marketing Tip #1: Optimize item titles for SEO

        Your item title is the first thing both Google and shoppers notice. Instead of a generic “Leather Bag,” go for something detailed like “Handcrafted Leather Laptop Bag – Durable & Stylish.” This helps your items rank better in search results and instantly

      • How can I filter inactive/disable agent tickets?

        Hello, We have an user-agent that left the company and we inactive/disabled his agent. So, now I can no longer filter or search tickets that he is the current owner, or even create a rule to reassign tickets to another person when the ticket is reopen.

      • How do i move multiple tickets to a different department?

        Hello, i have several tickets that have been assigned to the wrong department.  I am talking about hundreds of automatically generated ones that come from a separate system. How can i select them all at once to move them to another department in one go? I can select them in "unsassigned open tickets view" but i can't find a "move to another department" option. I also can't seem to assign multiple tickets to the same agent in that same view. Could somebody advice?

      • Add Reauthentication Option for Zoho Bug Tracker Integration in Zoho Desk

        Hello Zoho Desk Team, We hope you're doing well. We would like to request an enhancement to the Zoho Bug Tracker integration within Zoho Desk. Current Limitation: At the moment, there is no option to reauthenticate the Zoho Bug Tracker integration in

      • Create Package From A Picklist

        Dear Zoho, Can it be made possible to create a package from a picklist? The reason our company makes a picklist is for that to become a package Our sales orders have 600-1000 items I hope that makes it clear that it's hard to delete 990 items when we

      • Migrating from Zoho Checkout to Zoho Billing

        I have an active Zoho Checkout account where I'm charging customers for subscriptions. Now I'm looking to upgrade and only use Zoho BIlling, in which my account in on read only mode at the moment. I can see is also tracking the customers and its payments.

      • API - Bank Accounts | Reconciliation Discrepancy

        Unless I'm reading it wrong, the documentation for the Bank Reconciliations API is inconsistent with itself. https://www.zoho.com/books/api/v3/bank-accounts/#create-a-bank-reconciliation The text definition says that the transaction_id should be a string,

      • another little issue

        So to get over showing prices with VAT we used the price lists and made the prices inclusive. The problem is now on the items it wants to show the orginal retail value which makes no sense. Ideas please

      • Handle Leading Zeros in a Number Field

        Hi, If I use a Number Field, set with Min 7 Digits and Max 7 Digits, and enter 0000001, it will result in 1 and an error as it removes the leading zeros, the same with entering 0012340 will result in 12340 and error. So I have to use a Text Field and

      • can't access zoho account

        I can't log in to my zoho account, can you help me

      • HTML PDF Templates / Build From Scratch option not visible for Custom Modules

        Hi everyone, I am working with Zoho Books Custom Modules and trying to create a custom 4x4 package label PDF template using HTML/CSS. According to the official Zoho Books documentation for HTML PDF Templates, there should be an option like: Settings →

      • Virtual Option for Fields

        Hi, I would like to be able to choose another option other than Read-Only or Disabled, such as Virtual. And with Virtual, the field is shown on the form and avilable in rules, but NOT saved to the Database. A use case is having multiple Large Lists of

      • Prefix & Suffix on Single Line, Number, etc.

        Hi, I would like to have the same Prefix and Suffix that was added to the Unique ID on Text and Number Fields. Use case could be as basic as temperature, as per another Idea I have to use Single Line (Text) for a number that might have leading zeros today,

      • Customer User Fields for use in Rules

        Hi, I would like to be able to add custom fields to the users, such as Department or Role, which can then be used in Rules, Reports, etc. as a condition. A use case is limiting Global lists or Choices based on the users Custom Field, so one form can be

      • Locked out of MFA due to changing phones

        I have been locked out of my Zoho Books account since i changed my mobile phone over. I can get the OTP through the ZOHO Books software but i cant confirm using my phone app as nothing appears to authorise. I need to know how to register/set up my new

      • 👍 Zoho CRM's Notes now gets Reactions and a new look

        Available in SA and JP DCs. Rolling out to other DCs in phases. Hello everyone, Notes help users capture important updates, collaborate with teammates, and maintain context for records. Now with Note Reactions, users can quickly acknowledge updates, express

      • All new Address Field in Zoho CRM: maintain structured and accurate address inputs

        Availability Update: 29 September 2025: It's currently available for all new sign-ups and for existing Zoho CRM orgs which are in the Professional edition exclusively for IN DC users. 2 March 2026: Available to users in all DCs except US and EU DC. 24

      • Zoho books and venmo

        Hi, Is there a way to hook Venmo into zoho books? I have a Venmo business account and want to be able to sync that. I know you can do it with the paypal integration but I dont want to use paypal for the fees and that doesnt allow me use/integrate my current

      • Updating Unit Code for New Item Creation, Quote and Invoicing is so inconvenient

        The Zoho Team has implemented many updates, but these updates should be optional. Before rolling out any new feature, they should already have a solution in place that allows users to remove or disable it if they choose not to use it. Just yesterday,

      • Payroll needs to automatically remit taxes, not just give me the calculations

        Wagepoint, PayEvo, Waveapps, etc... All your competitors deposit employee payroll, but they ALSO remit taxes automatically. Get with the program, your Payroll app is extremely sparse.

      • Creating new Teams meeting from CRM doesn't enable Team functions in the meeting

        Hi I'm trying to set up the meeting integration and I've seen that when I create a Meeting in the CRM and set the location to Online and the Provider to Teams, and complete the boxes, add a participant etc, whilst the meeting is created in Teams, the

      • Next Page