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

    • 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

    • Zoho Slowness - Workarounds

      Hi all, We've been having intermittent slowness and Zoho just asks for same stuff each time but never fix it. It usually just goes away on it's own after a couple weeks. Given that speed is a very important thing for companies to be able to keep up with

    • Custom Bulk Select Button

      Zoho CRM offers the ability to select multiple records and invoke a Custom Button This functionality is missing from Recruit Currently we can only add buttons in the detail page and list But we cannot select Multiple Records and invoke a function with

    • Zoho CRM still doesn't let you manage timezones (yearly reminder)

      This is something I have asked repeatedly. I'll ask once again. Suppose that you work in France. Next month you have a trip to Guatemala. You call a contact there, close a meeting, record that meeting in CRM. On the phone, your contact said: "meet me

    • Power of Automation :: Smart Ticket Management Between Zoho Desk and Projects

      Hello Everyone, A custom function is a software code that can be used to automate a process and this allows you to automate a notification, call a webhook, or perform logic immediately after a workflow rule is triggered. This feature helps to automate

    • First day of trying FSM in the field.

      What we found. 1. with out a network connection we were unable to start a service call? 2. if you go to an appointment and then want to add an asset it does not seem possible. 3. disappointed not to be able to actually take a payment from within the app

    • BUG - Google Business Buttons - Add a button to GBP Post

      I am experiencing an issue with the "Add a button" feature when creating posts for my Google Business Profile (GBP) through Zoho Social. When I schedule or publish a GBP post and include a call-to-action button with a specific URL, the post itself publishes

    • Rich text Merge field - Not using font specified in HTML

      I have a rich text merge field in a writer template which is creating a table. I have chosen to use this method instead of a repeat region because I need to specify specific cell background colours which change every time the document is created. The

    • Support for Custom Fonts in Zoho Recruit Career Site and Candidate Portal

      Dear Zoho Recruit Team, I hope you're doing well. We would like to request the ability to use custom fonts in the Zoho Recruit Career Site and Candidate Portal. Currently only the default fonts (Roboto, Lato, and Montserrat) are available. While these

    • CC and/or BCC users in email templates

      I would like the ability to automatically assign a CC and BCC "User (company employee)" into email templates. Specifically, I would like to be able to add the "User who owns the client" as a CC automatically on any interview scheduled or candidate submitted

    • Trying to export a report to Excel via a deluge script

      I have this code from other posts but it gives me an error of improper statement, due to missing ; at end of line or incomplete expression. Tried lots of variations to no avail. openUrl(https://creatorapp.zoho.com/<username>/<app name>/XLSX/#Report:<reportname>,"same

    • Need help to create a attach file api

      https://www.zoho.com/crm/developer/docs/api/v8/upload-attachment.html Please help me to create it... It's not working for while. Do you have some example?

    • Export view via deluge.

      Hi, Is it possible to export a view (as a spreadsheet) via deluge? I would like to be able to export a view as a spreadsheet when a user clicks a button. Thanks     

    • how to add subform over sigma in the CRM

      my new module don't have any subform available any way to add this from sigma or from the crm

    • Outdated state in mexico

      Hello Zoho team, the drop down to add the state for customers, when they introduce their state in mexico has a city named “Distrito Federal” that name changed many years ago to “ciudad de mexico”. could you please update this so my clients can find the

    • Support new line in CRM Multiline text field display in Zoho Deluge

      Hi brainstrust, We have a Zoho CRM field which is a Muti Line (Small) field. It has data in it that has a carriage return after each line: When I pull that data in via Deluge, it displays as: I'm hoping a way I can change it from: Freehand : ENABLED Chenille

    • Possible to generate/download Quote PDF using REST API?

      See title. Is there any way after a quote has been created to export to a PDF using a specified template and then download it? Seems like something that should be doable. Is this not supported in the API v2.0?

    • Creating an invoice to be paid in two installments?

      Hi there, I own a small Photographic Services business and have not been able to find a way to fit my billing system into Zoho, or any other Accounting software. The way my payments work is: 1. Customer pays 50% of total price of service to secure their

    • Bug in allowing the user to buy out of stock items

      Hi i want to allow the user to buy out of stock items, according to the commerce documentation if i disable Restrict "Out of stock" purchases it will, but it doesnt work, so i want to know if it had any relation with zoho inventory, and if theres any

    • Zoho CRM Calendar | Custom Buttons

      I'm working with my sales team to make our scheduling process easier for our team. We primary rely on Zoho CRM calendar to organize our events for our sales team. I was wondering if there is a way to add custom button in the Calendar view on events/meeting

    • Replace Lookup fields ID value with their actual name and adding inormation from subforms

      Hi everyone,  I wanted to see if someone smarter than me has managed to find any solutions to two problems we have. I will explain both below.  To start we are syncing data from Zoho CRM to Zoho Analytics and I will use the Sales Order module when giving

    • Can a Zoho Sites page be embedded into another website (outside Zoho)

      Hi All, We have a request from a client - they'd like to take one of our information pages created in Zoho Sites and embed it into their own website? I was told through an email with Zoho that this was possible >>Thank you for your patience regarding

    • Bug in allowing the user to buy out of stock items

      Hi i want to allow the user to buy out of stock items, according to the commerce documentation if i disable Restrict "Out of stock" purchases it will, but it doesnt work, so i want to know if it had any relation with zoho inventory, and if theres any

    • Transition Criteria Appearing on Blueprint Transitions

      On Monday, Sept. 8th, the Transition criteria started appearing on our Blueprints when users hover over a Transition button. See image. We contacted Zoho support because it's confusing our users (there's really no reason for them to see it), but we haven't

    • Zoho CRM Sales Targets for Individual Salespeople

      Our organistion has salespeople that are allocated to different regions and have different annual sales targets as a result. I am building an CRM analytics dashboard for the sales team, which will display a target meter for the logged in salesperson.

    • All new Address Field in Zoho CRM: maintain structured and accurate address inputs

      The address field will be available exclusively for IN DC users. We'll keep you updated on the DC-specific rollout soon. It's currently available for all new sign-ups and for existing Zoho CRM orgs which are in the Professional edition. Managing addresses

    • Transfer all Related Data to new Account Owner

      Currently when I change the account Owner I only see the option to change only the open deals But I want the new account owner to take over all the related modules and all the deal stages Is it not possible right now? Am I missing something? Do I really

    • Can i connect 2 instagram accounts to 1 brand?

      Can i connect 2 instagram accounts to 1 brand? Or Do i need to create 2 brands for that? also under what subscription package will this apply?

    • How to Calculate MTTR (Mean Time to Resolve)

      We want to calculate MTTR (Mean Time to Resolve) in our Zoho Analytics report under Tickets. Currently, we are using the following fields: Ticket ID Ticket Created Time Ticket Closed Time Ticket On Hold Time We are planning to calculate MTTR (in days)

    • How to export project tasks, including the comments

      Hi, how can I export the project tasks, whereby I can also see the comments associated to a specific task? The use-case is that often we use comments to discuss or update a task related ideas. I would like to export the tasks, where we can also see the

    • How to Install Zoho Workdrive Desktop Sync for Ubuntu?

      Hi. I am newbie to Linux / Ubuntu. I downloaded a tar.gz file from Workdrive for installing the Workdrive Desktop Sync tool. Can someone give me step by step guide on how to install this on Ubuntu? I am using Ubuntu 19.04. Regards Senthil

    • Introducing Version-3 APIs - Explore New APIs & Enhancements

      Happy to announce the release of Version 3 (V3) APIs with an easy to use interface, new APIs, and more examples to help you understand and access the APIs better. V3 APIs can be accessed through our new link, where you can explore our complete documentation,

    • Does Zoho Sheet Supports https://n8n.io ?

      Does Zoho Sheet Supports https://n8n.io ? If not, can we take this as an idea and deploy in future please? Thanks

    • Next Page