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 #152 - Client Script Support for the new Canvas Record Forms
Hello everyone! Have you ever wanted to trigger actions on click of a canvas button, icon, or text mandatory forms in Create/Edit and Clone Pages? Have you ever wanted to control how elements behave on the new Canvas Record Forms? This can be achievedKaizen #142: How to Navigate to Another Page in Zoho CRM using Client Script
Hello everyone! Welcome back to another exciting Kaizen post. In this post, let us see how you can you navigate to different Pages using Client Script. In this Kaizen post, Need to Navigate to different Pages Client Script ZDKs related to navigation A.Kaizen #210 - Answering your Questions | Event Management System using ZDK CLI
Hello Everyone, Welcome back to yet another post in the Kaizen Series! As you already may know, for the Kaizen #200 milestone, we asked for your feedback and many of you suggested topics for us to discuss. We have been writing on these topics over theKaizen #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.
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
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 fullDirect “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 toAdd Flexible Recurrence Options for Meeting Scheduling in Zoho Cliq (e.g., Every 2 Weeks)
Hello Zoho Cliq Team, We hope you are doing well. Currently, when scheduling a meeting inside Zoho Cliq, the recurrence options are limited to Daily, Weekly, Monthly, and Yearly. There is no ability to set a meeting to occur every X weeks — for example,Sales Order, Invoice and Payment numbers
Hi zoho friends, it is me again, the slow learner. I'm wondering if there is a way to have it so the Sales order, invoice and payment numbers are all the same? It would be easier for me if they were the same number so there is not so many reference numbersAbility to Add YouTube Video to Playlist During Publishing
Hi Zoho Social Team, How are you? While publishing YouTube videos through Zoho Social, we noticed that the platform currently does not allow selecting a playlist at the time of publishing. Instead, we can only add the video to a playlist after it hasAbility to Change Visibility of Published YouTube Videos
Hi Zoho Social Team, How are you? We would like to request an enhancement in Zoho Social regarding the management of already published youtube videos. Currently, after publishing a youtube video through Zoho Social, there is no option to change its visibilityImportation 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,Ask the Experts 24: Analytics, data administration, and mobile experience with Zoho Desk
Hello Everyone! Welcome back to the Ask the Experts(ATE) series! We were so focused on our Autumn 2025 release that we didn't host an ATE session last month. In this month's ATE, we'd like to expand our areas for discussion: we'd like to listen to yourUpdate on the client portal URL for Guest users
We’re updating the way Guest users access their Connect network. As part of this change, all client organization portals used by Guest users will now be accessible through a dedicated domain specific to each data center. The access URLs mentioned hereWorkaround: 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 deadlineZoho Books | Product updates | October 2025
Hello users, We’ve rolled out new features and enhancements in Zoho Books. From iOS 26 updates to viewing reports as charts, explore the updates designed to enhance your bookkeeping experience. Zoho Books Updates for Apple Devices At WWDC 2025, AppleIs 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. ThanUsing 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 configureTask Due Date greater than 10 years.
We use recurring tasks in Projects where every week, month, year etc Some of our projects are greater than 10 years and we are unable to set a new due date because the difference between start date and due date is greater than 10 years. As an exampleThe 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 deliveryChanging 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 daWebhook - 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 integrationVerified 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.htmlAppointment 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 givenCannot 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 itsLimited 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 particularlyZoho 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'sBigin Android app update: Zoho Books integration
Hello everyone! We’re excited to introduce Zoho Books integration on the Bigin Android App. Once the integration is completed in the web(bigin.zoho.com), the Zoho Books tab will be visible in detail View of Contacts, Companies, and Pipeline records. TheBigin 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 alertEmail in each module
We have a contact ,module which then has a link to customer assets which in turn the asset has a multiple link to service visits. When we link assets to customers we choose by name and it brings over the associate email via the lookup. Great feature.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 associatedBigin Android app update: Custom buttons and widgets
Hello everyone! We are excited to introduce custom buttons and widgets on the Bigin Android app. Widgets: A widget is a customizable UI component in Bigin that improves efficiency and user experience. It lets businesses embed components, streamline interactions,Biometric Access Support on Zoho Vault Desktop App
Is there any plans to add biometric authentication (fingerprint, face recognition) for Vault desktop apps (Windows/macOS) to enhance security and ease of access. I would love to hear other members view on thisZoho Sheet for Desktop
Does Zoho plans to develop a Desktop version of Sheet that installs on the computer like was done with Writer?Create Assemblies API Assistance
I am using the Create Assemblies API documented here https://www.zoho.com/inventory/api/v1/compositeitems/#create-assemblies , however I'm getting the following error. {"code":1048,"message":"Sorry, there was an internal error. Please contact {0} forZoho Sheet - Desktop App or Offline
Since Zoho Docs is now available as a desktop app and offline, when is a realistic ETA for Sheet to have the same functionality?I am surprised this was not laucned at the same time as Docs.Collective-booking event not added to all staff calendars
We assign two staff to certain events. When the client books this event, it adds it to one staff calendar (the 'organiser') but not the other. How can I ensure all staff assigned to a collective booking get the event in their calendar? (A side note: itProject Management Bulletin: October, 2025
Every need leads to innovation. Project Management tools were developed out of sheer necessity to drive large projects. With wide usage, the specifications grew precise, and so did the refinement. Over years we’ve crafted one of the best project managementNext Page