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.

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.

• Topic Participants

• Subramanian K

  

• Arijit Das

• Salmanul Farzy

• 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

• Recent Topics

• Cannot apply tags to multiple items at once

  It is very frustrating needing to apply tags to notes individually. Even worse that it takes multiple clicks to do it. Can there please be an update to: 1.) Allow us to apply tags to batches of notes in one go. 2.) Make it less clicks to add a tag 3.)

• Get all hiring updates via Zoho Cliq bot notifications

  We’re introducing a new way to stay updated on recruitment activities: Cliq Bot notifications. Now you can receive Zoho Recruit notifications directly in Zoho Cliq—alongside your existing in-app alerts and emails. Whether it’s a candidate status change,

• Notes Acknowledgement

  It would be great to have emojis that can be used for Notes. Emojis such as Thumbs Up to let someone know you agree with them or a emoji for thanks. It's a simple way to acknowledge that you read someone's note. Moderation update: Emoji reactions for

• 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

• Project Finances: Fully Accessible within Projects

  Project finances and work items are now on the same screen and it transforms the way you run your project. Managing your project finances is now much easier and in the same screen as your work items. Access quotes, invoices, bills, sales orders, and purchase

• UI / UX Improvements

  Please consider changing the Dependency Details window from a column-based layout to a list-based layout, or allowing users to choose their preferred layout. The current column-based view uses screen space inefficiently and makes navigation difficult,

• Zoho CRM and Desk sandboxes for testing native integration

  Hello team, We are evaluating the native integration between Zoho CRM and Zoho Desk, We have sandbox instances of both products and want to test the integration there, without any effect on our production CRM or production Desk data. While setting up

• Function #24: Automatically display deal name from Zoho CRM on quotes in Zoho Books

  Deals allow businesses to organize and visualize their sales pipeline. This provides a clear overview of all potential opportunities and helps in making informed decisions. Zoho CRM empowers you to create deals or potentials for your clients and monitor

• Zoho Books | Product updates | August 2026

  Hello users, July has been an exciting month for Zoho Books! This month, we're excited to introduce HTML PDF Templates, Placeholders as Pills, expanded approval workflows for Sales Returns and Journals, and significant compliance updates across the India,

• Auto-Sync Field of Lookup Values When Parent Record Changes

  Hi Zoho Team, Currently, when you use a "Field of Lookup" in Zoho CRM, the value is captured as a snapshot at the time the lookup is set. If the parent record is later updated, the Field of Lookup value on the child record does NOT update and stays stale.

• [Request] Pivot filter date option : from set date to relative value ie from 01Jan to LastMonth

  I don't think I can currently do this... but it's worth asking if it's possible. My use case is concerning annual leave which is calculated from the beginning of the calendar year (01Jan) then each month I want to have details of leave taken etc... In

• Customer Statement Showing Incorrect Negative Balance Due to Unused Advance

  Dear Zoho Support Team, We are facing an issue with the Customer Statement in Zoho Invoice related to customer advances/mobilization advances. The issue is that when a customer has made an advance payment that has not yet been fully utilized against invoices,

• Mois de la sensibilisation à la cybersécurité 2026 : faites de la sécurité un réflexe avec Zoho

  Imaginez : vos systèmes informatiques répondent aux normes de sécurité en vigueur et votre entreprise est assurée contre les cyberattaques. Pourtant, un matin, tout bascule. Vos données sont chiffrées et un message glaçant s’affiche à l’écran : « Si vous

• 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

• What's new in Zoho Workplace | August 2026

  Hello Zoho Workplace community! Here's a roundup of all the new features and announcements that went live across Zoho Workplace applications in August. Zoho Mail Zoho Mail is now available in AWS Marketplace! AWS Marketplace users can access and subscribe

• What's new in Zoho Social - Q3 recap

  Hello everyone, We've rolled out a bunch of exciting updates in Q3, and we're thrilled to walk you through them. Here's a quick look at everything we released in July, August, and September to help you experiment with content, automate engagement workflows,

• Zoho Books | Product updates | October 2026

  Hello users, October brings a range of new features and enhancements to Zoho Books, designed to simplify compliance, streamline accounting workflows, and improve inventory management. From the launch of the Nigeria Edition and France’s e-invoicing capabilities

• The Social Wall: September 2026

  Hello everyone! This month, we’re bringing Snapchat to Zoho Social. You can now connect your Snapchat account and manage your content alongside your other social channels. Whether you want to reach a wider audience through Spotlights or share quick updates

• Turning off the recorded welcome in Zoho Webinar

  Is there a way to turn off the recorded voice that comes up at the beginning of every webinar session? It devalues the experience for attendees from feedback, interrupting their connection with our brand and delaying webinar start unnecessarily.

• 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,

• Outgoing Mail Blocked – Suspicious Login Activity (Need Clarification and Solution)

  Hello, I’m currently facing an issue where my Zoho Mail account has been blocked due to “suspicious login activity,” and outgoing emails are restricted. Here are the details shown: Block type: Outgoing mail blocked Reason: Suspicious login activity A

• Account Blocked due to Suspicious Activity.

  Hello, Trying to get access to my account, I have found this message above in the subject of this message. I am unable to log back to my account (see err. mess. below.) and thus cannot get rif of this following the Zoho procedure : I followed the step

• Zoho Recruit mailserver get blocked by Microsoft!

  Hi, We have experienced this issue twice now, where Zoho Recruit outbound IP addresses are being blocked by Microsoft. We are confident that Microsoft is the blocking party, as all outbound emails to candidates with @hotmail.com, @live.com, and @outlook.com

• Owner's Draw

  Example: I have a charge account at ABC Company. During the month I charge one $50 item for my business. I also pick up a $20 item for personal use. At the end of the month, I receive a statement with a balance due of $70 and I want to PAY THE ENTIRE

• Months of WooCommerce–Zoho Inventory sync failures and repeated support requests – has anyone experienced this?

  Months of WooCommerce–Zoho Inventory sync failures and repeated support requests – has anyone experienced this? I run a small retail business using WooCommerce and Zoho One. For months, I have been trying to resolve recurring synchronisation failures

• Name autocomplete

  Hi, During searching emails the web tool does not always propose the auto-completion of the saved emails. As a result I either have to go to contacts and look up the exact email, or the exact full name including the middle name and any dots, which is

• View Cannot Use UPC as Criteria

  When creating a new custom view, the UPC field is not available as a criterion for the view. This seems strange, because both ISBN and EAN are available in the dropdown. Because of this, I feel like the situation is possibly an oversight rather than by

• What are the best practices for managing tax records and financial information for a small business?

  I’m interested in learning how other small business owners and accounting professionals organize their financial records and prepare for tax filing. With bookkeeping, expense tracking, income records, and tax documents all needing to stay accurate, having

• Automating CRM backup storage?

  Hi there, We've recently set up automatic backups for our Zoho CRM account. We were hoping that the backup functionality would not require any manual work on our end, but it seems that we are always required to download the backups ourselves, store them,

• not able to convert pdf to jpg and other forms and vice versa.

  i want to change my pdf to jpg, word, etc and some times jpg to pdf. i don't know how to do in this.

• How Can I Collect Payments for Credit Sales Directly from Zoho POS Billing App?

  We are currently testing Zoho POS for a retail business and have encountered an issue with collecting payments on outstanding invoices from customers who purchase on credit. When we process a Credit Sale, Zoho POS correctly creates an Unpaid Invoice.

• Indeed has retired Organic (Free) job posting support for Staffing Agency edition users

  Dear Zoho Recruit Users, Due to a policy change by Indeed, Organic Job Posting support for staffing agencies is no longer be available in all regions, except Japan. Keep in mind that Corporate HR edition accounts will not be impacted by this change in

• Changing an existing item to different accounts & inventory-tracked

  Hi everyone, I have an item in Zoho Books that was originally set up as a non-inventory item. Over time, I associated it with different sales and purchase accounts, and I now have many invoices, bills, and reports that use this item. My business process

• Create a single record from multiple images with ICR

  Hello all, Zia's Intelligent Character Recognition can now create a single record from multiple images based on the configured ICR rule. Users can upload up to three images at once, such as an ID, a passport, and a business card, and Zia will extract

• Online Payment Fees

  We don't take many online credit card payments so the merchant service provider (PayPal) charges us the 2.9% fee for processing the amount. I would like the ability for the fee to be automatically added to the total amount for "ease of payment". We'd

• Lookups and Custom Modules

  I created a Custom Module that I'm calling "Item Purchasing Group". This module will store information for groups of Items that must be purchased together (including minimum overall quantities and/or values, etc.). This will have a one-to-many relationship

• Why is it so hard to get a fiscal YTD P&L report in Zoho Books?

  Yes I know that it could be done in Zoho Analytics, but I would have expected this default report view to be easily accessible in the list of Books accounting reports. Just like any other basic accounting system, I'm looking for monthly columns of the

• Button or Links order

  Is there a way to re-order the buttons or links that are created? Moderation Update: With our recent enhancement to custom button creation from the layout editor, administrators can now reorder custom buttons directly from the layout editor, and this

• Grok Bot integrations ASAP

  Grok Bot integration is critical. Please hurry. Zoho Books, CRM, all of it needed right away.

• Bulk updating tags

  My organisation handles a number of restricted funds. We previously did this by having a chart of accounts where each restricted fund has its own income and expense accounts. However, our accountant changed this, moving all transactions into accounts

• Next Page