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

    • Export PDF File Name

      Is it possible to change the default Zoho .pdf naming scheme for inventory items like quotations? Would like to use the the Subject as the default quote name. Is this possible?

    • How to change the from address from 'no reply' for an email template in CRM

      Hi, We have our CRM set up with the from field as sales@XXX. I have just created a series of email templates and sent a test and they are sending from noreply@zoho I have tried searching for how to change the email template but don't have the options

    • Zoho CRM Client Script - SetCriteria in lookup Field

      Hello All One More Zoho CRM Client Script Tips & Trick. Now you can Set the Criteria on Your lookup in zoho CRM, It Comes With a Create Page, Edit Page, and Details Page (Standard). Example:- We have a Room Module that includes Room Name, Status, Campus,

    • Kaizen #71 - Client Script ZDKs for Detail (Canvas) Page

      Hello everyone! Welcome back to another interesting Kaizen post. In this post, we can discuss Client Script ZDKs support for Detail (Canvas) Page. What is Detail (Canvas) Page? A Detail(Canvas) Page allows you to customize the record detail page to your

    • how to use validation rules in subform

      Is it possible to use validation rules for subforms? I tried the following code: entityMap = crmAPIRequest.toMap().get("record"); sum = 0; direct_billing = entityMap.get("direct_billing_details"); response = Map(); for each i in direct_billing { if(i.get("type")

    • Add Custom Reports To Dashboard or Home Tab

      Hi there, I think it would be great to be able to add our custom reports to the Home Tab or Dashboards. Thanks! Chad

    • Rich-text fields in Zoho CRM

      Hello everyone, We're thrilled to announce an important enhancement that will significantly enhance the readability and formatting capabilities of your information: rich text options for multi-line fields. With this update, you can now enjoy a more versatile

    • Create Lead Button in Zoho CRM Dashboard

      Right now to create Leads in the CRM our team is going into the Lead module, selecting the "Create Lead" button, then building out the lead. Is there anyway to add the "Create Lead" button or some sort of short cut to the Zoho CRM Dashboard to cut out

    • Zoho Reports Duplicating Entries

      I have a custom costing tab with a table where we entre invoices. These are under a Heading (PO Subject) and notes added in the form with different line items. In the reports, I have organised the report to group per PO Subject, with the total of the

    • Validation Rule Not Working for Mandatory Field in Zoho Blueprint

      As a Zoho user, we created a validation rule for a specific field. However, we noticed that when we made the same field mandatory within a Blueprint, the validation rule we defined did not work. When we reported this issue to Zoho Support, they stated

    • Notes Issues

      Been having issues with Notes in the CRM. Yesterday it wasn't showing the notes, but it got resolved after a few minutes., Now I have been having a hard time saving notes the whole day. Notes can't be saved by the save button. it's grayed out or not grayed

    • Export from Contacts module to Products module in Zoho CRM

      Good afternoon, I would like to send a number of contact info from the Contacts module into the customized module (tickets to an event) in one operation. I have selected several contacts in the Contact module (people who I have labelled as people I want

    • Zoho Commerce

      Hi, I have zoho one and use Zoho Books. I am very interested in Zoho Commerce , especially with how all is integrated but have a question. I do not want my store to show prices for customers that are not log in. Is there a way to hide the prices if not

    • Can’t receive emailI c

      I have generated a basic for but when I submit it I don’t get a email, I’ve been in the settings and tested me email, all appears correct, can you please help me

    • Data Capture for Historical Activity (Especially One Lead Downloading Variois reports without Overwriting the info)

      Is there a better way in Zoho CRM to capture and archive a lead’s historical activity—specifically whenever they download reports—so that the data is stored without being overwritten?”

    • Client Script - Updating Field Value in Detail Page of a Lead

      Hello, I'm trying to use Client Script To enrich some data of the Lead when one of my User fill the "City" field in the detail page of the Lead. This is my Script: log (value); var response = ZDK.Apps.CRM.Functions.execute("getInfoCitta", { "nomeCitta":

    • I Can't Clone Webinar that I Co-Organize

      How do i get our account admin to give me permission to clone our webinars? I am a co-organizer

    • I want to Make the due date of the project appears automatically

      hello everyone I want to know if the zoho projects app can add automatically the END DATE of the project I added the duration, start after dates of each tasks in the project template & the starting date of the project itself and the end date of it doesn't

    • Introducing Profile Summary: Faster Candidate Insights with Zia

      We’re excited to launch Profile Summary, a powerful new feature in Zoho Recruit that transforms how you review candidate profiles. What used to take minutes of resume scanning can now be assessed in seconds—thanks to Zia. A Quick Example Say you’re hiring

    • How to get the call recording external ID via desk API

      I have enabled phonbridge integration with Zoom Call. I am trying to access the call recording in Zoom by calling Zoom API. I have built a Desk workflow to trigger on a new call, to call a custom function. when calling the API, the response doesn't contain

    • How do you print a refund check to customer?

      Maybe this is a dumb question, but how does anyone print a refund check to a customer? We cant find anywhere to either just print a check and pick a customer, or where to do so from a credit note.

    • Notebook

      I have purchased the monthly pro subscription of Notebook. But it does not support my XP-Pen to write something in it. So it is not useful to me. Hence I am requesting you to help me to discontinue this subscription.

    • Domain Mapping & Image Publishing Issues on Zoho Sites

      Hello, I am facing two issues with my Zoho Sites account: 1. Images not visible after publishing. 2. Domain mapping error: "Domain already exists". I am a paid customer. Please connect me with Live Chat Support or Zoho Assist so I can show my issue

    • Prevent duplicate with custom fields?

      I was wondering something about custom field/custom modules in Zoho Desk. For some reason you can make a custom field mandatory but not unique? For example, if I create a custom module to manage equipment and renewal and make a field serial number no

    • Round robin

      Hi, I'm trying to set up a round robin to automatically distribute tickets between agents in my team but only those tickets that are not otherwise distributed by other workflows or direct assignments. Is that possible and if so which criteria should I

    • "Is Zoho CRM customer" vs "Is linked with Zoho CRM"

      Recently while building a Flow, I was setting up a Decision action following a Zoho Invoice Fetch record action. There were 2 choices that I had not seen as something I could manually action in Zoho Invoice: "Is Zoho CRM customer" and "Is linked with

    • Two currencies

      More and more I am finding that internattional payments' fees are unpredictable. I would like, on my invoices that are in a foreign currency (eg. USD$ or EUR€) for there to be a GBP£ TOTAL display alongside the invoice's currency total. This would make

    • Automatic Matching from Bank Statements / Feeds

      Is it possible to have transactions from a feed or bank statement automatically match when certain criteria are met? My use case, which is pretty broadly applicable, is e-commerce transactions for merchant services accounts (clearing accounts). In these

    • Generate leads from instagram

      hello i have question. If connect instagram using zoho social, it is possible to get lead from instagram? example if someone send me direct message or comment on my post and then they generate to lead

    • Zoho PDF editor has a lot of issues.

      Zoho PDF editor needs a lot of work. It hangs and glitches a lot. Deletes annotations and clearings randomly.

    • Where is the desktop app for Zoho Projects???

      As a project manager, I need a desktop app for the projects I manage. Yes, there's the web app, which is AWESOME for cross browser and platform compatibility... but I need a real desktop app for Projects that allow me to enter offline information where

    • How to Automate Monthly PDF Reports with Filters in Zoho Creator

      Hi everyone, I’m trying to build an automated monthly reporting process in Zoho Creator and would appreciate suggestions or best practices from anyone who has done something similar. What I’m trying to do: I have a form called New_Customer with fields

    • Feedback: Streamlining Note Management in Zoho Notebook

      Dear Team/Support, I would like to share some feedback regarding the note management system that could help improve usability and accessibility for users like myself. Notebook 1 (screenshot attached): Currently, the system does not allow selecting and

    • showing Limit exceeded

      Good afternoon...trust you're good. I've been having issues working with but it's not responding. it's showing Limit exceeded, sorry it seems like too many people are working on the sheet right now please try again later. meanwhile no one is working on

    • 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

    • CRM : Function to add user name to text field

      I have a lookup field in a module that is linked to the CRM users so we can assign a Project Lead to the customer. Sadly Zoho Marketing Automation doesn't sync Lookup fields so I need to extract information from the lookup to text fields: Lookup field

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

    • Next Page