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
- Creating a picklist field using the Create Custom Field Metadata API
- Updating a picklist field using the Update Custom Field Metadata API
- Assigning picklist values when creating records using the Insert Records API
- Updating picklist values in existing records using the Update Records API
- 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:
- Add new options
- Update the picklist
- Remove existing options using Update Custom Layout API
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", }, "$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!
Previous Kaizen : Kaizen# 204 - Answering Your Questions - Perform Field Updates before Blueprint transition via Client Script | Kaizen Directory : Home
Related Links :
Access your files securely from anywhere
Centralize Knowledge. Transform Learning.
All-in-one knowledge management and training platform for your employees and customers.
New to Zoho Recruit?
Zoho Developer Community
New to Zoho LandingPage?
Zoho LandingPage Resources
New to Zoho Survey?
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Bigin?
Topic Participants
Subramanian K
Sticky Posts
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.Kaizen #226: Using ZRC in Client Script
Hello everyone! Welcome to another week of Kaizen. In today's post, lets see what is ZRC (Zoho Request Client) and how we can use ZRC methods in Client Script to get inputs from a Salesperson and update the Lead status with a single button click. In thisKaizen #222 - Client Script Support for Notes Related List
Hello everyone! Welcome to another week of Kaizen. The final Kaizen post of the year 2025 is here! With the new Client Script support for the Notes Related List, you can validate, enrich, and manage notes across modules. In this post, we’ll explore howKaizen #217 - Actions APIs : Tasks
Welcome to another week of Kaizen! In last week's post we discussed Email Notifications APIs which act as the link between your Workflow automations and you. We have discussed how Zylker Cloud Services uses Email Notifications API in their custom dashboard.Kaizen #216 - Actions APIs : Email Notifications
Welcome to another week of Kaizen! For the last three weeks, we have been discussing Zylker's workflows. We successfully updated a dormant workflow, built a new one from the ground up and more. But our work is not finished—these automated processes are
New to Zoho TeamInbox?
Zoho TeamInbox Resources
Zoho CRM Plus Resources
Zoho Books Resources
Zoho Subscriptions Resources
Zoho Projects Resources
Zoho Sprints Resources
Qntrl Resources
Zoho Creator Resources
Zoho CRM Resources
Design. Discuss. Deliver.
Zoho Show Resources
Get Started. Write Away!
Writer is a powerful online word processor, designed for collaborative work.
Zoho CRM コンテンツ
-
オンラインヘルプ
-
Webセミナー
-
機能活用動画
-
よくある質問
-
Ebook
-
-
Zoho Campaigns
- Zoho サービスのWebセミナー
その他のサービス コンテンツ
Nederlandse Hulpbronnen
ご検討中の方
Recent Topics
Error AS101 when adding new email alias
Hi, I am trying to add apple@(mydomain).com The error AS101 is shown while I try to add the alias.No Need To Fix Something That Is Working
Zoho Books is a great financial tool which helps businesses to become more efficient and productive with day-to-day operations. As such, every change, upgrade, improvement needs to be carefully thought before implemented in the software and I'm sure ZohoUsing email "importance" as workflow-criteria
I'd like to set up a workflow that triggers if an incoming email has been flagged as "high importance" but I'm not seeing any way to do that. Hopefully I'm just missing something obvious...?This domain is not allowed to add. Please contact support-as@zohocorp.com for further details
I am trying to setup the free version of Zoho Mail. When I tried to add my domain, theselfreunion.com I got the error message that is the subject of this Topic. I've read your other community forum topics, and this is NOT a free domain. So what is theWhat is Resolution Time in Business Hours
HI, What is the formula used to find the total time spent by an agent on a particular ticket? How is Resolution Time in Business Hours calculated in Zohodesk? As we need to find out the time spent on the ticket's solution by an agent we seek your assistanceCheck & Unchecked Task Segregation in Export
It must have a feature to represent checked and unchecked tasks as [ ] and [✅] respectively when exporting it to Arratai or WhatsApp ; as Keep Notes by Google contains…WorkDrive Download Issue
My client has been sending me files via WorkDrive, which generally has worked fine. Recently files won't download at all. If you try and individually select and download a file, a popup will appear in the bottom right saying it's preparing and then itResolution Time Report
From data to decisions: A deep dive into ticketing system reports What are time-based reports? Time-based reports are valuable tools that help us understand how well things are going by breaking down key metrics over specific periods. By tracking, measuring,Support Custom Background in Zoho Cliq Video Calls and Meetings
Hello Zoho Cliq Team, We hope you are doing well. We would like to request an enhancement to the video background capabilities in Zoho Cliq, specifically the ability to upload and use custom backgrounds. Current Limitation At present, Zoho Cliq allowsAdd RTL (Right-to-Left) Text Direction Button in Zoho Cliq
Greetings Zoho Team, We would like to request the addition of an RTL (Right-to-Left) text direction button in Zoho Cliq, similar to what is already available in other Zoho apps like Zoho Desk. Currently, while using Zoho Cliq with the English interface,Enable Backgrounds and Video Filters for 1:1 Cliq Calls Across All Zoho Entry
Hello Zoho Cliq Team, We hope you are doing well. We would like to request an enhancement related specifically to 1:1 video calls in Zoho Cliq. Current Behavior Zoho Cliq currently provides background and video filter options in the following scenarios:Zoho Flow: Stripe a Zoho Marketing Automation
Hola! Quiero hacer un flujo con Zoho Flow, para que cuando se haga un pago en Stripe, añada el lead en Zoho Marketing Automation. Lo he configurado, configurando el disparador como "Payment created" y mapeando el campo de Stripe "Receipt email address".Need Customer Item Inward Module along with QC
Need Customer Item Inward Module along with QC 1. Using Transfer Orders hit the item balance sheet 2. Items without inventory it becomes difficult for tracking purpose. 3. Custom Modules become tedious to capture multiple items, item subforms are notLESS_THAN_MIN_OCCURANCE - code 2945
Hi I'm trying to post a customer record to creator API and getting this error message. So cryptic. Can someone please help? Thanks VarunZoho email
I need a list of email addresses of all contacts on my zohoShift-Centric View for Assigning and Managing Shifts in Zoho People
Hello Zoho People Product Team, Greetings and hope you are doing well. This feature request is related to Zoho People - please don't move it to zoho one! We would like to submit a feature request regarding the shift assignment and management view in ZohoIntroducing parent-child ticketing in Zoho Desk [Early access]
Hello Zoho Desk users! We have introduced the parent-child ticketing system to help customer service teams ensure efficient resolution of issues involving multiple, related tickets. You can now combine repetitive and interconnected tickets into parent-childcant upload images in signature- urgent help needed. ta!
HI, I have been trying to insert the company logo in the signature. i have tried it several times since yesterday, the longest I waited was 1 hour and 12 minutes for the pop up window to upload a 180 KB .jpg file. what am i doing wrong.. an urgent replyAdd Ticket button in Home view
When I go to the My Tickets or the Knowledge Base view in our Help Centre, the Add Ticket button is available, but not in the Home view. I would really like for it to be displayed in the Home view as well. Is this possible? Thanks.Problem using Zoho Desk API
Goodmorning, I am trying to use the Zoho Desk API to create a dashboard in Grafana, but I am having a problem. Following the instructions in the API documentation, I created the API Console application (server-based application). Then I created the stringAdd zoho calendar to google calendar
Hi I keep seeing instructions on how to sync Zoho CRM calendar with google calendar but no instructions on how to view Zoho calendar in my google calendar.How to print a label from zoho creator app?
Hello, I would like to print a label from zoho creator app record similar to attached one. Size 74mm x 102mm. I tried record template. It leaves plenty of space around the content and also I couldn't set the height of the page. So it is not printing properly. Could someone please direct me to right direction for this requirement?City field suggestion in Zoho Books
Hi team, We are using Customers module in Zoho Books. In the Address section, we want to understand whether the City field can show suggestions while typing using any API or built-in feature. For example, if a user types “Mum”, can the system suggestNon-responsive views in Mobile Browser (iPad)
Has anyone noticed that the creator applications when viewed in a mobile browser (iPad) lost its responsiveness? It now appears very small font size and need to zoom into to read contents. Obviously this make use by field staff quite difficult. This is not at all a good move, as lots of my users are depending on accessing the app in mobile devices (iPads), and very challenging and frustrating.How can I check all announce?
Hiii, May I ask how can I check all the announce based on broadcast date instead of reply date based So that I will not will miss out any new functionWhat are the create bill API line item requiered fields
While the following documentation says that the line items array is requiered it doesn't say what if any files are requiered in the array. Does anyone know? API documentation: https://www.zoho.com/inventory/api/v1/bills/#create-a-bill I'm trying to addThis user is not allowed to add in Zoho. Please contact support-as@zohocorp.com for further details
Hello, Just signed up to ZOHO on a friend's recommendation. Got the TXT part (verified my domain), but whenever I try to add ANY user, I get the error: This user is not allowed to add in Zoho. Please contact support-as@zohocorp.com for further details I have emailed as well and writing here as well because when I searched, I saw many people faced the same issue and instead of email, they got a faster response here. My domain is: raisingreaderspk . com Hope this can be resolved. Thank youCannot connect to imap.zoho.eu on iOS26
Hey, I recently migrated to another iPhone and since then use iOS26. Every since then, I was not able to connect to "imap.zoho.eu" from Apple Mail. I tried deleting the account and adding it again, did not work. I tried creating an app password, didn'tPersonalize your booking pages with Custom CSS
Greetings from the Zoho Bookings team! We’re introducing Custom CSS for Zoho Bookings, designed to give you complete control over the look and feel of your booking pages. With this new feature, you can upload your own CSS file to customize colors, fonts,Marketer's Space: Plan smarter with Zoho Campaigns' Calendar
Hello Marketers, Welcome to another post! Today, we'll talk about a discreet yet significant feature that's neatly tucked inside Zoho Campaigns: the calendar. It might look like an optional but somewhat unnecessary feature that you can use occasionally,User
If user is already part of manage engine endpoint central , what hapens when i try to add them to another Zoho org / directory? Are these users added as external users?Create static subforms in Zoho CRM: streamline data entry with pre-defined values
Last modified on (9 July, 2025): This feature was available in early access and is currently being rolled out to customers in phases. Currently available for users in the the AU, CA, and SA DCs. It will be enabled for the remaining DCs in the next coupleOutlook - Zoho CRM Calendar Integration
I'm facing an issue integrating Outlook with Zoho CRM. Has anyone successfully connected their Outlook to Zoho, and are all your meetings and emails being captured correctly in the CRM? Any insights or troubleshooting tips would be appreciated【Zoho CRM】ポータル機能のアップデート
ユーザーの皆さま、こんにちは。コミュニティチームの藤澤です。 今回は「Zoho CRM アップデート情報」の中から、ポータル機能のアップデートをご紹介します。 ポータル管理の新機能「自動招待」により、Zoho CRMからポータルへの招待を自動化できるようになりました。これまで必要だった、ユーザーごとの手動設定は不要になります。設定した条件に基づいて、対象ユーザーに自動で招待が送信されます。 ポータルの新機能 条件に基づく自動招待：指定した条件を満たすユーザーに、自動で招待を送信 招待設定：招待メールの言語を選択し、言語ごとに条件を設定可能Contact data removes Account data when creating a quote
Hi, Our customer has address fields in their quote layout which should be the address of the Account. They prefill the information, adding the account name - the address data is populated as per what is in the account - great. However when they then addExport all of our manuals from Zoho Learn in one go
Hi, I know there's a way to export manuals in Zoho Learn, but I want to export everything in one go so it won't take so long. I can't see a way to do this, can I get some assistance or is this a feature in the pipeline? Thanks, HannahAutomation#31: Automate Splitting Names for New Contact Records
Hello Everyone, This week, we present to you a custom function, which allows you to split the first and last names from the user's email ID based on the separator used in the ID. Having grown into a large firm, Zylker Techfix aims to optimize its processes,Automatically remove commas
Team, Please be consistent in Zoho Books. In Payments, you have commas here: But when we copy and paste the amount in the Payments Made field, it does not accept it because the default setting is no commas. Please have Zoho Books remove commas automProject Change Orders and Additions
We are in the process of migrating from QuickBooks Online to Zoho Books. We have Zoho One and like the ability to sync all of our data across everything. And I like that projects work in a way that's less dumb than QuickBooks. I'm trying to figure outZOHO Desk - Description of slave ticket disappeared after Merge
Dear Support, On Zoho Desk the description of a ticket disappeared after merging two ticket. The one which was the slave one completely disappeared. The problem that in this description there was an image which i had only on Desk in that ticket. CouldNext Page