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
アナリティクスで商談中のパイプライン(ステージ）の件数比較
アナリティクスで商談中のパイプライン(ステージ）の件数を前週と前々週で比較したい。前々週の件数が更新することで変動してしまう。対象方法をご教授ください。How do I remove a data source from Zoho Analytics?
I am unable to find a delte option on a datasource that i put in the system as an error. On teh web it refers to a setup icon but I do not see that on my interface?Exclude Email or Domain From New Ticket Notification
Hi, we utilize the new ticket notification feature in Zoho Desk. However, it would be great if there was a way to exclude certain email addresses or domains from receiving the automatic notification. This would be particularly helpful for automated alertsIdentify and clean hard bounce lists in Automation 2.0
Hello. 1. I want to know how I can identify hard bounces in the lists I created to clean them before sending an email, given that the bounce rate has increased and it is necessary to clean the lists. 2. How can I exclude hard bounces and invalid emailsTrigger workflows from SLA escalations in Zoho Desk?
Hey everyone, I’m currently working with SLA escalation rules in Zoho Desk and ran into a limitation that I’m hoping someone here has solved more elegantly. As far as I can tell, SLA escalations only support fairly limited actions (like changing the ticketDelete a department or category
How do I delete a Department? Also, how do I delete a Category? This is pretty basic stuff here and it's impossible to find.Zoho Webinar - Sharing System Audio (NOT AVAILABLE)
Hi, We are having a serious problem with Zoho Webinar. In the webinars we run, we very often share the audio from a video we are streaming directly from YouTube or other applications. Until recently we were using Zoom, but as we use other Zoho applicationsLost the ability to sort by ticket owner
Hi all, in the last week or so, we have lost the ability to sort tickets by Ticket Owner. Unlike the other columns which we can hover over and click on to sort, Ticket Owner is no longer clickable. Is it just us, or are other customers seeing this too?Cancellation Fees
Hi, It really would be good if Billing could take subscription management further with cancellations & being able to apply or set a cancellation fee for a plan that is either fixed or prorated. It is not uncommon in subscriptions for cancellation feesCustom Field for Subscription
Hi, I can't find a way to add a custom field (to contain a license key generated from our software) against a subscription? Is the only place to add this information in the Invoice module (as custom field for invoice)? When a customer views his subscriptionZoho CRM Meetings Module Issues
We have a use-case that is very common in today's world, but won't work in Zoho CRM. We have an SDR (Sales Development Rep) who makes many calls per day to Leads and Contacts, and schedules meetings for our primary Sales Reps. He does this by loggingNotes - Reaction Buttons
Using the native notes option within CRM is fine, it works and the RTF features are great, however, would it be possible - if there isnt already something in place, where we can add a reactions button, similar to teams/whatsapp to show that its been readHow to get the campaingns key?
Reading the documentations of the API, I see that is necessary have the campaign key, but I don't see how can I get it. For example to get the campaign details we need to do the request: https://campaigns.zoho.com/api/getcampaigndetails?authtoken=[API Authentication Token]&scope=CampaignsAPI&campaignkey=[campaignkey] I have the API Authentication Token but I don`t see how to generate the campaignkeyUnable to switch existing AWS RDS connection to DataBridge after moving RDS behind VPN
Unable to switch existing AWS RDS connection to DataBridge after moving RDS behind VPN Hi everyone, I’m facing a problem with an existing Zoho Analytics setup and would like to know the best migration path. Originally, my Zoho Analytics connection to[Bug] WebAuthn passkey registration blocked on rpIds with TLDs longer than 6 characters (.accountant, .technology, etc.) — isValidDomain regex too strict
Hi, Filing on behalf of an enterprise customer where Zoho Vault is deployed across the company. The Chrome extension blocks WebAuthn passkey registration on legitimate sites whose Relying Party ID (rpId) has a TLD longer than 6 letters. This affects everyNative QuickBooks integration for Zoho CRM: Connecting sales and finance
Greetings, I hope all of you are doing well. We're excited to announce Zoho CRM's integration with QuickBooks Web, which is designed to synchronize your CRM data with your QuickBooks accounting records and bridge the gap between sales and finance. ThisSyncing zoho books into zoho crm
I was wondering how I can use zoho books in crm as I have been using them separately and would like to sync the two. Is this possible and if so, how? ThanksZohoBooks_add_expense_attachment Fails
I'm working MCP in Claude to automate bookkeeping. Claude cannot seem to attach and reciept to an expense. The 'add expense attachment' tool is added to the server and enabled in Claude. I asked Claude to give me the calls he performed and this is whatZohoBooks_create_chart_of_account
I'm setting up Claude to do my bookkeeping workflows using a Zoho MPC server I setup. He does not seem to be able to create a chart of account. The 'create chart of account' tool is added to the server and enabled in Claude. I asked Claude to give meZoho Books Product Road Map
I am planning to look into Zoho Books to maintain my Company's Account Books. Is the roadmap of Zoho Books Development available online? What happens if you product dies, without an export feature to other popular Accounting softwares like Tally or Quickbook. Are we going to be left in lurch? Do you have a product road map? Regards, Vishal.I want to delete the email but I can't.
I want to delete emails but I can't, please help me. Thanks!Error while creating new user
Zoho Mail is blacklisted on magicspam.com and spamauditor.org
As of today, the same problem with the IP addresses 136.143.188.51 and 136.143.188.52 How long does it take them to clear their IP addresses? I've read on this forum that these IP addresses have been blacklisted for years. //////////////////////// ThisUnable to send emails from the delegated mailbox
currently it's not possible to send emails from our delegated mailbox (just in our own name, our own mail-accounts) The permissions granted include "Send as," and we are also unable to delete delegated employees or add new ones. We can only add employeesChange Password
How can I reset OR Change the Passwords for the Whole Organization at Once as Administrator using Admin Console?Zoho Books bill pay option not available with zoho one
Why isn't Zoho Books bill pay add-on not available for Zoho one customers not even as a purchasable option. I think this is very inconvenient for companies wanting to use this feature all in one systemSupport - what am I doing wrong?
Hi Everyone - I'm a new user and looking particularly for a replacement mail service. I'm just a home user not a professional but I do look after half a dozen domains. Zoho looks lovely and I'd like to switch but just want to get answers to a few 'easy'Zoho Forms - Form Availability Redirect Option
Hi Forms Team, It would be great if there was a redirect URL option on the Form Availability settings. For example, I would like to create a support form which is only available outside business hours and if the current data and time is not Mon-Fri 9-5Consider Making Printing Easier (UI)
I'm using Zoho Analytics in much the way that it was intended when it was "Zoho Reports" - as a way to pull together information across several apps in the ecosystem. I have a dashboard that I need to run each week for every employee (change the filterEmail Routing to Zoho from Cloudflare
Hello, I'm new to Cloudflare, having had my domain hosted on Fasthosts and just used it for email forwarding. I'm looking for a little help to configure my email routing/hosting. I've looked at the documentation but haven't found exactly what I need toEmails
Good Morning, Is anyone else experiencing emails bouncing back? Thanks,Secondary Reporting Manager permission level
Hi, same time last year I was speaking to Zoho about the use of a Secondary Reporting Manager and certain challenges that I was facing. at the time, I was told that this functionality did not exist. I am still facing challenges, so I would like to askwhy is my folder list is gone?
Hi, All my email folders are gone, i cant found any email. could you please check it?Our ZOHO mail is not working
ZOHO mail is not working for any of our company's employees. All are able to access it in mobile. But not in laptops as a app or in webpage. please help asap.Request to Release Email Aliases for Our Domain
Dear Zoho Support Team, Greetings, We are currently configuring the email system for our organization in Zoho Mail and encountered an issue while creating several email aliases. When attempting to create these aliases, we receive the following error message:Changing Base Currency to USD (we are based in the UAE)
Hello everyone, Good day. We are based on the UAE and our bookkeeping is in USD. I followed the online resource that I select the country first where the currency I want as base is native then later on changed the country once the whole setup is done.Error "The domain pinakajewels.com appears to be already in use in another organization. Learn More"
Hi Team, I have the following account with zoho mail Organization ID: 644368849 This zoho mail account was earlier mapped to www.senacareese.com I no longer own the domain www.senacareese.com I wish to map www.pinakajewels.com to the same zoho mail account.Add personal Facebook to Zoho Social
Hi. is there any way i can post to my business and personal Facebook and Instagram at the same time when I make or schedule a post?Option to Delete Chats in IM
Currently, there is no option to delete any chats in IM, regardless of their source.Billing Status Update
Hello Latha, I’m working on a new automation (deluge) to fulfill one of our requirements. In this automation, there is a step to update the Work Order billing status from “Not Yet Invoiced” to “Non-Billable.” I tried to find the API information relevantNext Page