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
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
Sneha Sridharan
Rodrigo
Praveen Sankar
Bradley Ploof
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
Empty folders are now appearing in the sidebar...
...and the folder list is now auto-collapsed by default with no way to change. Neither of these recent updates are useful or user-friendly. ==================== Powered by Haiku https://www.haiku.co.uk ====================Client Script | Update - Client Script Support For Custom Buttons
Hello everyone! We are excited to announce one of the most requested features - Client Script support for Custom Buttons. This enhancement lets you run custom logic on button actions, giving you greater flexibility and control over your user interactions.Zoho CRM for Everyone's NextGen UI Gets an Upgrade
Hello Everyone We've made improvements to Zoho CRM for Everyone's Nextgen UI. These changes are the result of valuable feedback from you where we’ve focused on improving usability, providing wider screen space, and making navigation smoother so everythingCreate custom rollup summary fields in Zoho CRM
Hello everyone, In Zoho CRM, rollup summary fields have been essential tools for summarizing data across related records and enabling users to gain quick insights without having to jump across modules. Previously, only predefined summary functions wereMonthly Webinar - Getting Started with Zoho LandingPage
Are you building your first landing page and want a little guidance? Join our monthly Getting Started with Zoho LandingPage webinar and learn how landing pages fit into your marketing strategy, drive lead generation, and improve conversions. Here’s whatView all email threads directly from record's History and Interactions
Greetings all, We've introduced the ability to view complete email thread conversations directly from records' History and Interactions sections, along with email delivery status and sentiment insights on the Interactions page—which makes it easier forMarketing Tip #22: Check website and navigation for broken links
Do you inspect your online store frequently? If not, here's your reminder to do it now. Broken links frustrate customers and make your store feel unreliable. Whether it’s a missing product page, an outdated menu item, social media accounts, or a brokenIs there a way to show contact emails in the Account?
I know I can see the emails I have sent and received on a Contact detail view, but I want to be able to see all the emails that have been sent and received between all an Accounts Contacts on the Account Detail view. That way when I see the Account detailCustom function return type
Hi, How do I create a custom deluge function in Zoho CRM that returns a string? e.g. Setup->Workflow->Custom Functions->Configure->Write own During create or edit of the function I don't see a way to change the default 'void' to anything else. Addingpush notification to Cliq when user is @mentioned in CRM notes
push notification to Cliq when user is @mentioned in CRM notes. Currently users that is @mentioned gets an email to be notified. User/s that is @mentioned should get a Cliq notification.How to make entries for restaurant sales in Zoho Books?
Hello, I'm new to Zoho Books. I need to understand how to record our restaurant sales in Zoho Books. We can't raise invoices for each bill from the daily sales report generated by our POS (duplicated effort). We need a means of entering cumulative salesCreating Restaurant Inventory Management on Zoho
Hi, We run a small cloud kitchen and are interested to use Zoho for Inventory and Composite Item tracking for our food served and supplied procured to make food items. Our model is basically like subway where the customer can choose breads, veggies,Sending emails via Books
Anyone else getting similar problems recently ??..... Hi, Your message to the following recipient was not delivered. Please find the details below. Bounce Details: Bounced Address : someone@google.com Bounce Reason : other ; Status : 5.0.0 (undefined status) ; Daignostic-Code : smtp;542 someone@google.com Rejected ; Bounced Time : Sep 05, 2017 06:37 PM BST Regards, Zoho Team The email addresses were fine only a few days ago but are now being rejected ?Integrate with WooCommerce using Wordpress Plugin
We’re thrilled to announce a powerful update to the Zoho Marketing Automation WordPress plugin with WooCommerce integration! This enhancement enables new possibilities for businesses running online stores using WooCommerce, empowering them to merge seamlessHow do I sync multiple Google calendars?
I'm brand new to Zoho and I figured out how to sync my business Google calendar but I would also like to sync my personal Google calendar. How can I do this so that, at the very least, when I have personal engagements like doctor's appointments, I canZoho Subscriptions -- Zoho Commerce integration
Is there integration between Zoho Subscriptions and Zoho Commerce? I would like to create subscription plans in Zoho Subscritpions and list them for on my Zoho Commerce store.Domain already exists
Hi, I tried to add my domain creativecolumnist.com but its showing as Domain already exist. Please release if it has already been associated with Zoho, I am the real owner of that domain.Select forwarding
For Zoho mail online on PC in web browser: I had forwarding enabled in section "Mail accounts / Forwards", and I also have some filters that send emails from some unwanted senders to Archive. But it doesn't work as intended, it forwards everything (obviouslyCliq iOS can't see shared screen
Hello, I had this morning a video call with a colleague. She is using Cliq Desktop MacOS and wanted to share her screen with me. I'm on iPad. I noticed, while she shared her screen, I could only see her video, but not the shared screen... Does Cliq iOS is able to display shared screen, or is it somewhere else to be found ? Regardssystem not picking my default custom service report template
Can you tell me why when we create a service report always pick the (standard old) template? Even when I have a custom service report selected as Default.Restrict Appointment Booking to Approved Clients
Dear Zoho Bookings Support Team, We'd like to propose a feature enhancement for managing appointments within Zoho Bookings. This feature would ensure only pre-approved clients can schedule meetings. Desired Functionality: We propose the introduction ofAutomate Credit Card Surcharge
Is there a way to create an automation that will add a 3.0% credit card surcharge to a subscription whenever a customer pays via credit card?Product Request: Send email to Secondary email
Guys, we should be able to send the campaign to the secondary email too. Is this on the plans for Zoho Campaign? It looks like I can map the secondary email from the CRM to the Campaigs, but can not send the message.I have the item field and Quantity field in the sub form , on the submit of the form if the quantity is grater than inventory means show alert on submit validation only for item type goods ,
I have the item field and Quantity field in the sub form , on the submit of the form if the quantity is grater than inventory means show alert on submit validation . Stock Check Validation only for item type goods , not for item type service . For theDisappearance of all articles in the knowledge base
Hi there! It seems like all of our articles have disappeared from the knowledge base: However, the names still appear in the "sort articles" section:Logic for sending to a non-primary email address
Hi, I have a scenario where contacts are able to sign up for emails with 2 different email addresses (example: work, personal). I've mapped both to Campaigns from Zoho CRM, but when I go to target an email only the primary email addresses are pulling in. How can I update this to look at both of the email addresses - or specifically the secondary email address in Campaigns? Thanks, JennyAdd "Reset MFA" Option for Zoho Creator Client Portal Users
Hello Zoho Creator Team, We hope you are doing well. We would like to request an important enhancement related to Multi-Factor Authentication (MFA) for client portal users in Zoho Creator. Currently, Creator allows us to enforce MFA for portal users,Tables for Europe Datacenter customers?
It's been over a year now for the launch of Zoho Tables - and still not available für EU DC customers. When will it be available?NOTAS INVISIBLES
Siempre que abro mis notas salen invisibles, muchas no resaltan las *negritas* en la vista previa hasta que te metes en ellas y modificas algo. Pero omg con el equipo de Zoho. Les dije que las usaba mucho precisamente por la VISTA PREVIA y encontrar lasDoes Zoho has chatroom/chatbot url feature?
Hi Zoho community! I’m looking for a quick "Yes/No" answer for my dev team regarding Zoho’s capabilities. We currently use Zoho Desk for our Service Team and Zoho CRM for our Marketing Team to bring both functions under one platform. Our question: DoesOne Support Email Managed By Multiple Departments
Hello, We use one support email (support@company.com). Incoming emails come to the "Support Department" and based on what the customer is asking, we route that ticket to different departments (billing, technical support, etc.). When users in these differentWhat's New in Zoho Analytics - February 2026
Hello Users! We're back with another round of updates for Zoho Analytics. This month's release focuses on giving you greater flexibility in how you visualize, manage, and act on your data - with new features like custom visualizations, remote MCP server,Is it Possible to Modify Standard Report Urls
Is there a way to permanently modify standard report Urls? Use case: Suppose I have a Products report. Showing list as timeline, calendar, or kanban doesn't make sense. Want to hide that from users by adding #Report:Products?zc_ShowAs=false&zc_Print=falseUpdated font library: New font styles and custom font options in Zoho Sheet
Zoho Sheet's font library now supports 500+ font styles in 60+ languages! The updated font library is stacked with new font styles, and some of the previously available font styles have been replaced with equivalent options. There are two ways you canscope for phonebridge in CRM and phonebridge API documentation
Hi I cannot find the scope to be used for phonebridge in CRM API V2 calls. I am getting OAUTH_SCOPE_MISMATCH for scope group ZohoCRM.modules.ALL,ZohoCRM.setttings.ALL Also I am not able to locate the documentation for the same, All I have is phonebridgeDoes Zoho Mail Have Popout windows?
I recently switched my work email over to Zoho and everything I read said that you can popout the draft email as you're writing, however, all the pictures or info I've seen show the typical popout arrow in the top right, which I can not for the life ofThis domain is not allowed to add in Zoho. Please contact support-as@zohocorp.com for further details
Job Alerts for Candidates
hi All, I have 2 questions relating to sharing job details with candidates. 1. is there a way to notify candidates that meet certain criteria of current jobs available? eg. I run a candidate search, and identify 50 candidates that might be suitable. CanZoho Wiki or new Zoho Learn
We are currently evaluating if we should move off confluence. At present in Confluence we have multiple levels within our documentation but with learn it looks like you can only have Space - Manual - Chapter Is it possible to have levels below Chapter? Also the same question for the existing wiki, can I have more sub-levels?Fix image at bottom of a page fot automatic proposal creation
I'm working on a proposal document to automate our proposal creation process. So far it works fine, but I experience some problems with an image I want to have fixed at the bottom of the page AND above the footer. This section of the document consistsNext Page