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

• Meet your customers on Arattai, from inside Zoho CRM

  Hello everyone, Your customers reach you on the apps they already use. Zoho CRM now supports one more: our very own Arattai! When someone messages your Arattai Business number, the conversation arrives in the Messages module in CRM, right beside your

• Running Balance

  Please add automatically Running balance in ledger view. Taking lot of time, every time to add manually

• MAKING ENTRY TIME MORE USER FRIENDLY AND FASTER O PREVENT TAB TIME

  I AM CURIOUS TO KNOW IF WE CAN MAKE IT MORE USER FRIENDLY WHILE MAKING BILLS , I MAJORLY USE OVER DESKTOP SO I AM SUGGESTING TO REMOVE TAB TIME WHILE ENTERING BILL OR MAKING INVOICE DIRECT JUMP TO ONLY REGULAR PARTS OF THE BILL . YOURS RAKESH 782866

• Unable to export reports despite enabled report export permissions

  Hi Zoho Community, We are unable to export reports in Zoho CRM. When attempting an export, we receive the following error: “Cannot Export Report — You do not have permission to export one or more modules used in this report. Please contact your administrator.”

• Add Payment Information (like Bank details)

  I am using the Free plan of Zoho Books. I need to add the bank details/ UPI details on the invoice. How can I do that. I have added the details in the Bank Section.

• account access nahi kar pa raha hoo

  hello sir/maddam, mera naam Indrasen Lodhi hai meri zoho mail id "indrasenlodhi@zohomail.in" hai. main iska authenticator app bhul gaya hu, mere pass bachup code bhi nahi hai. kripya meri madad kijiye.

• Keep Sensitive Customer Data Private with Field Masking in Zoho CRM

  Hello CRM community, Customer records in your CRM are often accessible across multiple teams, but not every team needs visibility into every field. A non-sales team, for instance, has no real need to see a contact's mobile number, and a support agent

• Generate a Zoho Sign link

  From time to time I get a response "I never received your you e-document for electronic signature" is there a way to generate a Zoho Sign link to share.

• E-invoicing setup not completed in Zoho Books

  My status on the EmaraTax portal appears as linked with Zoho. However, when I try to complete the setup on the E-invoicing tab in Zoho Books settings, I receive an error saying: "E-Invoicing could not be enabled as the FTA portal is currently unreachable.

• Notes - Reaction Buttons

  Using the native notes option within CRM is fine, it works and the RTF features are great, however, would it be possible - if there isnt already something in place, where we can add a reactions button, similar to teams/whatsapp to show that its been read

• Generate a link for Zoho Sign we can copy and use in a separate email

  Please consider adding functionality that would all a user to copy a reminder link so that we can include it in a personalized email instead of sending a Zoho reminder. Or, allow us to customize the reminder email. Use Case: We have clients we need to

• Need help with importing expenses

  I'm using the template downloaded from the application. When I try to import my expenses, I get the message: Duplicate entry in the Expense Date column. Ensure it contains unique values. None of the rows will import. There are duplicate dates, but they

• #12 Bringing In A Second Pair Of Hands

  Meera's studio became a two-person business in month five. Adding the second person took ten minutes. Working out why Meera herself was showing up as Staff took considerably longer. The Usual Way To Do This Covered in our published General FAQ, with the

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

• Header Line in Quote product rows

  I believe this is an essential feature that Zoho should provide us, when adding products we want the ability to add titles for our product, in quotes: The Solution/Category Title Product1 Product2..... and then it would show the sub-total of that title 

• How to Fix the Corrupted Outlook 2019 .pst file on Windows safely?

  There are multiple reasons to get corrupted PST files (due to a power failure, system crash, or forced shutdown) and several other reasons. If You are using this ScanePST.EXE Microsoft inbuilt recovery tool, it only supports the minor corruption issue

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

  Moderation update: Currently available in the following DC's CA, AU, CN, UAE, JP, SA - All Editions EU - Free, Standard and Professional Hello everyone, Notes help users capture important updates, collaborate with teammates, and maintain context for records.

• Add @Mention Notifications in Zoho Cliq for Zoho Project Mentions

  Hello Zoho Projects Team, We hope you are doing well. We would like to submit a feature request regarding "Projects Bot" Cliq bot notifications for @mentions inside Zoho Projects comments (Tasks and Issues). Current Behavior: At the moment, when someone

• Can't connect to POP and SMTP over VPN

  I use Thunderbird to access Zoho Mail via POP and SMTP. I have configured an app-specific password for Thunderbird to use. Everything is properly configured and works correctly — until I enable my VPN. I'm using a paid commercial VPN service (Mullvad).

• 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

• 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

• O SalesIQ aceita números do Whatsapp Business com coextistência?

  Tenho uma equipe com vários vendedores e cada um deles tem um celular corporativo usando o Whatsapp Business para se comunicar com os clientes. Estamos no plano Zoho One e esses mesmos vendedores também usam o SalesIQ para atender os leads que vem do

• Losing description after merging tickets

  Hello, We merge tickets when they are about the same topic from the same client. It happens sometimes. We recently noticed that after the merger only the description from the master ticket is left in a thread. And the slave-ticket description is erased.

• Any update on much requested feature, to delete attachments without deleting the e-mail body?

  People have been requesting the ability to delete e-mail attachments without deleting the e-mail for more than ten years now. The latest I see is marked "Working On It" and a year ago it was supposedly being added, see here: https://help.zoho.com/portal/en/community/topic/is-there-a-way-to-delete-mail-attachments-without-deleting-the-text

• Undo/redo when composing Mail

  Where is the undo/redo button when composing mail? I've new to Zoho, I've looked, I've searched and can't find it. What am I missing?

• Mail menu bar items missing in Inbox and folders

  Last night some shortcuts such as Move to Folder, Archive, Delete, Mark as spam, and others, disappeared from my Mail menu bar, along with items in the vertical three dots extension such as Mark as read, Flag as, Mark as unread, etc. What I now have instead

• ERROR CODE :554 - Your access to this mail system has been rejected due to poor reputation of a domain used in message transfer

  This message was created automatically by mail delivery software. A message that you sent could not be delivered to one or more of its recipients. This is a permanent error. *****, ERROR CODE :554 - Your access to this mail system has been rejected due

• Sent items with shared folders

  Hello, this is in some way in between a problem and an idea.  When sharing folders (which is actually not any close to a shared mailbox...) the person which the folder has been shared with can access that folder and can send emails when delegation is

• What's New in Zoho Inventory | July & August 2026

  Hello users, The July and August 2026 releases bring a range of new features and improvements across the product. From the Nigeria Edition and Super Admin enhancements to Sri Lanka IRD-compliant invoicing, Loyalty Program Management, and improvements

• E-mail com problema

  Não estou recebendo e-mail desde Janeiro. Algo desconfigurou e eu não consigo resolver. Podem ajudar? Aguardo. Wagner Della Aversana Whats 55 11 985119899

• 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

• SAML authentication in Zoho Mail: Simplify and secure your organization's login management

  Managing login credentials across multiple web applications can be challenging for organizations with a large number of users. Without a centralized authentication system, users are required to maintain separate passwords for each application, increasing

• How to prepare a balance sheet for a company that has no operations yet?

  .

• Can't create new account in zoho email

  Hello, i'm trying to create some free accounts to my customers... and since yesterday i can't create a new account, what is wrong? why i can't create free account? Thank You

• 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

• Introducing Incentives for Zoho CRM: Build, automate, and track sales commissions

  Dear Customers, We are here with an amazing news! We built a direct solution to help manage your commission provisioning activity in your business. From creating commission plans to issuing payouts, this application leverages your sales reps’ performance

• Bank Feeds - Again

  Bank feeds broken again for me. I don't see other recent posts on this, so maybe it's just us? Tried: refresh update cred/ deact./react. feeds chat support Nothing. On day 2 without zoho as a result, which is crippling for us. We've used zoho for a year

• 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

• SPF failure in android app

  I have no domain. I am not admin of anything. All I want to do is send an email from a zohomail.eu address, using the Zoho android app, with all settings as default. I do not use Office 365, or EOP, or Outlook, and I have no domain or domain registrar.

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

• Next Page