Kaizen #39 - Deals #API

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.
Click here to know more about scopes.

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!



    • 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 FAQs

    • Kaizen #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

    • Recent Topics

    • Converting Sales Order to Invoice via API; Problem with decimal places tax

      We are having problems converting a Sales Order to an Invoice via API Call. The cause of the issue is, that the Tax value in a Sales Order is sometimes calculated with up to 16 decimal places (e.g. 0.8730000000000001). The max decimal places allowed in

    • Sorting columns in Zoho Projects

      Hi, In project management best practice, sorting columns (ascending, descending) is an important tool. Sorting dates to see the order of tasks starting, sorting on priority or even on planned hours is a must for an efficient project control. Currently,

    • Business Continuity - Disaster Recovery

      I know about the Zoho CRM backup .zip files, however, this doesn't include any of the infrastructure with like custom fields or custom modules. I am curious on what everyone has in place for a true backup or what your plan is if your Zoho instance were

    • Upload API

      I'm trying to use the Upload API to upload some images and attach them to comments (https://desk.zoho.com/DeskAPIDocument#Uploads#Uploads_Uploadfile) - however I can only ever get a 401 or bad request back. I'm using an OAuth token with the Desk.tickets.ALL

    • Losing description after merging tickets

      Hello, We merge tickets when they are about the same topic from the same client. It happens sometimes. We recently noticed that after the merger only the description from the master ticket is left in a thread. And the slave-ticket description is erased.

    • Option to Empty Entire Mailbox or Folder in Zoho Mail

      Hello Zoho Mail Team, How are you? We would like to request an enhancement to Zoho Mail that would allow administrators and users to quickly clear out entire folders or mailboxes, including shared mailboxes. Current Limitation: At present, Zoho Mail only

    • update linked contacts when update happens in account

      Hi, I have a custom field called Licence in the Accounts module. When someone buys a licence, I’d like to update a custom field in the related Contacts. How can I achieve this? I noticed that workflows triggered on Accounts only allow me to update fields

    • Problem Management Module

      I am looking for a Problem Management module within Zoho Desk. I saw in some training videos that this is available, and some even provided an annual price for it. I want an official confirmation on whether this is indeed available. This is not a particularly

    • Deluge sendmail in Zoho Desk schedule can't send email from a verified email address

      I am trying to add a scheduled action with ZDesk using a Deluge function that sends a weekly email to specific ticket client contacts I've already verified the email address for use in ZDesk, but sendmail won't allow it in its "from:" clause. I've attached

    • Unable to explore desk.zoho.com

      Greetings, I have an account with zoho which already has a survey subscription. I would like to explore desk.zoho.com, but when I visit it while logged in (https://desk.zoho.com/agent?action=CreatePortal) I just get a blank page. I have tried different

    • Offline support for mobile app

      Accessing your files and folders from your mobile devices is now quicker and simpler, thanks to the power of offline support. Whether on an Android or iOS device, you can use the Offline function to save files and folders, so you can review them even

    • Zoho Desk KB article embedded on another site.

      We embed KB articles from Zoho Desk on another site (our application). When opening the article in a new tab, there is no issue, but if we choose lightbox, we are getting an error "To protect your security, help.ourdomain.com will not allow Firefox to

    • Zoho CRM Tracking Google Enhanced Conversions

      Can anyone @Zoho, consultants, or users help me understand if Zoho CRM is going to support Google's Enhanced Conversions? I included some information from Google below about it. We use Google Adwords for our pay per click advertising for lead generation,

    • Transitioning to API Credits in Zoho Desk

      At Zoho Desk, we’re always looking for ways to help keep your business operations running smoothly. This includes empowering teams that rely on APIs for essential integrations, functions and extensions. We’ve reimagined how API usage is measured to give

    • List of packaged components and if they are upgradable

      Hello, In reference to the article Components and Packaging in Zoho Vertical Studio, can you provide an overview of what these are. Can you also please provide a list of of components that are considered Packaged and also whether they are Upgradable?

    • Does Attari Messaging app have Bot option and APIB

      Hi, Does Attari also have Bot and API as we use in WhatsApp??

    • How to add application logo

      I'm creating an application which i do not want it to show my organization logo so i have changed the setting but i cannot find where to upload/select the logo i wish to use for my application. I have seen something online about using Deluge and writing

    • Introducing Keyboard Shortcuts for Zoho CRM

      Dear Customers, We're happy to introduce keyboard shortcuts for Zoho CRM features! Until now, you might have been navigating to modules manually using the mouse, and at times, it could be tedious, especially when you had to search for specific modules

    • Empowered Custom Views: Cross-Module Criteria Now Supported in Zoho CRM

      Hello everyone, We’re excited to introduce cross-module criteria support in custom views! Custom views provide personalized perspectives on your data and that you can save for future use. You can share these views with all users or specific individuals

    • Send Automated WhatsApp Messages and Leverage the Improved WhatsApp Templates

      Greetings, I hope all of you are doing well. We're excited to announce a major upgrade to Bigin's WhatsApp integration that brings more flexibility, interactivity, and automation to your customer messaging. WhatsApp message automation You can now use

    • Verifying Zoho Mail Functionality After Switching DNS from Cloudflare to Hosting Provider

      I initially configured my domain's (https://roblaxmod.com/) email with Zoho Mail while using Cloudflare to manage my DNS records (MX, SPF, etc.). All services were working correctly. Recently, I have removed my site from Cloudflare and switched my domain's

    • Zoho Analytics Regex Support

      When can we expect full regex support in Zoho Analytics SQL such as REGEXP_REPLACE? Sometimes I need to clean the data and using regex functions is the easiest way to achieve this.

    • Change of Blog Author

      Hi, I am creating the blog post on behalf of my colleague. When I publish the post, it is showing my name as author of the post which is not intended and needs to be changed to my colleague's name. How can I change the name of the author in the blogs?? Thanks, Ramanan

    • Show Attachments in the customer portal

      Hi, is it possible to show the Attachments list in the portal for the particular module? Bests.

    • Zoho CRM Formula - Current Time minus Date/Time field

      Hello, I am trying to prevent duplicate emails going to clients when more than 1 deal is being updated. To do this, I would like to create a formula to identify if a date/time field is >= 2 hours ago. Can someone please help me write this formula? Example:

    • Does Zoho Docs have a Line Number function ?

      Hi, when collaborating with coding tasks, I need an online real time share document that shows line numbers. Does Zoho's docs offer this feature ? If yes, how can I show them ? Regards, Frank

    • 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.

    • Feature Request - Insert URL Links in Folders

      I would love to see the ability to create simple URL links with titles in WorkDrive. or perhaps a WorkDrive extension to allow it. Example use case: A team is working on a project and there is project folder in WordDrive. The team uses LucidChart to create

    • Organization Emails in Email History

      How can I make received Org Emails to show up here?

    • how to differentiate if whatsapp comes from certain landing page?

      I create a Zobot in SalesIQ to create a Whatsapp bot to capture the lead. I have 2 landing pages, one is SEO optimized and the other want is optimized for leads comes from Google Ads. I want to know from which landing page this lead came through WhatsApp

    • How to sync from Zoho Projects into an existing Sprint in Zoho Sprints?

      Hi I have managed to integrate Zoho Projects with Zoho Sprints and I can see that the integration works as a project was created in Zoho Sprints. But, what I would like to do is to sync into an existing Zoho Sprints project. Is there a way to make that

    • How to record company set up fees?

      Hi all, We are starting out our company in Australia and would appreciate any help with setting up Books accounts. We paid an accountant to do company registration, TFN, company constitution, etc. I heard these all can be recorded as Incorporation Costs, which is an intangible asset account, and amortised over 5 years. Is this the correct way to do it under the current Australian tax regulations? How and when exactly should I record the initial entry and each year's amortasation in Books? Generally

    • How to create a drop down menu in Zoho Sheets

      I am trying to find out, how do I create a drop down option in Zoho sheet. I tried Data--> Data Validation --> Criteria --> Text  --> Contains. But that is not working, is there any other way to do it.  Thanks in Advance.

    • Show Payment terms in Estimates

      Hi,  we are trying to set up that estimates automatically relates payment terms for the payment terms we introduced on Edit contact (Field Payment terms).  How can it be done? Our aim is to avoid problems on payment terms introduced and do not need to introduce it manually on each client (for the moment we are introducing this information on Terms and Conditions.  Kind Regards, 

    • How can I calculate the physical stock available for sale?

      Hey Zoho Team,  I've tried to calculate the physical stock on hand in various ways - but always receive a mismatch between what's displayed in Zoho Inventory & analytics.  Can you please let me know how the physical stock available for sale is calculated?

    • When dispatched to crew, assigning lead missing

      Hello, For the past two or three weeks, whenever an officer assigns Service Appointment to a team, the lead person is missing from the assigned service list. Therefore, we have to reschedule the SA and then the lead person becomes visible in the assigned

    • open word file in zoho writer desktop version

      "How can I open a Microsoft Word (.doc or .docx) file in Zoho Writer if I only have the file saved on my computer and Zoho Writer doesn't appear as an option when I try 'Open with'? Is there a way to directly open the .doc file in Zoho Writer?"

    • I want to transfer the project created in this account to another account

      Dear Sir I want to transfer the project created in one account to another account

    • Inactive User Auto Response

      We use Zoho One, and we have a couple employees that are no longer with us, but people are still attempting to email them. I'd like an autoresponder to let them no the person is no longer here, and how they can reach us going forward. I saw a similar

    • Weekly Tips : Customize your Compose for a smoother workflow

      You are someone who sends a lot of emails, but half the sections in the composer just get in your way — like fields you never use or sections that clutter the space. You find yourself always hunting for the same few formatting tools, and the layout just

    • Next Page