Map Dependency Fields in Zoho CRM using APIs

Map Dependency Fields in Zoho CRM using APIs




Hi Everyone!!

Welcome back to another week of Kaizen series!

Over the past few weeks, we have been addressing your questions and feedback shared through our Kaizen 200th feedback form. Thank you for your continued engagement and thoughtful queries. We truly enjoy helping users solve real challenges through these Kaizen series.

This week, we will explore the Map Dependency Fields in Zoho CRM, and how you can configure and manage them using Zoho CRM APIs.

Map dependency fields with a use case

In Zoho CRM, dependency fields are also called picklist dependencies. They create a relationship between two picklist fields. A controlling field is the parent field, and a dependent field is the child field. The option chosen in the parent field decides which options should be shown in the child field. Helps you to make easy data entry and maintain cleaner with only relevant options.

In many businesses, one field’s options depend on another. For example, if your support team tracks Issue Type and Sub-Issue, showing all sub-issues at once lets users select incorrect options. A user might accidentally choose Payment Failed under Login Issue. This results in incorrect data selection and makes confusion in records.

Dependency fields solve this problem by creating a parent-child relationship between two picklist fields.

Let us consider the Support Cases module, where two picklist fields are already created:
  1. Parent Field - Issue Type: The value chosen here determines which options appear in the dependent field.
  2. Child Field - Sub-Issue: The available options change dynamically based on the selected value in the parent field.
Below table shows the picklist fields along with their respective options.

                            Issue Type

                                   Sub-Issue 

Login Issue

Forgot Password, Account Locked, 2FA Not Working
Payment Issue

Credit Card Declined, Refund Not Received, Double Charge

Feature Request

New Integration, UI Enhancement, Report Customization

By mapping these fields, CRM users see only the Sub-Issue values relevant to the selected Issue Type.

Without map dependency

Without configuring a map dependency, the Sub-Issue picklist would always display all available options - regardless of the selected Issue Type. For example, users might see options like Forgot Password, Double Charge, and Report Customization all at once. This can easily confuse users and lead to incorrect selections, such as choosing Double Charge under Login Issue.

With map dependency

With mapping dependencies, you can guide users to make correct selections by showing only the relevant options in the child field based on the option selected in the parent field.

Mapping picklist options in UI

You can map picklist field options directly from the Zoho CRM user interface.
Follow these steps:
  1. Go to Setup → Customization → Modules and Fields.
  2. Select the desired module. In this case, Support Cases.
  3. Click the ⋯ (more) icon next to the module name.
  4. Select Map Dependency Fields.
  5. On the Map Dependency Fields page, click the New button to create a new dependency.
  6. Choose the Parent Field and Child Field you want to map.
  7. Click Next button.


      8. Add option mappings to define which child field options should be shown based on the option selected in the parent field, then Save your configuration.

UI options mapping view

Mapping picklist options via API

Before mapping the options, you must need the following APIs :
  1. Modules Metadata API - To know the API name of the module.
    1. Endpoint: GET - /settings/modules
    2. Here, the API name of the Support Cases module is Support_Cases.
  2. Layouts Metadata API - Since dependencies are layout-specific, this API helps you identify the layout ID and all the available picklist fields for mapping. It also provides detailed metadata such as the layout ID, field IDs, and the corresponding picklist value IDs.
    1. Endpoint: GET /settings/layouts?module=Support_Cases

Create Dependency using the POST Map Dependency

Request URL:  {{api-domain}}/crm/v8/settings/layouts/5725767000007972011/map_dependency?module=Support_Cases

Request Method: POST

Input JSON
Each object in the map_dependency array requires a parent field, a child field, and a pick_list_values array that maps each parent option to its relevant child options.


{

    "map_dependency": [ //Array that contains one or more dependency mappings

        {

            "parent": { // Mandatory - Represents the parent picklist

                "api_name": "Issue_Type", //Mandatory - API name of the parent field

                "id": "5725767000007985243" // Mandatory - Unique ID of the parent picklist

            },

            "pick_list_values": [  //Mandatory - List of parent picklist values and their corresponding child mappings

                {

                    "display_value": "-None-",

                    "maps": [

                        {

                            "display_value": "-None-",

                            "actual_value": "-None-",

                            "id": "5725767000007985204"

                        }

                    ],

                    "actual_value": "-None-",

                    "id": "5725767000007985249"

                },

                {

                    "display_value": "Login Issue",

                    "maps": [

                        {

                            "display_value": "Forgot Password", //Label shown in the UI for the parent value

                            "actual_value": "Forgot Password", //Actual stored value of the parent picklist option

                            "id": "5725767000007985185" //Mandatory - Unique ID of the parent picklist option

                        },

                        {

                            "display_value": "Account Locked",

                            "actual_value": "Account Locked",

                            "id": "5725767000007985187"

                        }

                        

                    ],

                    "actual_value": "Login Issue", //Actual value of the parent field's option

                    "id": "5725767000007985242" //Mandatory - Unique ID of the parent field's option

                },

                {

                    "display_value": "Payment Issue",

                    "maps": [

                        {

                            "display_value": "Credit Card Declined",

                            "actual_value": "Credit Card Declined",

                            "id": "5725767000007985191"

                        },

                        {

                            "display_value": "Refund Not Received",

                            "actual_value": "Refund Not Received",

                            "id": "5725767000007985193"

                        },

                        {

                            "display_value": "Double Charge",

                            "actual_value": "Double Charge",

                            "id": "5725767000007985195"

                        }

                    ],

                    "actual_value": "Payment Issue",

                    "id": "5725767000007985244"

                },

                {

                    "display_value": "Feature Request",

                    "maps": [

                        {

                            "display_value": "New Integration",

                            "actual_value": "New Integration",

                            "id": "5725767000007985197"

                        },

                        {

                            "display_value": "UI Enhancement",

                            "actual_value": "UI Enhancement",

                            "id": "5725767000007985199"

                        },

                        {

                            "display_value": "Report Customization",

                            "actual_value": "Report Customization",

                            "id": "5725767000007985201"

                        }

                    ],

                    "actual_value": "Feature Request",

                    "id": "5725767000007985246"

                }

            ],

            "child": { //Mandatory - Represents the child field

                "api_name": "Sub_Issue", //Mandatory - API name of the child field

                "id": "5725767000007985186" //Mandatory - Child picklist field ID

            }

        }

    ]

} 


Sample Response 

{
    "map_dependency": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "5725767000008174001"
            },
            "message": "map dependency created",
            "status": "success"
        }
    ]
}


Retrieve the configured field mappings using the GET Mapped Dependency Fields API

Request URL:  {{api-domain}}/crm/v8/settings/layouts/5725767000007972011/map_dependency/5725767000008174001?module=Support_Cases

Request Method: GET
Sample Response

{
    "map_dependency": [
        {
            "parent": {
                "api_name": "Issue_Type",
                "id": "5725767000007985243"
            },
            "internal": false,
            "active": true,
            "id": "5725767000008180001",
            "source": 1,
            "category": 0,
            "pick_list_values": [
                {
                    "display_value": "-None-",
                    "maps": [
                        {
                            "display_value": "-None-",
                            "actual_value": "-None-",
                            "id": "5725767000007985204"
                        }
                    ],
                    "actual_value": "-None-",
                    "id": "5725767000007985249"
                },
                {
                    "display_value": "Login Issue",
                    "maps": [
                        {
                            "display_value": "Forgot Password",
                            "actual_value": "Forgot Password",
                            "id": "5725767000007985185"
                        },
                        {
                            "display_value": "Account Locked",
                            "actual_value": "Account Locked",
                            "id": "5725767000007985187"
                        },
                        {
                            "display_value": "2FA Not Working",
                            "actual_value": "2FA Not Working",
                            "id": "5725767000007985189"
                        }
                    ],
                    "actual_value": "Login Issue",
                    "id": "5725767000007985242"
                },
              .
              .
              .
            ],
            "child": {
                "api_name": "Sub_Issue",
                "id": "5725767000007985186"
            }
        }
    ]
}
You will get a JSON structure containing all dependency mappings. Check if your parent and child fields appear as configured.

Update the existing mapped options using the PUT Mapped Dependency Fields API

Request URL:  {{api-domain}}/crm/v8/settings/layouts/5725767000007972011/map_dependency/5725767000008174001?module=Support_Cases

Request Method: PUT

Input JSON

{

    "map_dependency": [

        {

            "parent": {

                "api_name": "Issue_Type",

                "id": "5725767000007985243"

            },

            "pick_list_values": [

                {

                    "display_value": "-None-",

                    "maps": [

                {

                    "display_value": "Login Issue",

                    "maps": [

                        {

                            "display_value": "Forgot Password",

                            "actual_value": "Forgot Password",

                            "id": "5725767000007985185"

                        },

                        {

                            "display_value": "Account Locked",

                            "actual_value": "Account Locked",

                            "id": "5725767000007985187"

                        },

                        { // mapped a new option to the existing mapping

                            "display_value": "2FA Not Working",

                            "actual_value": "2FA Not Working",

                            "id": "5725767000007985189"

                        }

                    ],

                    "actual_value": "Login Issue",

                    "id": "5725767000007985242"

                }

            ],

            "child": {

                "api_name": "Sub_Issue",

                "id": "5725767000007985186"

            }

        }

    ]

}





Delete existing dependency using the DELETE Mapped Dependency Fields API

Request URL:  {{api-domain}}/crm/v8/settings/layouts/5725767000007972011/map_dependency/5725767000008174001?module=Support_Cases

Request Method: DELETE

Sample Response


{
    "map_dependency": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "5725767000008174001"
            },
            "message": "map dependency deleted",
            "status": "success"
        }
    ]
}



Assigning picklist values using the Insert Records API

When you insert a record, you can directly pass the picklist option’s display value (not the ID) in the request body.

Request URL: {api-domain}/crm/v8/{module_api_name}
Request Method: POST

Sample Input 

{

    "data" : [

        {

            "Name" : "Support Case 1",

            "Support_Case" : "Login Issue",

            "Issue_Type" : "Login Issue",

            "Sub_Issue":"Forgot Password"

        }

    ]

}


Note: When creating or updating records via API, CRM does not validate the dependency relationship between parent and child picklist values.
To ensure data consistency and prevent data loss, always use the Get Map Dependency API before creating or updating records and to know correct mappings as well. This helps you retrieve the correct parent–child mappings and pass only valid picklist values in your API requests.

FAQs

Q1. Is the Map Dependency field supported in subforms?

Yes. You can configure dependency mappings for picklist fields within subforms as well. The Map Dependency Fields API supports creating parent–child picklist relationships directly inside a subform. To do this via API, use the subform’s API name as the module name when making the dependency mapping call.
This ensures that the dependency is created specifically for the picklist fields inside that subform, not the main module.

Q2. Can I keep the parent field in the main form and the child field in the subform?

Not currently. As of Zoho CRM API Version 8, cross-level mapping where the parent field is in the main form and the child field is in a subform, or vice versa is not supported neither via the UI nor through the API.

You can only:
  1. Map picklists within the main form, or
  2. Map picklists within the same subform.

Q3. What happens if I delete a picklist value that is part of a dependency?

If you delete a picklist option, the corresponding mapping will be automatically removed from the dependency.


Q4. What happens if I rename a picklist value that is part of a dependency?

If you rename a picklist option, the dependency will be automatically updated with the new option label.



We hope this post helps you learn more on mapping dependency fields in CRM using Zoho CRM APIs. Try it out, and let us know your experience in the comment section or reach out to us at support@zohocrm.com 

Stay tuned for more insights in our upcoming Kaizen posts!





      • Sticky Posts

      • 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

      • Kaizen #217 - Actions APIs : Tasks

        Welcome to another week of Kaizen! In last week's post we discussed Email Notifications APIs which act as the link between your Workflow automations and you. We have discussed how Zylker Cloud Services uses Email Notifications API in their custom dashboard.

      • Kaizen #216 - Actions APIs : Email Notifications

        Welcome to another week of Kaizen! For the last three weeks, we have been discussing Zylker's workflows. We successfully updated a dormant workflow, built a new one from the ground up and more. But our work is not finished—these automated processes are

      • Kaizen #152 - Client Script Support for the new Canvas Record Forms

        Hello everyone! Have you ever wanted to trigger actions on click of a canvas button, icon, or text mandatory forms in Create/Edit and Clone Pages? Have you ever wanted to control how elements behave on the new Canvas Record Forms? This can be achieved

      • Kaizen #142: How to Navigate to Another Page in Zoho CRM using Client Script

        Hello everyone! Welcome back to another exciting Kaizen post. In this post, let us see how you can you navigate to different Pages using Client Script. In this Kaizen post, Need to Navigate to different Pages Client Script ZDKs related to navigation A.

        • Recent Topics

        • iOS App doesn't refresh for Document Creation

          Hello Zoho team, I have created a workflow to be used on a mobile iOS device which starts in Zoho Creater and ends with a murge and store function that then opens the newly created document within the Zoho Writer app. This process is working great however

        • Zoho Books Sandbox environment

          Hello. Is there a free sandbox environment for the developers using Zoho Books API? I am working on the Zoho Books add-on and currently not ready to buy a premium service - maybe later when my add-on will start to bring money. Right now I just need a

        • Client Portal ZOHO ONE

          Dear Zoho one is fantastic option for companies but it seems to me that it is still an aggregation of aps let me explain I have zoho books with client portal so client access their invoice then I have zoho project with client portal so they can access their project but not their invoice without another URL another LOGIN Are you planning in creating a beautiful UI portal for client so we can control access to client in one location to multiple aps at least unify project and invoice aps that would

        • Email Insights included in Bigin emals are marked as SPAM everywhere

          Today I noticed that email recipients who use Office 365 never receive emails sent from Bigin. Further examination showed that all Email Insights links in email headers are marked as spam/phishing by Office 365. Example screen included. The problem is

        • Data Import | Zoho Analytics Custom Query Window Size

          Please increase the window size for the Custom Query Data Import. It's impossible to work with such a small query window.

        • Cliq iOS can't see shared screen

          Hello, I had this morning a video call with a colleague. She is using Cliq Desktop MacOS and wanted to share her screen with me. I'm on iPad. I noticed, while she shared her screen, I could only see her video, but not the shared screen... Does Cliq iOS is able to display shared screen, or is it somewhere else to be found ? Regards

        • Name changed in settings for mailbox but still not changed when typed in To field

          In the email account secretary@ i have updaetd the new staff members details but the old members name still appears when I type secretary@ in the To field. I cant work out where Zoho is finding the old name from. I have deleted the browser cache. If I

        • Cannot add my name to my domain name

          I want to have My name@mydomain.com and it says my name is linked to another account already. Please fix it since I do not have another account.

        • Invoice status on write-off is "Paid" - how do I change this to "Written off"

          HI guys, I want to write off a couple of outstanding invoices, but when I do this, the status of the invoices shows as "Paid". Clearly this is not the case and I need to be able to see that they are written off in the customer's history. Is there a way

        • Establishing new Zoho email account on laptop

          Good Morning: I am very long time Outlook business user and decided to try your email service last night and had established an account. I am trying to verify my account; how do I establish my Zoho email account on my laptop? I opened the account with

        • unable to send message reason 550 5.4.6 unusual sending activity

          My email account can't send message. It shows unable to send message reason 550 5.4.6 unusual sending activity detected

        • how to add email to existing organization i w

          I am already registered my organization and i have an email id. I need one more email id but i can't find anywhere .i want the cheapest email id . how to add ?

        • e-mail bloqueado

          Estou com meu e-mail lucas@peplus.me bloqueado, preciso desbloquear para retorno de usos em minhas atividades.

        • zoho labels api not working

          We're using n8n to automte email reply using zoho api. I'm facing issue with label api. I added the required scopes but its not working. i followed zoho api documentation but didn't work. also, where do i find/how do i create zoho oauth token mentioneeed

        • Whatsapp Connection Status still "Pending" after migration

          Hello, I migrated my WhatsApp API to Zoho from another provider a day ago. So far the connection status is still “Pending”. There is a problem? How long does it usually take?

        • Desk DMARC forwarding failure for some senders

          I am not receiving important emails into Desk, because of DMARC errors. Here's what's happening: 1. email is sent from customer e.g. john@doe.com, to my email address, e.g info@acme.com 2. email is delivered successfully to info@acme.com (a shared inbox

        • Streams/Shared email doesn't show up in windows trident app. It works fine on MAC. Is there any difference between 2 install ?

          I can see streams/share email boxs on my MAC version of trident app but i can't see them in windows version of trident app. Is there any difference between 2 install? I try to find setting but not able to see any setting to add stream/share email boxes.

        • add zoho account

          How to add a zoho mail to previous zoho account? I have two

        • Zoho Desk Mobile App Year-End Roundup - 2025

          Dear Zoho Desk users, Greetings! As you gear up for the festive season, we are excited to share a quick journey into all that is released in 2025! Zia's generative AI capabilities Zia insights can be highly beneficial in helping agents manage daily support

        • How create a draft via workflow?

          I wish to create a workflow rule for specific emails that creates a draft response - not an automatic email reply, but just a draft with a set response ready to be verified by an agent who can then manually select recipients. Alternatively, the workflow

        • Narrative 17: The role of Zia AI in customer support

          Behind the scenes of a successful ticketing system: BTS Series Narrative 17: The role of Zia AI in customer support Overview Zia in Zoho Desk is a layered AI assistant that combines generative AI, prediction, and automation to support agents, automate

        • Domain Transaction

          I have purchased a domain name called trainedworkforce.co.in I made the payment got the receipt but the domain is still not purchased after successful transaction .

        • Ability to Set a Unified Tab Order/View for All Users in Zoho Projects

          Hello Zoho Projects Team, We hope you are doing well. We would like to submit a feature request regarding tab/menu organization in Zoho Projects. Current Behavior: The tab (module) order in Zoho Projects is user-specific. Each user (internal or external)

        • Zohomail - The "All Messages" vs "In Box"

          Why do some new email message appear under the all messages view but not in my inbox? That's really annoying but to be fair I've experienced the same with gmail.

        • error while listing mails

          I can't access email in any of my folders: Oops, an error occurred - retry produces the second error response: error while listing mails (cannot parse null string). I've signed in and out of Zoho, restarted my iMac.

        • Zoho CRM for Gmail Extension Not Working in Brave Browser?

          Is anyone able to get the Zoho CRM Chrome Extension working in the Brave browser? They're both built on the Chromium platform and every other Chrome Extension works with the exception of Zoho CRM for Gmail so any ideas here?

        • Zoho CRM for Everyone's NextGen UI Gets an Upgrade

          Hello Everyone We've made improvements to Zoho CRM for Everyone's Nextgen UI. These changes are the result of valuable feedback from you where we’ve focused on improving usability, providing wider screen space, and making navigation smoother so everything

        • How to track a contact or customer's past product purchases in Bigin Premiere?

          Hello there. I am the sole user of Bigin for a small company (chess club), and would like to track current and past purchases made by a contact (player) or company (family which includes the player). Players may register for multiple tournaments, take

        • Introducing the Zoho Projects Learning Space

          Every product has its learning curve, and sometimes having a guided path makes the learning experience smoother. With that goal, we introduce a dedicated learning space for Zoho Projects, a platform where you can explore lessons, learn at your own pace,

        • Where to show Customization Field ?

          Dear Sir, I have made some New Field in Item Field Customisation. Now I don't require that field in Estimate, Sales Orders etc. I just wants that field in Sales Invoice to Show/Hide... Is that possible ?

        • Zoho Desk 2025 round-up: Key highlights on feature releases

          Hello everyone, As we gear up for 2026, here is a detailed round-up of all feature releases in Zoho Desk web throughout the year. For consolidated information on releases check out the What’s New page You can also watch these webinars. Zia in web Zia

        • Print Sales Orders, Purchase Orders or Invoices from API

          Hello, Is it possible to use the print option that is available in Sales Orders Purchase Orders and Invoices with the API?. I don't see any information in the docs about this. Thanks

        • New in Smart Prompt: Record Assistant for contextual assistance, and support for new AI models

          Smart Prompt helps teams stay informed and move faster by providing relevant suggestions where work happens in CRM. With this update, Smart Prompt becomes more adaptable to your organization’s AI preferences. You can now choose which Large Language Model

        • CRM gets location smart with the all new Map View: visualize records, locate records within any radius, and more

          Hello all, We've introduced a new way to work with location data in Zoho CRM: the Map View. Instead of scrolling through endless lists, your records now appear as pins on a map. Built on top of the all-new address field and powered by Mappls (MapMyIndia),

        • Zoho Books - How to Invoke a Custom Function in Schedulers

          We have multiple schedulers that send emails to customers in batches. Currently, we are maintaining the same code across several schedulers. Is it possible to use a custom function inside a scheduler script? If yes, how can we invoke the custom function

        • How to show a hided report??

          in CRM Report , I clicked Hide incidently , how to show the floder again? Nowhere I can find the hided report floder...

        • To print Multiple delivery notes in batches

          In Zoho Books, we can print a Delivery Note from an Invoice using the Print Delivery Note option, but it is non-editable and always prints all line items from the invoice. Our requirement is to deliver invoiced items in batches and print delivery notes

        • Converting Customer Invoice to Purchase Bill

          Hi, In my service-based business, I sometimes create the customer invoice first, and later I receive the purchase bill from the vendor for the same job. Is there any option in Zoho Books to: Convert a customer invoice into a purchase bill, or Link/associate

        • Email tracking inquiry

          I am trying to track when my emails are opened and clicked like I previously did in HubSpot. HubSpot pretty much did the entire process automatically. After digging through, I finally found in settings --> emails --> BCC Dropbox there is an email I can

        • Mass Update of Lookup Fields not possible

          Hello List I've created a custom field for Leads and Contacts 'Current Campaign'. This is very Handy as I can filter leads and then related them to a campaign. Everything ready, but then I realized that mass update doesn't work for lookup fields... a

        • Next Page