Managing Picklists and Enabling History Tracking via Zoho CRM APIs

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

      • filter broke my data

        I uploaded a file recently from Sheets and it has top 2 rows frozen, with table headers in second row and each one is filterable. somehow my first 2 columns became unfiltered and no matter what I do I cannot reapply the filter?? also didn't realize they

      • How do I move Notes around within a Group?

        It says here: " You can now sort notes by title (alphabetically), or by date modified and date created. You can even organize your notes by dragging and dropping them into a particular order. To sort your notes, simply go to Settings and tap “Sort By.” Please note: all sort settings will be saved and synced across devices, except for custom sorting. Custom sorting will be device specific."However, I am unable to 'custom sort' in either Notebook for Mac or on the Web. In addition, I can't find the

      • 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

      • Zoho Sign: need to leave document pending for up to a year, or maybe there's a better way?

        I have zoho one, maybe there's a better way to do this with another service than sending a zoho sign template from zoho crm. At the end of the day this requirement is due to regulations, no matter how dumb it may seem. I'm just looking for a way of getting

      • Separate Items & Services

        Hi, please separate items and services into different categories. Thank you

      • What's New in Zoho Inventory | Q2 2025

        Hello Customers, The second quarter have been exciting months for Zoho Inventory! We’ve introduced impactful new features and enhancements to help you manage inventory operations with even greater precision and control. While we have many more exciting

      • Mastering Zia Match Scores | Let's Talk Recruit

        Feeling overwhelmed by hundreds of resumes for every job? You’re not alone! Welcome back to Let’s Talk Recruit, where we break down Zoho Recruit’s features and hiring best practices into simple, actionable insights for recruiters. Imagine having an assistant

      • We are unable to process your request now. Please try again after sometime or contact support@zohoaccounts.com

        I cannot sign up and return the error of we are unable to process your request now. Please try again after sometime or contact support@zohoaccounts.com

      • Multi-currency - What's cooking ?

        Hi,       We have been doing this feature for sometime and we would like to give you some glimpses of it.  Working with Multi Currency :        Multicurrency support gives you the ability to handle business transactions in multiple currencies. You can define a base currency for your organization and add more currencies with exchange rates based on the base currency.  Setup :        From the setup page, you can manage all the currencies supported by your organization.       Currencies page        

      • Integrating Chatbot with Zoho Creator Application

        Is it possible to integrate a chatbot with a Zoho Creator application?

      • How to reduce programmatically the image uploaded by user?

        I need a function that will automatically reduce the pixel dimension to 800 x 600 pixels / 180 resolution or (approx. 1.37MB) of image uploaded by user from digital camera, for example, 2271 x 1704 pixels /180 resolution or approx. 11.1MB. After the user selected the image, the function will able to detect if pixels is above 800x600, process the photo (crop/ reduce) and resume upload. Need help...  

      • Dark mode for Zoho Creator / Zoho CRM Code editor

        Hi Team, Is there any plans for Dark mode in Zoho creator / Zoho Crm code editor and development pages in pipeline?

      • Is there a way to make a button scroll down?

        Looking to have a button on a landing page scroll down to another section on the page. Any recomendations outside of coding?

      • Collective-booking event not added to all staff calendars

        We assign two staff to certain events. When the client books this event, it adds it to one staff calendar (the 'organiser') but not the other. How can I ensure all staff assigned to a collective booking get the event in their calendar? (A side note: it

      • ZOHO Android Client

        Hi, I installed the Android app, but it had an issue, so I reinstalled it. I was able to add multiple accounts, but now when I add the next account, it just duplicates the one I already have and will not even allow me to enter the info for another account.

      • I'd like to suggest a feature enhancement for SalesIQ that would greatly improve the user experience across different channels.

        Hello Zoho Team, Current Limitation: When I enable the pre-chat form under Brands > Flow Controls to collect the visitor’s name and email, it gets applied globally across all channels, including WhatsApp, Messenger, and Instagram. This doesn't quite align

      • Enhance Barcode/QR Code scanner with bulk scanning or continuously scanning

        Dear Zoho Creator, As we all know, after each scan, the scanning frame closes. Imagine having 100 items; we would need to tap 100 times and wait roughly 1 second each time for the scanning frame to reopen on mobile web. It's not just about wasting time;

      • Non-depreciating fixed asset

        Hi! There are non-depreciable fixed assets (e.g. land). It would be very useful to be able to create a new type of fixed asset (within the fixed assets module) with a ‘No depreciation’ depreciation method. There is always the option of recording land

      • Managing Rental Sales in Zoho Inventory

        I am aware that Zoho Inventory is not yet set up to handle rental sales and invoicing. Is anyone using it for rentals anyway? I'd like to hear about how others have found work arounds to manage inventory of rental equipment, rental payments, etc. Th

      • Megamenu

        Finally! Megamenu's are now available in Zoho-Sites, after waiting for it and requesting it for years! BUT ... why am I asked to upgrade in order to use a megamenu? First: Zoho promised to always provide premium versions and options for all included Zoho-applications

      • Cannot access KB within Help Center

        Im working with my boss to customize our knowledge base, but for some reason I can see the KB tab, and see the KB categories, but I cannot access the articles within the KB. We have been troubleshooting for weeks, and we have all permissions set up, customers

      • Zoho Flow to Creator 3001 Respoonse

        I have updated my Flows with the new V2 connection to Zoho Creator, but now some Flows do not work. They take in data from a Webhook and are supposed to create a record in Creator, however creator returns a 3001 message along with a failure, but I cannot

      • File Upload to Work Drive While Adding Records in Zoho Creator Application

        Hi I am trying to set a file attachment field in zoho creator form, to enable the user to upload a scanned document from their local pc. The file should be uploaded to zoho workdrive and not to the default zoho creator storage. The file link should be

      • Why not possible to generate?

        Using this https://desk.zoho.com/DeskAPIDocument#TicketCount#TicketCount_Getticketcountbyfield on my ZML script url :"https://desk.zoho.com/api/v1/ticketsCountByFieldValues?departmentId=XXXXXXXXXXX&accountId!=XXXXXXXXX&customField1=cf_country_1:XXXXXX&field=overDue"

      • email

        Hi My crm email is not working, can you check, I have zoho one account.

      • Need option to see Mass Emails & Cadences in Gmail Outbox OR a dedicated Zoho Outbox

        Hi everyone, Right now, when we send 1:1 emails from gmail (with gmail API connected to Zoho CRM), those emails appear both in gmail's sent folder and in Zoho CRM. That works well. But when we send Mass Emails or Cadence emails form Zoho CRM, they are

      • I can't found API for Sales Receipts

        Hello May you please help me to find an API document for Sales Receipts to get data and retrive a custom fields like Invoice and credit notes Regards

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

      • Multiple Vendor SKUs

        One of the big concerns we have with ZOHO Inventory is lack of Vendor Skus like many other inventory software packages offer. Being able to have multiple vendor skus for the same product would be HUGE! It would populate the appropriate vendor Sku for

      • Internally created tickets

        Hi there When tickets are created internally on-behalf of customers - there is nothing to show that the ticket was created by an internal agent. This means, that it's easy for our agents to confuse tickets which were created by internal team members and

      • Automatically change website passwords

        Hi everyone, We just switched to a Professional package to also use the "Automatically change website passwords" function. But I cannot find anything about it, how to use it, anywhere. Does anyone know how I can use this function? Best, Caspar

      • Change Invoice Prices for an Effective Date

        Hi, It would be a really good feature to be able to change the prices on invoices/recurring invoices from an effective date in the event of price increases. For instance, I am in the process of increasing prices that will be effective from a specific

      • "Other Current Asset" accounts as "Paid Through" accounts in Expense

        It would be incredibly useful to be able to assign accounts of type Other Current Asset as Paid Through accounts in Expense. Currently, Other Current Liability are permitted as Paid Through Accounts. This makes sense, as Credit Cards are current liabilities.

      • Multi column open text questions that allows respondents to add rows for additional information

        I need to create a question that has 2 columns with open text, but I also need to allow respondents to click a "+" button, or something similar, so that they can add additional information if they choose to. I've tried using the Multiple Textboxes type

      • Bot Filtering & Apple Mail Privacy Protection Compliance in Zoho Campaigns

        Dear Campaigns Users, The wait is over! We’re excited to announce that the enhanced bot filtering feature is now live in Zoho Campaigns. This update brings greater accuracy to your email campaign reports by distinguishing real user engagement from automated

      • Découvrons les détails qui simplifient vos journées de travail avec Trident

        Nous nous installons dans des routines efficaces et rodées avec le temps. Chaque matin, nous ouvrons nos e-mails, passons aux messages, consultons notre agenda, puis attaquons nos tâches. Ce processus nous semble maîtrisé, mais est-il réellement optimisé

      • Issue with Purchase Rate Showing as “0” After Importing Items List

        Dear Zoho Books Support Team, Good day. I’m reaching out regarding an issue I’m facing while importing my items list into Zoho Books. Despite mapping all fields correctly and including the purchase price for each product in my Excel file, the Purchase

      • API for Task Entity in Zoho Books

        I’m working on automating task creation in Zoho Books via a custom button in the Bills Module. The goal is to create a task in the Tasks Module and assign it to the Finance Team, so they can track progress efficiently. While reviewing Zoho Books documentation,

      • create invoice in zoho books from the zoho forms

        Is there a native way to have create invoice in zoho books, when zoho form is completed?

      • Email undelivered

        GOod Day I am always receiving an uncategorized-bounce to my email. I am not sure why this is happening.

      • Next Page