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

      • Workflow workdrive rollout

        Hi! When will workflow be rolled out to all users? Thanks.

      • Help Center and SEO: Any Benefit to My Domain-Mapped Website Ranking?

        First of, I love the Help Center which I've just decided to integrate into my website to replace its old-fashioned FAQs. So much more to achieve there now! Lots of new benefits to the site visitors and to me in terms of organizing and delivering all the

      • Blueprint status change

        I want to change the Blueprint status of a workflow. The status is completed automatically when I added the record through API call. But I want to make it active, I don't see any options for this. Even if I draw transition from any stage , it is not visible

      • Support french language options

        Greetings, I want to use Zoho with the french language portal, however the supplied translation is not very good (google translate). There are many basic mistakes on the main most important sections (my requests, submit a request). Is there a way for

      • Automation #7 - Auto-update Email Content to a Ticket

        This is a monthly series where we pick some common use cases that have been either discussed or most asked about in our community and explain how they can be achieved using one of the automation capabilities in Zoho Desk. Email is one of the most commonly

      • 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

      • Introducing the Workflow and Actions APIs for Zoho CRM

        We are absolutely thrilled to announce the release of Workflow APIs and Actions APIs in Zoho CRM’s v8 API suite! This powerful new set of endpoints gives developers unprecedented programmatic control over business automation. For years, Workflow Rules

      • Zoho CRM Analytics - Allow To Reorder Dashboards

        I would like to suggest that you add the ability to reorder dashboards in the Analytics Module. I can see that this has been requested some time ago, the latest 9 years ago. I am not sure if this is a big or small endeavor, but such a small fix can go

      • Zoho Form URL displays incorrect name

        Hi, I have a form I created called "Design Request form". It displays this way everywhere I look. However, in the URL, it shows up as "DesignJobRequestFormFINAL011325PROOFV1B" and I'm not sure why. I can't find where to fix this. Does anyone have any

      • Consumers are talking about your business. Are you listening?👂

        A loyal customer might be praising your product in a forum. A frustrated user could be posting a harsh review on a public site. An excited partner may have left a comment on your campaign. A domain expert might be deconstructing your product. A prospect

      • What counts as a Temp for Billing Purposes in Workerly

        I'm considering trying this product but am not sure how the temp count is used for billing purposes. For example, if we keep a large data base of 500 potential workers.....are we billed for that or only if they are assigned to a client at a given point

      • Form name incorrectly displayed in URL

        Hi, I have a form I created called "Design Request form". It displays this way everywhere I look. However, in the URL, it shows up as "DesignJobRequestFormFINAL011325PROOFV1B" and I'm not sure why. I can't find where to fix this. Does anyone have any

      • I can't receive mail

        Hello, I can't receive e-mail. I no longer receive e-mails to the e-mail I received for ​my site. I also edited the DNS settings, but it doesn't work at all.

      • 1‑to‑1 invite missing post-setup (needs re-invite) vs channel invite auto-joins without business prompt

        1. Zoho Cliq 1‑to‑1 external invite The inviter sent a 1‑to‑1 invite to an invitee who didn’t have a Cliq account. After the invitee completed account setup and created a business/organization, the website redirected them to Cliq, where they opened Cliq

      • 【開催報告】東京 ユーザー交流会 Vol.3 2025/10/17 Zoho サービスの活用促進を外部ツールとの連携で実現！

        ユーザーの皆さま、こんにちは。コミュニティチームの藤澤です。 10月17日(金)に新橋で「東京 ユーザー交流会 Vol.3」を開催しました。ご参加くださったユーザーの皆さま、ありがとうございました！ この投稿では、当日のセッションの様子や使用した資料を紹介しています。残念ながら当日お越しいただけなかった方も、ぜひチェックしてみてください😊 ユーザー活用事例セッション：Zoho Flowと決済システムの連携 あみろくの岡島さんに、Zoho サービスの活用事例として、Zoho Flow を活用した外部サービスとの連携事例をご共有いただきました。

      • received email opens in a new tab every time I log in

        as per the title: since about when I first made my email account, every single time Ive logged in to view my inbox, a new tab opens for an email I viewed once as if restoring a closed session. I thought I just didnt understand the "starting up" settings

      • Engage with your customers at scale using WhatsApp Marketing Template messages

        Hi everyone, To make it easier for organizations to communicate with customers, Desk now allows you to send individual, mass, and bulk WhatsApp template messages from both the Ticket and Contact modules. How is this going to benefit your business? WhatsApp

      • Importation Tickets error

        Hi, I'm newbie here 🤓 So, i'm importing data from csv, but when I try advance to mapping fields the importer tool show this message: Previously I try import, other data, and not show errors in this step. Some ideas? Best Regards,

      • Showing description in timesheet and timelogs.

        I am wondering if it’s possible in version 5 of Zoho People to have the description show by default or with a manipulation on the user’s part. Let me show you what I mean. As you can see this is the view for the users. Now if they want to see the full

      • Direct “Add to Google Calendar” Option in Zoho Meeting

        Hello Zoho Meeting Team, Hope you are doing well. We would like to request an enhancement related to the “Add to Calendar” functionality in Zoho Meeting. Currently, when we open Zoho Meeting and view our meetings under My Calendar, there is an Add to

      • Workaround: openURL in Blueprints - An alternate approach

        There is a roundabout way to open a URL in blueprints after a save event. By using the 'onBeforeMandatoryFormSave' in Client Script, you can open an external URL. Now, the problem is, this is designed to be run BEFORE the blueprint is saved, not after,

      • MTD SA in the UK

        Hello ID 20106048857 The Inland Revenue have confirmed that this tax account is registered as Cash Basis In Settings>Profile I have set ‘Report Basis’ as “Cash" However, I see on Zoho on Settings>Taxes>Income Tax that the ‘Tax Basis’ is marked ‘Accrual'

      • Migrate file from Single File Upload to Multi File Upload

        Dears, I have created a new field Multi File Upload to replace the old Single File Upload field. I'd like to ask you guys what is the best way to migrate the files to the new field?

      • Open "Live Chat" from a hyperlink?

        Hi, I often write paragraphs and text on our company website, and usually say you can get in touch with us via live chat. Can the chat window be triggered to pop open without clicking the chat graphic in the bottom window, and use it in a hyperlink? ie:

      • Zoho Sites search box

        Is there a Search box that can be added to a Zoho site? It would be for searching within the site only.

      • What stops me from packaging and shipping an order when the inventory is negative?

        It seems if the inventory value is negative, that Zoho Inventory should not allow me to create a Package and Ship it.   But, there seems to be nothing to stop me from doing that other than when I go to physically package the item and realize that there is no stock. There also seems to be nothing on the screen that even indicates to me that I should not package and ship.  To me this is the fundamental point of an inventory system.  Am I doing something wrong?   

      • Conditional formatting based on another field

        Hi I have two fields on my form stage 1 complete and stage 1 deadline.  I am trying to setup conditional formatting so that if stage 1 complete is after stage 1 deadline the record is highlighted in red. I need both stage 1 complete and stage 1 deadline

      • Is there API Doc for Zoho Survey?

        Hi everyone, Is there API doc for Zoho Survey? Currently evaluating a solution - use case to automate survey administration especially for internal use. But after a brief search, I couldn't find API doc for this. So I thought I should ask here. Than

      • Using IMAP configuration for shared email inboxes

        Our customer service team utilizes shared email boxes to allow multiple people to view and handle incoming customer requests. For example, the customer sends an email to info@xxxx.com and multiple people can view it and handle the request. How can I configure

      • The sending IP (136.143.188.15) is listed on spamrl.com as a source of spam.

        Hi, it just two day when i am using zoho mail for my business domain, today i was sending email and found that message "The sending IP (136.143.188.15) is listed on https://spamrl.com as a source of spam" I hope to know how this will affect the delivery

      • Changing a Single-Line Text field into a Multi-line Field without losing data

        Is it possible to change a Single-Line Text field into a Multi-line Field without losing data. I have a module with data for which I would like to change a single-line field into a multi-line field but I'm worried it might delete the pre-existing da

      • Webhook - Google Sheets

        I have 2 forms that are both integrated with Google Sheets. I've set up a webhook to pull form 1 data from Google Sheets to prefill data in Form 2. The issue I have is that the forms name fields are First Name & Last Name but the Google sheets integration

      • Verified Mark Certificate

        Hello Dears, Can anyone help and check my mail or direct me to the desired person who can add the verification tag to my mail https://www.zoho.com/blog/mail/email-authentication-with-bimi.html

      • Appointment booking is temporarily unavailable

        Embeded Zoho booking page in my WordPress website. When someone starts a booking, after choosing time and date, an error appears before payment - "Appointment booking is temporarily unavailable due to restricted settings." Used the embeded code given

      • Cannot connect to 365 business calendar and Teams, says personal but it is not.

        hi I have a number of users connected to their 365 business accounts. Adding a new user and it thinks hes got 365 personal edition. He does not.... Anyone know what's going on. Trying for days now. Bookings go into his MS calendar but as its thinks its

      • Limited review (/questions) for Bookings 2.0

        Hi all, I'm writing this review of Bookings 2.0 for two reasons: 1) it may be of interest to others, and 2) I'd like to be corrected if I'm wrong on any points. It's a very limited review, i.e. the things that have stood out as relevant, and particularly

      • Zoho Bookings - Reserve with Google

        Does Zoho Bookings plan to to integrate with Reserve with Google?

      • Tip #3: How to change your booking page language

        Displaying your booking page in your target audience's language can greatly increase customer satisfaction. By speaking their language, you will help customers feel more comfortable scheduling with you and create a stronger connection with them. Let's

      • Bigin Android app update: Alerts while creating tasks outside of working days, conflicting events and calls.

        Hello everyone! In the most recent version of the Bigin Android app, we have brought in support to display an alert if task is being scheduled outside of the working days. Also, when scheduling an event or call in the Activities module, a conflict alert

      • Bigin update: Link email messages to pipeline records.

        Hello everyone! In the latest version of the Bigin iOS(v1.11.9) and macOS(1.8.9) app, we have brought in support for an option to link email to pipeline records. This helps you to view emails specific to a deal, especially when a contact is associated

      • Next Page