Zoho CRM API Mandatory Field Change: What Breaks

24 Oct 2026

8 min

Implementation

Automation

Enterprise

Zoho is changing how Zoho CRM validates mandatory fields on API writes, and the change is expected to go live by the end of October 2026. Zoho announced the update early specifically so developers can test against it before it ships. If your integration creates or updates Leads, Deals, Contacts, or custom module records through the Zoho CRM API, this is worth a half day of testing now rather than an incident later.

What is actually changing in the Zoho CRM API

Zoho's developer community post describes a planned update to "mandatory field behavior" in the CRM APIs, tied to a broader overhaul of Map Dependency Fields. Zoho is explicit that the change is "not live yet" and is being shared in advance so partners can review the impact and prepare.

Map Dependency is the mechanism that controls parent-child relationships between picklist and radio-button fields. Set a parent value and the set of valid values on a dependent child field narrows automatically. Zoho's own API documentation is clear on the shape of this relationship: a parent field can control multiple children, but each child field can only have one parent, and the mapping is defined per layout, not globally across a module.

Today, most of that enforcement lives in the UI layer and in the Layouts configuration. The upgrade bundle Zoho is rolling out makes Map Dependency setup "simpler, faster, and more intuitive" inside the product, and the accompanying API-level mandatory field changes are what integration builders need to watch, because API writes that skip the UI entirely are exactly where dependency rules have historically been easiest to bypass.

Why this matters even if you have not touched Map Dependency

You do not need to have configured a single dependency rule yourself for this to hit your integration. If any admin on the Zoho CRM org you sync with has set up a parent-child picklist relationship (Country and State is the textbook example Zoho uses in its own docs), your integration's writes to that module are affected the moment stricter mandatory validation goes live.

This is the part that catches sync jobs off guard: a record payload that has always passed validation can start failing once the receiving org enables or tightens a Map Dependency rule, with no code change on your side. The CRM admin changed something in Setup, not in the API, and your integration found out from a 400 response.

What your integration should check before the end of October

Zoho CRM already enforces two layers of mandatory fields, and the October change adds pressure to the layer most integrations underestimate.

Layer 1: system-defined mandatory fields. These are fixed per module and documented directly in the Insert Records API reference. A few examples:

Leads: Last_Name
Contacts: Last_Name
Accounts: Account_Name
Deals: Deal_Name, Stage, and Pipeline (when pipelines are enabled)

These rarely change and are easy to hardcode into a mapping layer. They are not the risk here.

Layer 2: layout-defined mandatory fields. This is where it gets dynamic. Zoho's Layouts API documentation notes that a field's required flag is set at the layout level and that you can only mark a field as mandatory using the Layouts API, not the record-level Insert or Update APIs. Combine that with Map Dependency and you get a rule that is conditionally mandatory: Child_Field might not be required at all until a specific Parent_Field value is selected, at which point it becomes mandatory for that record.

Before the rollout, pull the current layout metadata and dependency map for every module you write to:

text

GET /crm/v8/settings/layouts?module=Deals
GET /crm/v8/settings/map_dependency?module=Deals&layout_id={layout_id}

The Get Mapped Dependency Fields API returns the parent field, the child field, and the mapping between parent values and the valid child values and their mandatory state for each. Run this against every org or layout your integration writes to, not just your own test org, because dependency rules are configured per customer.

What breaks when validation fails

When a write is missing a now-mandatory field, Zoho CRM's API returns an HTTP 400 with a specific error code rather than a generic failure. Zoho's own error reference documents MANDATORY_NOT_FOUND as the code returned when a required field is missing from the request, with the response body identifying the missing field by API name. A typical rejected record-create response looks like this:

json

{
  "code": "MANDATORY_NOT_FOUND",
  "details": {
    "api_name": "Deal_Sub_Type"
  },
  "message": "required field not found",
  "status": "error"
}

The practical failure mode for most teams is not a hard outage. It is a partial batch failure: a bulk upsert job sends 500 records, 480 succeed, and 20 fail silently into a dead-letter queue or an error log nobody checks daily, because the sync job's retry logic was built for rate-limit errors (HTTP 429) and connectivity failures, not for a 400 that says "this field is conditionally required now and it wasn't before."

If your sync writes to custom modules with several Map Dependency chains stacked on top of each other, the failure surface gets larger fast, because each conditionally-mandatory child field is a new way for a previously-valid payload to become invalid.

How to test against the change before it ships

Inventory every module your integration writes to, not just the ones you actively maintain. Lead-import scripts and one-off migration tools that nobody has touched in a year are the most common source of surprise failures, because nobody is watching their error logs.
Pull current Map Dependency maps with the Get Mapped Dependency Fields API for each layout in scope, and diff them against what your field-mapping code assumes is optional.
Add explicit handling for MANDATORY_NOT_FOUND in your error handling, separate from your rate-limit and auth-failure paths, so a validation rejection surfaces as an alert rather than a silent drop.
Re-run your full test suite against a sandbox org once Zoho's community post updates with a firm release date, since Zoho has stated the October 2026 date is a target, not a locked ship date.
Check whether your integration sets child-field values without first checking the parent value on the same payload. Writing Parent and Child in the same API call, where Child's valid values depend on Parent, is the pattern most likely to fail once validation tightens.

If your Zoho CRM data eventually flows into a signature or agreement workflow, for example a Deal reaching a specific Stage triggers a Docusign Workflow Builder send, a silently failed CRM write means the downstream workflow never fires at all. We have covered the integration side of that pipeline directly in Zoho's native e-signatures versus Docusign IAM for CRM workflows, and it is worth re-reading alongside this change if your Zoho-to-Docusign automation depends on specific field values populating correctly.

Frequently asked questions

When does the Zoho CRM mandatory field change go live?

Zoho's developer community states the change is expected to roll out by the end of October 2026 and confirms it was not live as of the announcement. Treat late October as a target date to test against, not a guaranteed ship date, since Zoho has not published a locked release day.

Does this affect integrations that do not use Map Dependency Fields?

If no parent-child picklist or radio dependency is configured on the modules you write to, the change should not add new mandatory-field failures for your integration. The risk applies to any org where an admin has configured a Map Dependency rule, whether or not your integration's own developers configured it.

What error does Zoho CRM return for a missing mandatory field?

Zoho CRM returns an HTTP 400 response with the error code MANDATORY_NOT_FOUND, and the response body's details.api_name field names the specific field that was missing, per Zoho's own API error reference.

Can I mark a field as mandatory through the record API?

No. Zoho's Layouts API documentation states that a field's mandatory flag can only be set through the Layouts API, which controls it at the layout level. The Insert and Update Records APIs enforce whatever the current layout says is mandatory; they do not let you toggle that requirement per call.

Where can I check what Map Dependency rules are already configured?

Use the Get Mapped Dependency Fields API against each module and layout your integration writes to. It returns the parent field, the dependent child fields, and the valid child values per parent selection, which is the information you need to confirm your write payloads will still validate after the change.

The next step

A field-validation change that only shows up as a partial batch failure is exactly the kind of break that custom Zoho CRM integrations absorb quietly for weeks before anyone notices records are missing downstream. If you are running Zoho CRM data into Docusign Workflow Builder, NetSuite, or another system and want someone to pressure-test your field mappings and error handling against this change before October, talk to the fluidlabs team about your integration. We have built and maintained Zoho CRM to Docusign integrations in production, and this is exactly the class of upstream API change we build defensive error handling for.