Kaizen #39 - Deals #API
Hello everyone!
Welcome back to another post in the Kaizen series!
This week, we will discuss retrieving, adding, updating, and deleting Deals via API.
Deals in Zoho CRM
A Deal is a revenue opportunity that is associated with a Contact or Account.
OAuth Scope
The scope to access the Deals module via API is: ZohoCRM.modules.deals.{operation_type}
The operation type can be ALL, READ, WRITE, CREATE, or DELETE based on the operation you are trying to perform.
Retrieving deals via API
Using the Get Records API, you can retrieve the records from the Deals module.
Request URL to retrieve all deals: {{api-domain}}/crm/v2/Deals
Request URL to retrieve a specific deal: {{api-domain}}/crm/v2/Deals/{Deal_ID}
Request Method: GET
Response Keys:
Key with JSON data type | CRM Field Type | Description |
$currency_symbol string | - | Represents the symbol of the currency of the deal amount. |
Campaign_Source JSON object | Lookup | Represents the name and ID of the campaign if the deal is related to one. |
$review_process JSON object | - | Represents the review process details, if the deal was created in review mode. |
$followers JSON array | - | Each object represents the name and ID of the user who is following the deal. |
Closing_Date Date Time in ISO8601 format | Date | Represents the closing date of the deal. |
Last_Activity_Time Date Time in ISO8601 format | - | Represents the date and time when the deal was last updated. |
$review JSON object | - | Represents the review process details. |
Lead_Conversion_Time integer | - | The number of days taken to convert a Lead into a Deal (if the Deal was created from a Lead). |
Deal_Name string | Single Line | Represents the name of the deal. |
Exchange_Rate integer | Number | Represents the exchange rate of the currency of the deal amount. |
Expected_Revenue double | Currency | Represents the expected revenue of the deal. The system calculates the value based on the amount and the Deal Stage that you specify. It is a read_only field. |
Currency double | Picklist | Represents the currency of the deal amount. |
Overall_Sales_Duration integer | - | Represents the average number of days taken for the Lead to be converted to a Deal, and then to be won. |
Stage string | Picklist | Represents the stage of the deal. It can be: Qualification, Needs Analysis, Value Proposition, Identify Decision Makers, and so on. You can customize these values based on your business model. |
Account_Name JSON object | Lookup | Represents the name and ID of the account the deal is associated with. |
id string | - | Represents the unique ID of the deal. |
$approved boolean | - | Represents if the record is approved or not. |
$approval JSON object | - | Represents the details of approval process if the deal is in one. |
Territory JSON array | - | Represents the territories the deal is associated with. |
Amount integer | Currency | Represents the value of the deal. |
$followed boolean | - | Represents if the current user follows the deal or not. |
Probability integer | Number | Represents the probability of deal closure. |
Next_Step string | Single Line | Represents the details of the next steps of the sales process (this may vary based on your business model). |
$editable boolean | - | Represents if the deal is editable or not. |
Contact_Name JSON object | Lookup | Represents the name and ID of the contact the deal is associated with. |
Sales_Cycle_Duration integer | - | Represents the average number of days taken for the deal to be won. |
Type string | Picklist | Represents the type of the deal. These values can be customized based on your business model. |
Lead_Source string | Picklist | Represents the source of the lead. These values can be customized based on your business model. |
Tag JSON array | - | Represents the deal tags if any. |
Owner JSON object | - | Represents the name, ID, and the email of the deal owner. |
Description string | Multi-Line | Represents the description of the deal if any. |
Note:
The keys listed above are available by default. If you have any custom fields in your layout, the data in those fields will also be retrieved.
You can fetch a maximum of 200 deals per API call.
Adding Deals via API
Using the Insert Records API, you can add records to the deals module.
Request URL to add deals: {{api-domain}}/crm/v2/Deals
Request Method: POST
List of keys that you can include in your request body
Description, Campaign_Source, Closing_Date, Deal_Name, Exchange_Rate, Expected_Revenue, Currency, Stage, Account_Name, Amount, Probability, Next_Step, Contact_Name, Type, Lead_Source, Tag, and Owner.
Mandatory Keys
Deal_Name and Stage. Apart from these, you must add all the user-defined mandatory fields too.
You can also insert a deal in a specific layout by specifying the "Layout" details in the following format. In this case, you must ensure that you specify all the layout-specific mandatory fields in the input.
"Layout": { "name": "sample", "id": "4150868000002606001" } |
For more details regarding these keys, refer to the Response Keys section above.
Input
{ "data": [ { "Owner": { "name": "Patricia Boyle", "id": "4150868000001248015", "email": "patricia@zylker.com" }, "Description": "This is a sample Deal", "Campaign_Source": { "name": "Sample", "id": "4150868000000584006" }, "Closing_Date": "2020-07-16", "Deal_Name": "Zylker Deal1", "Currency": "AUD", "Stage": "Qualification", "Account_Name": { "name": "Zylker", "id": "4150868000001416001" }, "Amount": 666.67, "Probability": 10, "Next_Step": "sample", "Contact_Name": { "name": "Alicia Boyle", "id": "4150868000002500007" }, "Type": "New Business", "Lead_Source": "Advertisement" } ] } |
Response
Note:
You can also add custom fields' values. You can get their API names using the Fields Metadata API.
You can insert a maximum of 100 Deals per API call.
Updating Deals via API
Using the Update Records API, you can update records in the deals module.
Request URL to update deals: {{api-domain}}/crm/v2/Deals
Request URL to update a specific deal: {{api-domain}}/crm/v2/Deals/{Deal_ID}
Request Method: PUT
List of keys that you can include in your request body
Description, Campaign_Source, Closing_Date, Deal_Name, Currency, Stage, Account_Name, Amount, Probability, Next_Step, Contact_Name, Type, Lead_Source, Tag, and Owner.
Mandatory Keys
The id is a mandatory key in the input when you update multiple Deals in an API call.
For more details regarding these keys, refer to the Response Keys section above.
Note:
You can also update custom fields' values. You can get their API names using the Fields Metadata API.
You can update a maximum of 100 deals per API call.
Deleting Deals via API
Using the Delete Records API, you can add records to the deals module.
Request URL to delete deals: {{api-domain}}/crm/v2/Deals
Request URL to delete specific deal: {{api-domain}}/crm/v2/Deals/{Deal_ID}
Request URL to delete multiple deals: {{api-domain}}/crm/v2/Deals?ids={id1, id2,..}
Request Method: DELETE
Note: You can pass a maximum of 100 record IDs in the ids parameter.
Refer to Kaizen #25 - Zoho CRM API - Common Errors and Error Handling to know more about the errors related to Deals API.
The Stage History of a Deal
Using the Get Related Records API, you can get the details of the related lists of a deal. One such related list is Stage History with which you can track and record the different stages that a deal has been through.
Request URL to get stage history of a deal: {{api-domain}}/crm/v2/Deals/{Deal_ID}/Stage_History
Request Method: GET
Key with data type | Description |
$duration_days integer | Represents the number of days the deal was in a particular stage. |
Stage string | Represents the unique ID of the stage. |
id string | Unique ID of the deal in that particular stage. |
We hope you found this post useful.
Write to us at support@zohocrm.com if you have any questions, or let us know in the comment section.
Cheers!
Next 'Kaizen' - System-defined fields and their default values in Leads #API
Access your files securely from anywhere
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
Sneha Sridharan
Rodrigo
Praveen Sankar
Bradley Ploof
Subramanian K
Sticky Posts
Kaizen #197: Frequently Asked Questions on GraphQL APIs
🎊 Nearing 200th Kaizen Post – We want to hear from you! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.Kaizen #198: Using Client Script for Custom Validation in Blueprint
Nearing 200th Kaizen Post – 1 More to the Big Two-Oh-Oh! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.Celebrating 200 posts of Kaizen! Share your ideas for the milestone post
Hello Developers, We launched the Kaizen series in 2019 to share helpful content to support your Zoho CRM development journey. Staying true to its spirit—Kaizen Series: Continuous Improvement for Developer Experience—we've shared everything from FAQsKaizen #193: Creating different fields in Zoho CRM through API
🎊 Nearing 200th Kaizen Post – We want to hear from you! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.Client Script | Update - Introducing Commands in Client Script!
Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! Commands
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
Show/ hide specific field based on user
Can someone please help me with a client script to achieve the following? I've already tried a couple of different scripts I've found on here (updating to match my details etc...) but none of them seem to work. No errors flagged in the codes, it justWhy I am unable to configure Zoho Voice with my Zoho CRM account?
I have installed Zoho Voice in my Zoho CRM, but as per the message there is some config needed in Zoho Voice interface. But when I click on the link given in the above message, I get an access denied page.Adding Multiple Products (Package) to a Quote
I've searched the forums and found several people asking this question, but never found an answer. Is ti possible to add multiple products to a quote at once, like a package deal? This seems like a very basic function of a CRM that does quotes but I can't500 Internal Server Error
I have been trying to create my first app in Creator, but have been getting the 500: Internal Server Error. When I used the Create New Application link, it gave me the error after naming the application. After logging out, and back in, the application that I created was in the list, but when I try to open it to start creating my app, it gives me the 500: Internal Server Error. Please help! Also, I tried making my named app public, but I even get the error when trying to do that.Client Script | Update - Client Script Support For Portals
Dear All! We are excited to announce the highly anticipated feature: Client Script support for Portals. We understand that many of you have been eagerly awaiting this enhancement, and we are pleased to inform you that this support is now live for allAlias Email Id already exists
Hi I'm trying to create an alias : contact @ yoavarielevy.co.il but i get the message Alias Email Id already exists I had an account with the same name but I deleted it. Can you help? Thanx YoavProfessional Plan not activated after payment
I purchased the Professional Plan for 11 users (Subscription ID: RPEU2000980748325) on 12 September 2025, and the payment has been successfully processed. However, even after more than 24 hours, my CRM account still shows “Upgrade” and behaves like aZoho Books - France
L’équipe de Zoho France reçoit régulièrement des questions sur la conformité de ses applications de finances (Zoho Books/ Zoho Invoice) pour le marché français. Voici quelques points pour clarifier la question : Zoho Books est un logiciel de comptabilitéhow to edit the converted lead records?
so I can fetch the converted leads records using API (COQL), using this endpoint https://www.zohoapis.com/crm/v5/coql and using COQL filter Converted__s=true for some reasons I need to change the value from a field in a converted lead record. When I tryAuto Update Event Field Value on Create/Edit
Hi there, I know this question has been posted multiple times and I've been trying many of the proposed similar scripts for a while now but nothing seems to work... what might I do wrong? The error I receive is this: Value given for the variable 'meetingId'Pre-orders at Zoho Commerce
We plan to have regular producs that are avaliable for purchase now and we plan to have products that will be avaliable in 2-4 weeks. How we can take the pre-orders for these products? We need to take the money for the product now, but the delivery willConstant color of a legend value
It would be nice if we can set a constant color/pattern to a value when creating a chart. We would often use the same value in different graph options and I always have to copy the color that we've set to a certain value from a previous graph to makeZoho Pagesense really this slow??? 5s delay...
I put the pagesense on my website (hosted by webflow and fast) and it caused a 5s delay to load. do other people face similar delays?Payroll and BAS ( Australian tax report format )
Hello , I am evaluating Zoho Books and I find the interface very intuitive and straight forward. My company is currently using Quickbooks Premier the Australian version. Before we can consider moving the service we would need to have the following addressed : 1.Payroll 2.BAS ( business activity statement ) for tax purposes 3.Some form of local backup and possible export of data to a widely accepted format. Regards Codrin MitinProblem with Email an invoice with multiple attachments using API
I have an invoice with 3 attachments. When I send an email manually using the UI, everything works correctly. I receive an email with three attachments. The problem occurs when I try to initiate sending an email using the API. The email comes with onlyPage Layouts for Standard Modules like CRM
For standard modules like quotes, invoices, purchase orders, etc, it would be a great feature to be able to create custom page layouts with custom fields in Zoho Books similar to how you can in Zoho CRM. For example, and my current use case, I have aNon-depreciating fixed asset
Hi! There are non-depreciable fixed assets (e.g. land). It would be very useful to be able to create a new type of fixed asset (within the fixed assets module) with a ‘No depreciation’ depreciation method. There is always the option of recording landFixed asset management
I want to know if there is any individual module for fixed assets managementOne time sale item in billing automatically detects as service
if i have some items which i don't want to add in my "item" list because its sold only for one time. but when i type item name in invoice, it (system) automatically takes it as a service and despite of HSN , it shows SAC code to be entered. if its selectable i.e. either item or service , it would be very helpful and a must have feature.Project template after project creation
How can I apply a project template AFTER the project has been created?convert the project to templet
i have some deployment ME product for different customer , i need to create a fixed template for use it rather then keeping creating this template every timeIs there a notification API when a new note is addeding
Trying to push to Cliq, or email notification when there's a new note added in module. How to implement this?Seriously - Create multiple contacts for leads, (With Company as lead) Zoho CRM
In Zoho CRM, considering a comapny as a lead, you need us to allow addition of more than one contact. Currently the Lead Section is missing "Add contact" feature which is available in "Accounts". When you know that a particular lead can have multipleRelated Module in Sharing Rules
Zoho CRM team recently added the feature to filter records by Related Records It will be really beneficial if we can have this feature for Sharing Rules as wellAssignment Thresholds Resetting After Lead Conversion
Hello everyone, We're facing an issue with Zoho CRM's lead assignment thresholds that makes them unsuitable for our workflow. I'm hoping to find a potential workaround or solution from the community. Here’s our current process: A new lead is created automaticallyVendor Signatures Needed for Purchase Orders
Hello everyone, We have a unique requirement that necessitates that Vendors & Suppliers formally acknowledge our Purchase Orders upon receipt. I was hoping that there would be an option to do so in Zoho Books, but that does not appear to be the case.Export Invoices to XML file
Namaste! ZOHO suite of Apps is awesome and we as Partner, would like to use and implement the app´s from the Financial suite like ZOHO Invoice, but, in Portugal, we can only use certified Invoice Software and for this reason, we need to develop/customize on top of ZOHO Invoice to create an XML file with specific information and after this, go to the government and certified the software. As soon as we have for example, ZOHO CRM integrated with ZOHO Invoice up and running, our business opportunitiesZoho 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 goTerritory view for custom modules?
I have recently activated territories however I can't seem to find how to use territories for custom modules? These modules have territories: Contacts / Accounts / Opportunities These modules don't have territories: Buildings (custom module) andZoho Books - How to Invoke a Custom Function in Schedulers
We have multiple schedulers that send emails to customers in batches. Currently, we are maintaining the same code across several schedulers. Is it possible to use a custom function inside a scheduler script? If yes, how can we invoke the custom functionAdding a developer for editing the client application with a single user license
Hi, I want to know that I as a developer I developed one application and handed over to the customer who is using the application on a single user license. Now after6 months customer came back to me and needs some changes in the application. Can a customeradditional accounts
If I brought 5 emails to my account. Can I later buy additional emails.Approval Process Comments
Is it possible to view the comments entered during the approval or rejection of a record in the approval process? If not, is there a way to require a field to be completed upon approval or rejection?Login for test case
Had a few questions regarding authentication test cases and couldn't find an answer in the the docs. 1. If an app like Zoho Creator requires authentication before providing access, do I need to create a login function and add it to each test case? 2.Zoho / Outlook Calendar sync
The current Marketplace -> Microsoft -> Meetings integration needs 2 changes. 1. The current language for the Two-Way sync option should be changed. It currently states, "Sync both your Zoho CRM Calendar and Office 365 Calendar meetings with each other."Collaps Notes
There are times when long/large notes are added to a record i.e. Accounts or Deals etc. Currently, the full note is displayed in the notes related list section. It would be great if by default only 5 to 10 rows of the note are displayed when the noteGST Slabs Redefined: Stay Compliant Using Zoho Books!
Hello Everyone! The Government of India is rolling out new GST rates, a major reform aimed at simplifying the current tax structure starting 22 September 2025. GST will move from four slabs (5%, 12%, 18%, 28%) to two main slabs (5% and 18%), plus a specialForm Rules for Suburb Categories to alternate landing pages or Making a Fields Contents ALL CAPS
I need to send differentform submissions to two to three different thank-you URLs (for Meta/Google pixels) depending on which suburb a user selects in a form. I have ~400 suburbs split into two categories (A and B, based on business value). Current challenges:Please make it easier to Pause syncing
right now it takes 3 clicks to get there. sounds silly, but can you make it just 2 clicks to get it done instead? thats how dropbox does it, 2 clicks to pause instead of 3.Customer members area
Does FSM support a customer members area? If not what do you propose we use if we want the data used in FSM for customers to give them an area / login to see past orders, create new orders and general announcements.Next Page