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 #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 areKaizen #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.
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
Accounting on the Go Series-55: Seamlessly Add New Vendors While Creating Transactions from Scanned Documents
Hi there! We’ve made handling documents and vendors in Zoho Books even simpler. Now, when you upload a document and scan it, if the app detects a vendor that isn’t already in your organization, you don’t have to leave the page to add them manually. WithAccounting on the Go Series-57: Effortlessly Add and Manage Bank Accounts from the Zoho Books Mobile App
Hi all, Great news for our users in the US and Canada! Managing your finances just got a whole lot easier. Zoho Books has always made it seamless to integrate bank accounts and fetch feeds automatically. Now, we’re taking it up a notch—directly from theAccounting on the Go Series:58-Effortless Compliance: Download XML for Invoices & Credit Notes on Mobile
Hi there! In Mexico, XML files are crucial for electronic invoicing and fulfilling SAT (Tax Administration Service) requirements. These files ensure your transactions are accurately recorded and tax-compliant. Now, you don’t need to rely on the web appAuto Generated Invoice number YEAR
Auto Generated Invoice number shows transaction year as 25 even though it's 24 still.Books generiert keine valide XRechnung
Hallo zusammen, ich möchte hier ein Problem ansprechen, das mir aktuell bei der Nutzung von Books erhebliche Schwierigkeiten bereitet, und hoffe auf Austausch oder Lösungsansätze von anderen Nutzern. Bei der Erstellung von XRechnungen mit Books tretenWHEN UPDATE ORGANIZATION INFO OLD INVOICES ALSO CHANGE INVOICING DATA
Hi We have updated our tax information because we have become a company, up until now we were an individual. The problem is that when updating the data in the zoho books profile all the old invoices change their tax information as well. Is there a wayInvoice import error - duplicate customer name column - there are no duplicates
It is not allowing the importing of any rows because of a duplicate customer name problem, but there are no duplicates in the custoemr name row. Has anyone dealt with this issue before?[WEBINAR][Feb 2025] Automate your entire financial operations from receipts to reconciliation with Zoho Books & Zoho Expense integration
Hello there, We are hosting a free, live webinar on the importance of travel and expense management solutions for businesses, and how Zoho Expense automatically syncs with Zoho Books to simplify your accounting even further. The webinar is on FebruaryCustomize Layout
I am using "Customize Layot" for customize Quotation template but I try to add logo into the header by "%ScaledLogoImage%" code but dont add logo into header. what is problem?Problem - cant add Users (i.e. Zoho one / CRM Users) to BCC or CC in email, i.e. Sales orders or Retainers
I can go to zoho books email templates, and select any email template, and automatically include any Zoho One user, i.e. member of staff. However in the context of sending an email, it will not let us add a member of staff from the user list, insteadUK MTD ITSA
UK Making Tax Digital for Income Tax I have had notice this is to apply from April 2026. What is Zoho doing about this? I will need to start planning to implement this in the next months so need an update as to what I will and will not be able to do inPartial refunds
I am trying to process refund for a one item invoice, however the refund is partial: i am getting this error while creating credit note, can anyone share some wisdom about thisZoho Books Roadshows are back in the UAE!
Hello there, Business owners and accounting professionals of the UAE, we’re coming to your cities! FTA accredited Zoho Books is now officially one of the Digital Tax Integrators in the UAE. With the newly launched direct VAT filing capabilities, we'reNew user After moving over from QBO
New user observations/suggestions. QBO took away a lot of features I was used to with the desktop version. Chaos ensued. Zoho Books has a lot of what I was used to and a bit more. Good deal Some things I have run into and suggest some upgrades. 1: TheSole Trader - Financial Advisor (Appointed Representative) - Paid via Capital Account but no Invoicing...
Hi. I'm about to venture into a new business after 12 months of intensive learning/exams. A little chuffed if I may say so especially at 52! I really like the look of ZoHo Books for my modest enterprise but I'm in need of some guidance, please. My servicesMulti-Unit Inventory with Flexible Unit Selection (Purchase in One Unit, Sell in Another)
We need multi-unit inventory management in Zoho Books with the flexibility to choose units (e.g., Box or Piece) at the time of purchase or sale. For example, if 1 Box = 10 Pieces, we should be able to record purchases in Boxes but sell either in BoxesDisputed Purchase Invoices
We have recently moved to Zoho Books from Sage. In Sage we were able to post a purchase/vendor invoice but mark it as on dispute. This would usually be a pricing query or if something was damaged. It would show in their ledger, so we could agree theirNo TDS Deduction
In some of our case, where we are reselling items at the same rate we purchased. In this scenario, Indian IT Law has a provision to request customer not to deduct TDS if the transaction value is same. TDS is paid by us (intermediary reseller) before weCBSA - GST CHARGES on imports
Hi there, We have a questions about landed cost categorization. We received a shipment from overseas. CBSA invoiced us for the GST on the items. Now we entered the CBSA-GST as a separate bill and attached it as landed cost to the main invoice based onZoho Books
How do I manually insert opening balance?Sales order & purchase order item links for item details
This is fantastic for checking lots of things, I use it a lot. It would be great to see it extended to invoices & bills On another note, may as well throw in my favourite whinge ..... Wish you guys would get the PO receive differences sorted urgently,Bank charges are applied. Please select a bank account.
Hello, I'm trying to add bank charges to a customer payment, but I get the error message "Bank charges are applied. Please select a bank account." I found this old thread, where it says that I need to "select a Bank account for the 'Deposit To' dropdownHow to add receipts
How to add receiptsSupport for auto-upgrade in TrueSync (for Windows)
WorkDrive TrueSync app now supports auto-upgrading to the latest version for Windows OS. You must manually download and install the TrueSync app version 3.4.0 to avail this feature. Download the latest TrueSync app for Windows (version 3.4.0) SupportedWorkDrive API Documentation
WorkDrive provides users and developers an extensive set of APIs to help integrate functionalities of Zoho WorkDrive with other Zoho applications and third-party tools. We have published the official WorkDrive API Documentation page for all external users.March 15, 2023: Zoho Docs is discontinued
As of today (March 15, 2023) Zoho Docs is discontinued for all users. We would like to thank our customers for trusting us for so many years! Going forward, we're confident you'll enjoy using Zoho WorkDrive for all your advanced file management and collaborationIntroducing WorkDrive 4.0: Enhanced productivity. Advanced data administration. (Phase 1)
Hello All, We're excited to share the release of WorkDrive 4.0, which includes important new features and enhancements focused primarily on productivity, secure collaboration, data administration, integrations, and user experience. Read the official announcementExternal download link limit
Can You please help us to understand this For Zoho WorkDrive external users, the download limit is a maximum of 5 GB total download size and a maximum of 50 first-level files and folders What is the meaning of first level? We are using these files inDynamically catching new file creations
I have a team folder with many subfolders, and in those folders we add new documents all the time. I'd like to have a workflow or script to notify me (and then take other actions) when a file is added anywhere in that structure that ends in "summary.txt".Rotate an Image in Workdrive Image Editor
I don't know if I'm just missing something, but my team needs a way to rotate images in Workdrive and save them at that new orientation. For example one of our ground crew members will take photos of job sites vertically (9:16) on his phone and uploadWorkflow workdrive rollout
Hi! When will workflow be rolled out to all users? Thanks.Creating and managing a Team Folder using WorkDrive TrueSync
Hello everyone, Are you tired of constantly switching between your Desktop TrueSync app and the WorkDrive web app to create and manage Team Folders? We’ve made things easier for you. You can now create and manage Team Folders directly within the TrueSyncEdit images seamlessly with WorkDrive's built-in Image Editor
Are you tired of switching between multiple tools just to make simple edits to your images? We understand the hassle, which is why Zoho WorkDrive now comes with a built-in image editing tool, powered by Zoho Annotator. This tool allows you to edit imagesSupercharge your email workflow with WorkDrive's add-in for Microsoft Outlook
Consider this: You’re handling a critical project, and your inbox is packed with important attachments, email threads, and client communications. The back-and-forth routine of downloading files to your computer, uploading them to WorkDrive, and manuallySecure and promote your content with Custom Watermarking
Imagine this: You’re a professional photographer who regularly shares your work online with potential clients and collaborators. Recently, you notice that some of your images have been reposted without any credit or permission. This not only impacts yourJoin us in Singapore for the Zoho WorkDrive User Group meetup!
Hello, everyone! Exciting news! We'll be hosting an upcoming Zoho WorkDrive user group meetup in the beautiful city of Singapore this November. At this Zoho User Group meetup, we'll guide you through ways to use WorkDrive as a platform and build customWorkDrive TrueSync now supports ARM64-based Windows devices!
We’re excited to announce that the Zoho WorkDrive TrueSync app now fully supports Windows devices with ARM64 architecture! Whether you're working on an ARM-based device or an x64 processor, you can now enjoy the same seamless file synchronization experienceOption to Disable Download for Documents Shared via Permalink
Dear Zoho Writer Team, Currently, when sharing a Writer document using the regular permalink (Collaborators with external users), there is no option to restrict the ability to download the document. While the external share link allows such restrictions,How to Download a File from Zoho WorkDrive Using a Public Link
How to Download a File from Zoho WorkDrive Using a Public Link If you're working with Zoho WorkDrive and want to download a file using a public link, here's a simple method to do so using API or a basic script. This approach helps developers or teamsdomain not verified error
Hi when i try to upload a video from zoho creator widget to zoho work drive iam getting domain not verified error.I don't know what to do .In zoho api console this is my home page url https://creatorapp.zoho.com/ and this is my redirect url:www.google.com.IamNext Page