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 :



    Nederlandse Hulpbronnen


      • Recent Topics

      • Unify All Zoho Video Meeting Experiences into One Standardized Platform

        Hi Zoho Team, We would like to share an important user experience concern regarding the current state of video meeting functionality across the Zoho ecosystem. The Problem Within Zoho, there are multiple ways to initiate or schedule a video meeting: Zoho

      • Is it possible to embed Youtube shorts?

        Hi Zoho desk support, This is Ryan from Accuver America. While I'm trying to create a knowledge base article with embed video, I ran into this issue. "www.youtube.com refuse to connect" A little bit background is that because this video is recorded on

      • Split functionality - Admins need ability to do this

        Admins should be able to split an expense at any point of the process prior to approval. The split is very helpful for our account coding, but to have to go back to a user and ask them to split an invoice that they simply want paid is a bit of an in

      • Delegates - Access to approved reports

        We realized that delegates do not have access to reports after they are approved. Many users ask questions of their delegates about past expense reports and the delegates can't see this information. Please allow delegates see all expense report activity,

      • How to include total km for multiple trips in expense report.

        Whenever I create a mileage report it only shows the total dollar amount to be reimbursed. The mileage for each individual trip is included but I also need to see the total distance for all trips in a report? How do I do this?

      • Get logged in user ID in Deluge script

        Hello all, How do I get the id of the logged-in user in a deluge script? the "zoho.loginuserid" function actually returns the users email address or whatever the user id they use to login to zoho with and not the id of the user record, and given that

      • Item Details Field - New Barcode / Document option?

        Is this a new feature??? its in both books and inventory.

      • Shared Mailbox - Mark as read for all users

        Hi all, Maybe someone can help me out. At the moment we have a shared mailbox without streams. When a users reads an mail or marks it as read other users will not see this. How can we resolve this? We now archive the mails when read and followed up. However

      • How do I increase the email attachment size in Zoho CRM ?

        It looks like I'm limited to 10MB when sending an attachment using the email widget on a record in Zoho CRM. Is there a way to increase the size? Or can I use some other tool? From what I'm reading online, I'm maxed out at 10MB. Any insight would be greatly

      • Can I export to PDF in Zoho Learn

        I have seen help pages where export to pdf options are available but I do not see that option available from the application. I see that exprt is available in my free trial version but that is only to html pages. I need to be able to export my manuals

      • Zoho Sites "pages" management page

        I have 80 plus pages on zoho sites. When I go to the "pages" link to view and edit pages, They are not in any kind of order, so I spend lots of time searching for pages when I need to edit or create new. How can I change the view order of all my pages

      • Staff rules

        Hi! Do you people know what are the default staff rules when a new booking is created? We have two staff members in my team (me as the admin, and my employee). As we share the same services, I'm wondering how Zoho will pick the staff for new apointments.

      • Add Image Upload Field to Zoho Bookings Registration Form

        Hi, We would like to request the addition of an image upload field to the Zoho Bookings registration form. Currently, Zoho Bookings only supports text-based fields (e.g., Single Line, Multi-Line, Email, Checkbox, Dropdown, Radio Button, and Date), but

      • Merge Tags Output Incorrect Placeholder Text After CRM Sync

        Hi everyone, I’m experiencing an issue with merge tags in Zoho Campaigns after last sync of contacts and leads from Zoho CRM (days before everything worked perfectly). Here’s the situation (seems like a default configuration in Campaigns) : My leads have

      • UI Improvement - Ability to Collapse Flow

        The UI for Flow is generally pretty good. However, when multiple decision trees are used, the layout can get pretty convoluted and hard-to-follow (see one of my Flows below): In these cases, even the auto-arrange fails to make this something that a normal

      • Windows agent 2025_M02 release notes

        Agent Version: 111.0.3.300 Release date: 24 February, 2025 Various Major enhancements to improve overall performance and optimize the user experience. Squashed a few bugs to improve overall product quality.

      • Windows agent 2025_M01 release notes

        Agent Version: 111.0.3.299 Release date: 05 February, 2025 Major Enhancement: Live Monitor feature compatibility released. Major Enhancement: Updated Scaling for multi technician cases with Android and Web based viewers. Various other bug fixes and performance

      • how to record deferred revenue?

        Dear Zoho Team, We issue invoices relating to 12-month web hosting service. When we issue the invoice, we should record the entire amount of the invoice as DEFERRED REVENUE (ie. $10 x 12 mths = $120, balance sheet item). After the particular month of the hosting service, $10 of revenue has been earned and deferred revenue amount will be $110. We must keep adjusting the balance sheet and income statement over the course of the service until the company has fulfilled its obligation of services and

      • Narrative 13: Importing your data

        Behind the scenes of a successful ticketing system: BTS Series Narrative 13: Importing your data When importing data into an application, it is crucial to prevent data loss or duplication. These types of errors can hinder the development of a clean and

      • Blueprint Not Triggering When Lead Status Is Updated by Workflow (IndiaMART Integration)

        I have set up a blueprint that triggers when a lead’s status is “New Lead.” Our CRM is integrated with IndiaMART, and when leads are created from IndiaMART, their Lead Status is initially set to None. To handle this, I created a workflow that automatically

      • Update Subform in specific field(Status) without affecting other fields in Zoho CRM using Deluge?

        Scenario: PRODUCT Module(change name Plot) in any product status change From Available to Booked then on PROJECT Custom Module have Subform So, Subform name is Property Details now in that Subform 1 field is STATUS that update according to  product status

      • YouTube Live #2: Agreement Intelligence with Zoho Sign's eSign AI assistant

        Hi there, We're back again with our YouTube live series and this time, we'll take you through our holistic agreement intelligence powered signature workflows. Struggling to draft an agreement? Need help double-checking clauses and going through complicated

      • Can I Build a POS using ZOHO creator and integrate it with ZOHO Books?

        Hello,  I have a Zoho Books account and I was wondering if I can have a POS system that integrates with it. Primarily with Inventory, Customers and Payment and ofcourse Create invoices and credit notes.   So, would Zoho creator provide me with this solution?  Thank you, 

      • An important update for Zoho Cliq desktop users

        The latest version of the Zoho Cliq desktop app (v1.8.0) will no longer be supported on macOS 10.15 Catalina and earlier versions. This is because the framework we use (Electron) no longer supports some older macOS versions. If you’re using macOS 10.15

      • Zoho Projects - Visual improvement to parent and sub-task relationship

        Hi Projects Team, My feature request is to improve sub-task visibility. Please see screenshot below. I really think parent child relationships could be visually improved. Even if the first letter of the parent task was inline with other same level tasks

      • Items Below Reorder Point Report?

        Is there a way to run a report of Items that are below the Reorder Point? I don't see this as a specific report, nor can I figure out how to customize any of the other stock reports to give me this information. Please tell me I'm missing something s

      • New Toolbar in Zoho Sheet

        We have revamped our toolbar design in this new version of Zoho Sheet. Below are some screenshots to help you get accustomed to this new interface. Click on the picture below to view the animated image in its original size. Scroll down this post to learn about the changes. Highlight of Changes: The previous format tab is now split into 2 tabs - Home and Format. The Home tab contains the commonly used functions and the Format tab holds formatting related options. Under the Home tab towards the far

      • Zoho inbuilt Telephony made a lot of issues!

        Hi there, I am a user that I am working with zoho inbuilt telephony around 1 month. Non of my colleagues are happy with this app! most of the time customer cannot hear my customer service team, customers say our voice is breaking. whenever Telephony support

      • Sending workflow notifications using popular chat services

        Hello everyone, We have introduced instant and scheduled notifications on some of the most popular chat platforms to facilitate easy collaboration, quick action, and wider reach. Workflow notifications can be sent to the following chat platforms: Zoho

      • Webhook not firing.

        I created a webhook using the Web UI, it looks very nice and the testing worked without an issue, but when i save/ update a ticket, the webhook is not firing. Here are the details of the web-hook i get from using the API "modifiedTime": "2019-10-22T09:23:37.380Z",

      • Adding Images to a Quote in Zoho CRM

        We are currently preparing to use Quotes in Zoho CRM and we are building out our Quote templates.  We came across an issue of not being to add Images of the products to the Quote - specifically in the body of the Quote templates.   This is a problem,

      • Applications built with Zoho Creator

        Hi, I’m really interested in seeing how others have built their application using Zoho Creator, especially those designed for external users (clients, vendors, or the public). If you’ve developed something along those lines and don’t mind sharing, I’d

      • Is it posssible to add Asap Widget on Wordpress?

        I have tried to add the ASAP widget so users could iniciate chats and see the KB information but nothings seems to work. I have tried to add the script using a php snippet that adds the to the footers and also tried one for the header in the functio

      • Require ticket resolution

        Hi Zoho team, Is there a way to require resolution even if an agent did not use a blueprint? for example, our blueprint has a "resolve" transition but what if agent revoked blueprint and manually set the status of ticket to closed? Is there a way where

      • Tables from ZohoSheets remove images when updated from source

        I have a few tables from a ZohoSheet in a ZohoWriter document that will remove the images in the cells when I refresh from the source. The source still has the images in the table when I go to refresh. After updating from the source, as you can see the

      • API Pagination Error: 'from' Parameter Limit

        Hello, I am encountering an error while paging through the Zoho Desk API results: Status code: 422 - {"errorCode":"UNPROCESSABLE_ENTITY","message":"The value passed for field 'from' exceeds the range of '0-4999'."} Is 5000 the maximum number of records

      • How to go to the next open ticket in the queue when agents closes ticket

        Zoho Desk When agent closes a ticket - eg when they choose 'Send and Close" - where is the setting that automatically redirects them to the next open ticket in the queue?

      • External download link limit

        Can You please help us to understand this For Zoho WorkDrive external users, the download limit is a maximum of 5 GB total download size and a maximum of 50 first-level files and folders What is the meaning of first level? We are using these files in

      • CRM verify details pop-up

        Was there a UI change recently that involves the Verify Details pop-up when changing the Stage of a Deal to certain things? I can't for the life of me find a workflow or function, blueprint, validation rule, layout rule ect that would randomly make it

      • Custom templates for calendar report

        What about being able to design custom templates for the calendar report, as well as for other types of reports? I think more users are waiting for this.

      • Next Page