Kaizen #205 - Answering Your Questions | Managing Picklists and Enabling History Tracking via Zoho CRM APIs

Kaizen #205 - Answering Your Questions | Managing Picklists and Enabling History Tracking via Zoho CRM APIs

Hello everyone!

Welcome back to another post in our Kaizen series. 

In this post, we will look at how you can manage picklist fields in Zoho CRM using APIs. This topic was raised as feedback to Kaizen #200, so we are taking it up here with more details.



In this post, we will cover the following:
  • What is a picklist field in Zoho CRM?
    • Picklist vs Multi-select Picklist
  • Working with picklist fields via APIs
  • History tracking for picklists
    • What is history tracking for picklists in Zoho CRM?
    • Use case
    • Enabling history tracking for a picklist using the Create Custom Fields API

What is a picklist field in Zoho CRM?

A Picklist field is a drop-down field in Zoho CRM that contains a predefined list of values. While creating or updating a record, you can select one value from this list instead of entering it manually. This helps you avoid typing errors.

Example :
A Region field with values East, West, North, and South.
If a lead is from the East, the user simply selects East from the picklist instead of typing it manually. 

Picklist vs Multi-select Picklist
                                                         
                                                            Picklist

                                                   Multi-select Picklist

  Users can select only one value from the list. 

   Users can select multiple values at once. 

  A standard Region picklist works when a record belongs to only one region.

  Example : East

   A Multi-select Region picklist works when a record spans multiple regions.
   Example : East, North

Global picklist / Global set : User can create a picklist in common and associate the created picklist across the modules to maintain accuracy. Refer to Kaizen #161: Global Sets using Zoho CRM APIs for more details.

Working with picklist fields via APIs

Creating a picklist field using the Create Custom Field API

You can create a new Picklist field in a module by calling the Create Custom Field Metadata API. For example, you can create a picklist field named Region with the values: East, West, North, South.

Request URL : {{api-domain}}/crm/v8/settings/fields?module=Leads
Request Method : POST


Sample Input
When creating a picklist field, set its data type as picklist and provide the list of options, each with a mandatory display_value. You can also configure additional properties such as actual_value, lexical sorting, and color coding.


{
    "fields": [
        {
            "field_label": "Select Region",
            "data_type": "picklist", // Specify the data type as picklist
            "tooltip": {
                "name": "info_icon",
                "value": "Select your region here"
            },

    "profiles": [
                {
                    "id": "5725767000000026011",
                    "permission_type": "read_write" 
                }
 ],
            "pick_list_values": [
                {
                    "display_value": "East",  //The unique display value for the picklist, which will be displayed in the CRM UI. Use the display_value in API requests during create, update, and upsert operations.

                    "actual_value": "IN_East" //The unique reference value associated with the particular option.
                },
                {
                    "display_value": "West",
                    "actual_value": "IN_West"
                },
                {
                    "display_value": "North",
                    "actual_value": "IN_North"
                },
                {
                    "display_value": "South",
                    "actual_value": "IN_South"
                }
            ],
            "pick_list_values_sorted_lexically": true,   //Sorts options alphabetically. Default value is false.
            "enable_colour_code": true    //Allows color coding for picklist options. Default value is false.
        }
    ]
}


Note : To create a multi-select picklist field, set the data_type key to multiselectpicklist in the request body ("data_type": "multiselectpicklist").

Sample Response
{
    "fields": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "5725767000007613005"
            },
            "message": "field created",
            "status": "success"
        }
    ]
}

Updating a picklist field using the Update Custom Field API

The PATCH - Field Metadata API lets you modify an existing Picklist field. Use the Get Fields Metadata API to get your picklist field ID. 

You can:
Here is a sample request that updates the Select Region dropdown field in the Leads module.

Request URL : {{api-domain}}/crm/v8/settings/fields/5725767000007613005?module=Leads
Request Method : PATCH

Adding a new option to the existing picklist field 

Sample Input 

{
    "fields": [
        {
            "pick_list_values": [
                {
                    "display_value": "Central", //adding a new option to the existing picklist field
                    "actual_value": "IN_Central"
                }
            ],
        }
    ]
}

Updating picklist 

{
    "fields": [
        {
            "profiles": [
                {
                    "id": "5725767000000026011",
                    "permission_type": "read_only" //updating the permission_type
                }
            ],
            "pick_list_values": [
                {
                    "display_value": "South Region", //updating the display field's value
                    "id": "5725767000007613010" //unique ID of the option 
                }
            ],
            "enable_colour_code": false //disabling color code for the options
        }
    ]
}

Note : Use the actual_value or unique ID of a picklist option to update its display value. Use the Get Fields Metadata API or Get Layouts Metadata API to get the details.

Removing existing options using Update Custom Layout API

To remove picklist values, keep only the required options in your input. Any options not included in the request will automatically move to the unused section.
First, fetch the required layout, section, field, and option IDs using the Get Layouts Metadata API. Then, in your request body, specify only the picklist values you want to retain.

Request URL : {{api-domain}}/crm/v8/settings/layouts/5725767000000091055?module=Leads
Request Method : PATCH

Sample Input 
{
    "layouts": [
        {
            "id": "5725767000000091055", //layout id
            "sections": [
                {
                    "id": "5725767000000209001", //section id
                    "fields": [
                        {
                            "id": "5725767000007613005", //field id
                            "pick_list_values": [
                                {
                                    "display_value": "Central",
                                    "id": "5725767000007626001"
                                },
                                {
                                    "display_value": "East",
                                    "id": "5725767000007613004"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}


Here, Central and East regions remain as active picklist options, and West, North, and South regions are moved to the unused section.

Updated response
Use the Get Fields Metadata API to check the updated response. The Central and East are still active options (type: used), and North, South, and West are inactive options (type: unused)
{
    "fields": [
        .
        .
        .
        {
            "field_label": "Select Region",
            "id": "5725767000007613005",
            "api_name": "Select_Region",
            "pick_list_values": [
                {
                    "display_value": "-None-",
                    "sequence_number": 1,
                    "reference_value": "-None-",
                    "colour_code": null,
                    "actual_value": "-None-",
                    "id": "5725767000007613013",
                    "type": "used"   //default option
                },
                {
                    "display_value": "Central",
                    "sequence_number": 6,
                    "reference_value": "Central",
                    "colour_code": null,
                    "actual_value": "IN_Central",
                    "id": "5725767000007626001",
                    "type": "used"
                },
                {
                    "display_value": "East",
                    "sequence_number": 2,
                    "reference_value": "East",
                    "colour_code": null,
                    "actual_value": "IN_East",
                    "id": "5725767000007613004",
                    "type": "used"
                },
                {
                    "display_value": "North",
                    "sequence_number": 4,
                    "reference_value": "North",
                    "colour_code": null,
                    "actual_value": "IN_North",
                    "id": "5725767000007613008",
                    "type": "unused"
                },
                {
                    "display_value": "South",
                    "sequence_number": 5,
                    "reference_value": "South",
                    "colour_code": null,
                    "actual_value": "IN_South",
                    "id": "5725767000007613010",
                    "type": "unused"
                },
                {
                    "display_value": "West",
                    "sequence_number": 3,
                    "reference_value": "West",
                    "colour_code": null,
                    "actual_value": "IN_West",
                    "id": "5725767000007613006",
                    "type": "unused"
                }
            ],
            "data_type": "picklist"
        }
    ]
}



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": [
        {
            "Company": "Zylker",
            "Last_Name": "David",
            "Select_Region": "Central"   // Picklist value to assign
        }
    ]
}

Note: 
  • When creating, updating, or upserting records, 
    • You can either pass an existing picklist value or add a new one, through the API. Please note that the new value will only be stored in that record, and will not be added to the picklist field’s metadata.
    • In the UI, you can only select from the available dropdown options.
    • Always use the display_value of the picklist option, not the picklist option’s ID.
    • You can also assign the default option (-None-). In this case, the picklist field’s value will be stored as null ("Select_Region": null)
Sample Response

{
    "data": [
        {
            "code": "SUCCESS",
            "details": {
                "Modified_Time": "2025-08-23T04:51:39-07:00",
                "Modified_By": {
                    "name": "Patricia Boyle",
                    "id": "5725767000000411001"
                },
                "Created_Time": "2025-08-23T04:51:39-07:00",
                "id": "5725767000007623017",
                "Created_By": {
                    "name": "Patricia Boyle",
                    "id": "5725767000000411001"
                }
            },
            "message": "record added",
            "status": "success"
        }
    ]

}



Updating picklist values in existing records using the Update Records API

When updating, you also use the picklist display value in the field.

Request URL : {api-domain}/crm/v8/Leads/5725767000007628002
Request Method : PUT

Sample Input 

{
    "data": [
        {
            "Select_Region": "West" // New picklist value
        }
    ]
}

This will replace the existing picklist value with West.


History tracking for picklists

What is history tracking for picklists in Zoho CRM?

You can enable history tracking for a picklist field using the Create Custom Field API. Once enabled, Zoho CRM automatically creates a related list for the tracked picklist and a separate module.
Every time the picklist value changes, Zoho CRM creates a new entry in this related list. Each entry shows the old value, the new value, who made the change, and when it was made, and how long the record stayed in the previous value before moving to the next one.

Use case

Zylker's sales team tracks lead progress through the statuses such as New, Contacted, Qualified, and Converted. The team wants to know how long a lead remains in each status and identify if follow-ups are delayed or leads are not progressing. 
You can achieve this by enabling history tracking on the Status picklist. You can also monitor every status change, who made it, and how long the lead stayed in the previous status. This helps the team monitor, identify delays, and improve the follow-up process.

The log stores:
  • New Value - updated region in the Moved_To__s key.
  • Changed By - user who made the update  in the Modified_By key.
  • Changed On - date and time when the region was changed  in the Last_Activity_Time key.
  • Duration  - how long the record stayed in the previous value before the change  in the Duration_Time and Duration_Days keys.

Enabling history tracking for a picklist using the Create Custom Fields API

Request URL : {{api-domain}}/crm/v8/settings/fields?module=Leads
Request Method : POST

Sample Input
{
    "fields": [
        {
            "field_label": "Status",
            "data_type": "picklist",
            "pick_list_values": [
                {
                    "display_value": "New",
                    "actual_value": "New"
                },
                {
                    "display_value": "Contacted",
                    "actual_value": "Contacted"
                },
                {
                    "display_value": "Qualified",
                    "actual_value": "Qualified"
                },
                {
                    "display_value": "Converted",
                    "actual_value": "Converted"
                }
            ], 
            "history_tracking_enabled": true, //(mandatory) Enables history tracking for the picklist
            "history_tracking": {
                "related_list_name": "Status History", //Lets you give a custom name to the history related list that CRM creates.
                "duration_configuration": "time", //Decides how to track the timing of changes: days - History is tracked by days and time - History is tracked by time. 
 
              Note : Before specifying the time value, enable the duration customization feature in your organization by contacting support@zohocrm.com.

                "followed_fields": [  // The followed_fields lets you retrieve additional field values whenever the picklist value changes.
                    {
                        "api_name": "Owner"
                    }
                ]
            }
        }
    ]
}

Sample Response in UI 


Sample Response via API
Whenever a picklist option changes, the system creates a new record in the related list module. In this example, Status History is the related list module. The sample response below shows how a particular change looks when retrieved using the Get Records API.

Request URL : {{api-domain}}/crm/v8/Status_History/5725767000007739323
Request Method : GET

Sample Response

{
    "data": [
        {
            "Status": "Contacted",
            "$approval": {
                "delegate": false,
                "takeover": false,
                "approve": false,
                "reject": false,
                "resubmit": false
            },
            "Modified_Time": "2025-08-28T06:35:15-07:00",
            "$currency_symbol": "$",
            "$field_states": null,
            "$review_process": null,
            "$editable": true,
            "Duration_Time": "6568847", //The system stores the duration in milliseconds.
            "$sharing_permission": "full_access",
            "Lead_Owner": {
                "name": "Patricia Boyle",
                "id": "5725767000000411001"
            },
            "Moved_To__s": "Qualified",
            "$orchestration": false,
            "Last_Activity_Time": "2025-08-28T08:24:44-07:00",
            "Full_Name": {
                "name": "Zylker",
                "id": "5725767000007735001"
            },
            "Modified_By": {
                "name": "Patricia Boyle",
                "id": "5725767000000411001",
                "email": "patricia@zoho.com"
            },
            "$review": null,
            "$process_flow": false,
            "$in_merge": false,
            "id": "5725767000007739350",
            "$approval_state": "approved",
            "$pathfinder": false,
            "$zia_visions": null
        }
    ]
}



Note :
  • You can select up to 10 fields in total, with a maximum of 5 user fields for all modules except Deals.
  • Encrypted fields cannot be specified.
  • In the Deals module,
    • History tracking is enabled by default for the Stage picklist field.
    • You cannot enable history tracking for any other picklist field in the Deals module.
    • You can only update the existing Stage picklist field using the Update Custom Field API.
    • You can add up to 6 followed fields, with a maximum of 5 user fields.



We hope this post helps you confidently manage picklists and track their history in Zoho CRM. 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!
Cheers!






Related Links :



    • Sticky Posts

    • Kaizen #197: Frequently Asked Questions on GraphQL APIs

      🎊 Nearing 200th Kaizen Post – We want to hear from you! 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 #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.

    • Celebrating 200 posts of Kaizen! Share your ideas for the milestone post

      Hello Developers, We launched the Kaizen series in 2019 to share helpful content to support your Zoho CRM development journey. Staying true to its spirit—Kaizen Series: Continuous Improvement for Developer Experience—we've shared everything from FAQs

    • Kaizen #193: Creating different fields in Zoho CRM through API

      🎊 Nearing 200th Kaizen Post – We want to hear from you! 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.

    • Client Script | Update - Introducing Commands in Client Script!

      Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! Commands

    • Recent Topics

    • Create, collaborate, and manage agreements with Zoho Sign

      Agreements drive business. We launched Zoho Sign in 2017 as a simple digital signature tool to sign agreements from anywhere, at any time. Over the years, we've learned that most agreements go through last-minute changes before they're signed. Our users

    • Function #25: Automatically generate purchase orders from a sales order

      We kicked off the "Function Fridays" series with the goal of helping you automate your everyday accounting tasks. As we delve into today's post, I'm delighted to announce that we're here to present the 25th custom function in this series. While it is

    • DNS set up

      I want to create an email with my company domain. When I tried to add new record with cloudflare it didn't work. The DNS record can't be manually added. I followed the instruction but still can't add it. Could you help?

    • hiding a topic from all but one segment (or list)

      My organization sends out a number of newsletters using Zoho Campaigns. One of those newsletters is for volunteers. In order to become a volunteer, a person has to first go through our volunteer orientation (training). After that, they can receive newsletters

    • How do I set up this automation correctly?

      When contacts enter my Subscribers list, I want it to reference a custom field to see if it is empty. Then I want it to do two things: If empty: Assign a tag based on a different custom field. If that custom field is empty, assign a different tag. If

    • Function #62: Display associated Quote on Invoice details screen

      Hello everyone! Today, we are sharing a Related List script that makes it easy to view and access the quote from which an invoice was created right from the invoice details screen. This Related List displays the Quote number and Amount, allowing you to

    • Custom confirmation message

      How can I change the message that users see after they submit the booking form? I have to confirm some details before their appointment is officially "confirmed", so I want to change it where it doesn't say their appointment is "confirmed" but rather

    • email forwarding not working

      Your email forwarding service does not work. I received the confirmation email and completed the confirmation, after that nothing and nothing since no matter what I have tried. Shame as everything else was smooth. I spose it's harder to run one of these web based internet mail services than you guys thought!!! can you fix the email forwarding asap PLEASE!

    • Desk x CRM Integration

      Howdy! We currently use SalesIQ but we are considering moving across to Desk as it seems to have more functionality that we want. One of the pulls is the ability for our customers to self serve. But, I might be getting over excited and not actually need

    • Function #53: Transaction Level Profitability for Invoices

      Hello everyone, and welcome back to our series! We have previously provided custom functions for calculating the profitability of a quote and a sales order. There may be instances where the invoice may differ from its corresponding quote or sales order.

    • Issue with Save & Share Link – Works for Others but Not Creator

      I’ve enabled the "Save and Share" feature in Zoho Forms, and it works correctly for all users accessing the public link—except for me (the form creator). Issue Details: When I save and share the link, recipients see a “no permission” error. The form is

    • Save the pdf report from a registration form in a Folder

      Through Zoho Forms I created a registration form with quite a lot of rules to handle different variables (TEAM types, payment in installments, etc.), and the result is pretty good. The automatic PDF that is sent to the respondent upon submission is already

    • zoho forms integration to zoho work drive

      Scenario: A user fills out a Zoho Form, entering details such as email, mobile number, and other required information, and uploads supporting documents like PAN, Aadhaar, etc. Upon submission, the data is available in Zoho Forms Reports. Requirement:

    • Zoho Forms to Zoho CRM Integration failed - can I restart it?

      The integration of Zoho Form to Zoho CRM has failed. Is there a way for me to restart it for the impacted entry?

    • insert an equation, but in document, it shows an image not available.

      I'm new to Zoho writer and used Zoho writer in desktop app version . When I inserted an equation, I got an image not available sign. Any help is appreciated. Thanks, Charles

    • Zoho Desk Android app update - Swipe action customization

      Hello everyone! We have brought in support for the swipe action customization in latest version(v2.9.13) of the Zoho Desk Android app update, enabling you to configure left and right swipe gestures on tickets to carry out the actions swiftly without opening

    • Import KB template OR Export template for zoho desk?

      Greetings. Can you tell me if there is a way to get an EXPORT of my KB articles? OR is there a template you supply for importing KB articles into my zoho desk? I am looking for a method of understanding what fields can be imported, and what their possible

    • XML format to import knowledgebase into Zoho Desk

      Hi, We just started to use Zoho Desk and want to import our knowledgebase from our old support system (Freshdesk) to Zoho Desk. Can anyone give us information about the format of xml file to import? There is no explanation on the related page.

    • Zoho Desk integration with Power BI

      Hi, I want to be able to create a Power BI report which has live updates of ticket data from zoho desk, is this possile at all? Thanks Jack

    • Arranging Ticket Templates

      Is there any way to arrange our ticket templates? It doesn't look very organised when it's just arranged according to when they were created. We want the list to look more organised, by arranging/grouping them by topics, or even just by alphabetical

    • What they mean with "Portal"?

      I just downloaded this app to take my personal notes on digital art studio because it seemed to me the most comfortable app to do it, I use it very often, what do they mean by “no activity on your portal”? I have about 1 year of work here and I don't

    • Inactive User Auto Response

      We use Zoho One, and we have a couple employees that are no longer with us, but people are still attempting to email them. I'd like an autoresponder to let them no the person is no longer here, and how they can reach us going forward. I saw a similar

    • favorites no longer listed

      Hello, I can no longer navigate to my Favorites from the pulldown at the top of my grid view (see attached screenshot). I wasn't able to find it anywhere! Please help me display my Favorites. Thank you!

    • Notecards Disappeared

      Got a new phone. Downloaded and signed in Zoho Notebook. Not finding the Note cards. Just Empty Note books. Frustrating.

    • Table Errors

      Hello, I'm new to Zoho Notebook and using it on several Mac/Apple devices. My question is regarding tables: Why do they become broken, and how to fix the error without retyping all my data? (Please see the screenshot attached.)

    • Online Calculator with Zoho Forms?

      I'd like to build a custom calculator on my website. Zoho Forms seems to offer all the fields for basic calculations performed live without pressing any "Calculate" buttons. Unfortunately, there is still that "Submit" button at the bottom. There is nothing

    • Zoho Tables instead of Zoho Creator Spreadsheet reports <3

      That would make my day for sure. Zoho Creator is create, but miss data entering as AirTable/Spreadsheet can. Seeing Zoho putting effort in this makes me think maybe one day we could see a similar interface for Zoho Creator spreadsheet reports. B.

    • Notebook Stack

      Hi Everyone I Hope you´re fine, I´m sorry if this idea was posted before (I made a search but I haven´t find anything related). So, Having the possibility of stacking notebooks would be an interesting way to order notebooks that correspond to the same

    • Writing on sketch cards is bugged when zoomed in

      When zoomed in, it writes a noticeable distance above or to the side of where you're actually trying to write. The further you're zoomed in, the more noticeable it is. Zooming is also entirely absent on the desktop version.

    • Swipe between notes on iPhone

      It'd be convenient if I could move from one note to the next in a notebook simply by swiping left to right.

    • Sales IQ chat is not working in signed android apk

      I have integrated ZOHO sales IQ support chat and i have followed each step and its working fine in my development build but when i create signed APK for it. Chat does not work in it and showing awaiting for detail. I previously asked the same query but

    • COQL order by COUNT not working

      Dear community, I am trying to get a list of deal amounts per planner working on it and sorted to get see who has the least amount of deals. For some reason, I am unable to use sort by in combination with a COUNT. My original code was: query = "select

    • I want to duplicate a report and name it something else

      Hi, I have created a report, and now want to reproduce it and call it something else. so that I will end up with TWO separate reports with different titles. Please tell me how do I copy / reproduce a report please

    • Zoho CRM: Sales Rep Professional Certification Program on Coursera

      We are happy to share that we have published the Zoho Sales Representative Professional Certificate in partnership with Coursera, a leading platform for online learning and career development that offers access to courses and degrees from leading universities

    • OS X Notebook quits immediately upon launch

      NoteBook for OS X (Sequoia, but also under Sonoma) always quits immediately upon launch (so I cannot use the "Attach user log" option). I've restarted my MacBook but the problem persists. If it helps, attached is a diagnostic report from Library>Log

    • Can External users upload files or images to WorkDrive?

      I want to know if it is possible for someone externally through a link and PW be able to upload files and images onto WorkDrive?

    • Multi-line fields character limits

      Is there a way to set the character limit higher on multi-line fields so that we are not losing information pasted into the field? When the text is entered or pasted, there is no error to say that the text is too large. After saving and going back to view most of the text is gone.   Also, when viewing the resume, the text is not wrapped in the multi line fields and can t be read without scrolling across the page.

    • Taz bot not working — What should I do to resolve this issue?

      I am experiencing issues with the Taz bot in Zoho Cliq—not receiving responses or it does not seem to work as expected. Could you please explain why the Taz bot might not be functioning and what steps I should take to resolve this issue? Thank you!

    • OneNote Migration

      I am trying to migrate two notebooks from OneNote. For five days now I have had no notification that migration has completed and the migration page show 50% complete - one notebook completed one not finished. It just stays like this. I am unable to cancel

    • Set various time slot reminders for task and event

      Hi I would like known if there is possibility to set various time reminders for a task or event like we have the possibility to do in google calendar or google task. For example I'am creating an event or task and I want to be alerted before 30min and

    • Next Page