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.



      Zoho Campaigns Resources


        • Desk Community Learning Series


        • Digest


        • Functions


        • Meetups


        • Kbase


        • Resources


        • Glossary


        • Desk Marketplace


        • MVP Corner


        • Word of the Day


        • Ask the Experts


          • 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 #261 : Using Zoho CRM Skill to generate complex COQL queries

            Hello everyone, In the previous Kaizen posts, we introduced the zoho-crm SKILL.md and discussed how it can help you when you are working with Zoho CRM APIs and Client Script. In this Kaizen, we will focus on using the Zoho CRM `SKILL.md` with GitHub Copilot
          • 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

          Zoho CRM Plus Resources

            Zoho Books Resources


              Zoho Subscriptions Resources

                Zoho Projects Resources


                  Zoho Sprints Resources


                    Zoho Orchestly Resources


                      Zoho Creator Resources


                        Zoho WorkDrive Resources



                          Zoho CRM Resources

                          • CRM Community Learning Series

                            CRM Community Learning Series


                          • Tips

                            Tips

                          • Functions

                            Functions

                          • Meetups

                            Meetups

                          • Kbase

                            Kbase

                          • Resources

                            Resources

                          • Digest

                            Digest

                          • CRM Marketplace

                            CRM Marketplace

                          • MVP Corner

                            MVP Corner




                            Zoho Writer Writer

                            Get Started. Write Away!

                            Writer is a powerful online word processor, designed for collaborative work.

                              Zoho CRM コンテンツ


                                ご検討中の方

                                  • Recent Topics

                                  • [Webinar] Zoho CommunitySpaces MCP

                                    New to MCP, or just exploring what's possible? Join us for a webinar on Zoho MCP and your community. We'll show you how Zoho CommunitySpaces and Zoho MCP work together, what your AI co-host can do inside your community, and how to get started. Register
                                  • Solution to Import OST File into Office 365.

                                    In today’s digital workplace, organizations are rapidly moving toward cloud-based email systems for better flexibility, security, and collaboration. Microsoft 365 has become one of the most widely used platforms for business communication. A common requirement
                                  • How can I show an uploaded image larger/full size in a Zoho Forms response PDF?

                                    Hi,  I noticed that in a response PDF for Forms, the uploaded image is shown in a tiny box as seen in my screenshot. Is there any way I can make that appear larger in the response PDF? thanks.
                                  • Live connection to DS files in Zoho Creator / ChatGPT

                                    As an idea, we are using ChatGPT to build with Zoho Creator (outside of Zia), which is works brilliantly to assist write deluge, provide test suggesitons etc. Currently we are uploading the DS files which are very point in time, it would be great to have
                                  • Meet PageHealth by Zoho PageSense: a free way to find out what's holding your page back

                                    We all know the feeling. You've spent days tweaking headlines, moving buttons, and rewriting copy, and you're still not sure why visitors aren't sticking around. Revamping your website is hard, and figuring out what's actually getting in the way is even
                                  • Export Exchange Online Archive Mailboxes to PST for Microsft 365 Users

                                    With Microsoft 365 it is possible to archive older emails in Exchange Online in order to keep the main mailbox tidy. If however you need to export the archived emails to a PST file for the purposes of backup, migration, compliance or for use offline,
                                  • Task Module quick create settings

                                    Hello, requesting the Task module receive a quick create customization settings. We have added custom fields and have to select "More fields" at the bottom of the pop-up to access the custom fields.
                                  • Your employees changed departments. Did your IT systems notice?

                                    An employee joins your Marketing team. HR adds their details to the organization's user directory. The IT admin, in turn, creates their Zoho One account, assigns the required applications, adds them to groups and provides access based on the organization's
                                  • AI Calling

                                    Hi, does anyone have experience or any thoughts on AI Calling. Getting AI to make calls on behalf of your company. We are looking into it, but are finding it difficult to get info and providers that can assist.
                                  • Email Forwarding to Zoho Desk Failing After Migration from Gmail to Outlook (Microsoft)

                                    We recently migrated from Gmail to Microsoft Outlook. Since the migration date, emails sent by our customers are no longer being received by Zoho Desk. I tried setting up the email forwarding rules in Outlook similar to what we had in Gmail, but it still
                                  • Option to Disable Knowledge Base Section in Feedback Widget Popup Hello Zoho Desk Team

                                    Hello Zoho Desk Team, How are you? We are actively using Zoho Desk and would like to make more use of the Feedback Widget. One of the ways we implement it is through the popup option. At the moment, the popup always displays the Knowledge Base section,
                                  • How to Fix an Outlook OST File That Cannot Be Opened

                                    Have you at any time attempted to open Outlook only to find that your OST file cannot be accessed? It can be very annoying, particularly since the file holds important emails, attachments, and other mailbox data. This problem might arise due to file corruption,
                                  • Record positive and negative bank transactions in the same expense account

                                    Hello, I hosted a promotional event and paid a vendor $600 for food catering (bento boxes). Twenty people attended the event, and each person paid $30 for a bento box, resulting in 20 separate $30 transactions deposited into the bank. I coded the $600
                                  • Is it possible to log text messages from iphone into Zoho CRM

                                    My team is more and more utilizing text messaging to communicate with clients. Does Zoho have a solution for logging these text messages when clicking "Send Text Message" from the Zoho app. Much like when you call, you get prompted to log a call, can
                                  • CRM Address Field - States with Countries in brackets

                                    Hi, Could you please remove the country in brackets from the Global State List, or at least allow us to edit these entries? It looks like the brackets were added during the initial data population, perhaps by someone building the list in a spreadsheet
                                  • 👍 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
                                  • How to mass find and delete duplicate files from OneDrive

                                    It is easy to save documents, photos, videos, and all other types of files using Onedrive, but if you upload the same files more than once then your OneDrive storage can end up being filled with a large number of duplicate files. Manually searching out
                                  • Different Report sharing filters within same Dashboard

                                    I have a question about sharing filters for a dashboard which contains separate reports built from the same query. Below are the pieces of the puzzle: - “Sales Query”: line-level query containing sales for a team of 5 sales reps; there’s no need for the
                                  • Specifying time increments on a Date/Time field

                                    Hi all, Im using a Date/Time field in my CRM module. At the moment the increments are 30 minutes. How can I change these to be 15 minutes? Thanks
                                  • Make Your Workflows Smarter with Zia Agents

                                    Hello, Enterprise Support Community, Workflow rules can now go beyond predefined actions. Zia Agents can now be invoked directly from workflow rules in Zoho CRM, allowing you to bring contextual, AI powered actions into your automated processes. Choose
                                  • How can I add a Custom Field (or Customer_name) to a picklist?

                                    Our workflow is Shopify-->SO -->Picklist-->Package-->Shipment. We would like to have the Picklist template to include a custom field "Customer_Notes" (we have created this field already). This way we get alerted when a customer has notes on their account.
                                  • DYK 14: Create Tasks with AI

                                    Did you know AI can suggest tasks within your Zoho Projects portal? Breaking a project into clear, actionable work items takes time and manual effort. Especially when the same team handles both planning and execution. AI task suggestions in Zoho Projects
                                  • #11 Nithya's First Overseas Client

                                    Nithya designs for clients in three countries and has never met any of them. Her first overseas invoice took a full evening. The second took four minutes. The difference was not a clever tax trick. She stopped treating every international customer as
                                  • Other languages in Schedulers (Zoho Books)

                                    Hello everyone, currently we have create functions in other languages, like nodejs etc but on schedulers we can use only deluge.. Are other languages on schedulers roll out? Kind regards, Sakis Oikonomou
                                  • New in Office Integrator: Extract data from images into your spreadsheet

                                    Hi users, We are pleased to introduce the Data from Picture feature in Zoho Office Integrator's spreadsheet editor. It intelligently detects and organizes text and numbers from any image into structured cells using OCR. With this feature, users can turn
                                  • Edit PDFs using Zoho PDF Editor

                                    Hello users, In a previous article, we covered the organizing capabilities of Zoho PDF Editor. Here, we'll provide a quick recap of its editing features, including a few new additions. A few highlights of Zoho PDF Editor's editing capabilities: Add and
                                  • Partner with HDFC And Sbi Bank.

                                    Hdfc and sbi both are very popular bank if zoho books become partner with this banks then many of the zoho books users will benefit premium features of partnered banks.
                                  • Multiple subscription plan line items in Zoho Billing quotes

                                    I run an IT company and sell a lot of licences. A client might have multiple subscription plans including software licences in different categories. A client might have Microsoft licences, antivirus licences, web hosting and maintenance package services.
                                  • Mail Merge templates in Sandbox

                                    Rolled out for all DCs Hello everyone, You can now create and test Mail Merge templates directly in Sandbox, making it easier to validate document generation without affecting your live organization. Why this matters Mail Merge templates are often used
                                  • Dashboard Table of “My New Work Orders” Changes View

                                    Hi FSM Team, We noticed an inconsistency with the Dashboard Table of “My New Work Orders.” Initially, the table is configured to use the “My New Work Orders” view. When we go to the Home page, the table displays a different set of records. When we return
                                  • Tips & Tricks #6 | Zoho Vault: Audita actividad, Gestiona accesos, Comparte credenciales & mucho más.

                                    ¿Sabías que Zoho Vault puede hacer mucho más por la seguridad de tu equipo? Las contraseñas forman parte del día a día de cualquier persona y organización. Aplicaciones, herramientas internas, cuentas de clientes, servicios externos, plataformas de marketing,
                                  • Inquiry Regarding Customer Hierarchy & Sub-Customer Creation via Zoho API

                                    Dear Zoho Support Team, Our mutual client has requested support for implementing the Customer Hierarchy (Parent/Sub-Customer structure) within our existing workflow. At the moment, all invoices are being created in Zoho under the main (parent) customer
                                  • Which Zoho CRM tasks would you want an AI assistant to handle?

                                    I’ve started delegating my Zoho CRM work to AI – and many tasks now take me half the time. It has been so useful that we’re now working to make it available to everyone. Instead of clicking through records and tabs, I simply describe what needs to be
                                  • Introducing MCP for Zoho CommunitySpaces

                                    Hello everyone, Your AI assistant can now share the community workload with you. Zoho CommunitySpaces supports MCP (Model Context Protocol), so you can link an AI assistant like Claude, ChatGPT, or Cursor to your community and run it through plain language
                                  • CV-Library: The Newest Source Booster in Zoho Recruit!

                                    We’ve expanded your sourcing toolkit — CV-Library, one of the UK’s largest and most trusted online job boards, is now available as a Source Booster in Zoho Recruit. This gives recruiters instant access to millions of UK-based candidate profiles, all without
                                  • Tip 52#: Ways to improve data flexibility using related list

                                    A related list offers an ideal solution to string related data across entities together. It enables you to pull records from any module or external source and float them as a tab within your project, sprint, epic, work item, or release detail view layout.
                                  • Email Blast

                                    Hi, How do we send an email blast to thousands of customers? The email addresses are not yet saved in Zoho Desk.
                                  • Zoho ERP | Product updates | September 2026

                                    Hello users, A new month, a fresh set of updates in Zoho ERP. This month brings Netting, enhancements across our verticals, and more updates to help streamline your everyday work. Explore this month’s updates and see what’s new. Introducing Netting If
                                  • Introducing Zoho POS for Restaurants

                                    Hello Community, We’re thrilled to announce the launch of Zoho POS for Restaurants, unveiled at the 30th milestone edition of Zoholics India 2026. Running a restaurant involves multiple teams and workflows. A single table journey, from seating a guest
                                  • WhatsApp Business Message Pricing Update: Effective October 1, 2026

                                    Hi everyone, Starting October 1, 2026, Meta is updating how WhatsApp Business messages are charged. This guide explains the new per-message pricing model, how message categories work, and what changes for service messages specifically. How Meta charges
                                  • Next Page