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!

Previous 'Kaizen' - Calls #API

Next 'Kaizen' - System-defined fields and their default values in Leads #API

Access your files securely from anywhere

Zoho Developer Community

New to Zoho LandingPage?

Access Zoho LandingPage

Zoho LandingPage Resources

New to Zoho Survey?

Access Zoho Survey

Latest Feature Updates

Explore our Pricing & Plans

Zoho Survey Resources

Android Mobile Surveys

Insurvey Blogs

Insight Blogs

Tips & Tricks

New to Zoho CRM Plus?

Deliver unforgettable customer experiences

ACCESS ZOHO CRM PLUS

New to Zoho CRM Plus?

Deliver unforgettable customer experiences

ACCESS ZOHO CRM PLUS

New to Zoho Marketing Plus?

Everything you need to run your marketing

ACCESS ZOHO MARKETING PLUS

New to Zoho Marketing Plus?

Everything you need to run your marketing

ACCESS ZOHO MARKETING PLUS

New to Bigin?

Signup Now

Access Bigin

Latest Feature Updates

Zoho Desk Resources

Desk Community Learning Series
Digest
Functions
Meetups
Kbase
Resources
Glossary
Desk Marketplace
MVP Corner
Word of the Day

Tout forum

France ZUGs

Zoho SalesIQ Resources

Sticky Posts
Kaizen#162 : Add Tags and Open Pre-filled Email Drafts via Client Scripts
Hello everyone! Welcome to another informative Kaizen post. In this post, let us see how to accomplish the following using Client Script. 1. How to auto-tag a record based on field update? 2. How to Open a pre-filled email draft This post will provide
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
Extension Pointers - JS SDK series #4: Managing data from a widget using ZOHO.CRM.HTTP
Handling and managing the data between two applications is a major factor for an efficient business. There are a variety of ways to handle data between Zoho CRM and other third-party applications. You can use deluge CRM tasks, create connectors, use API
Kaizen #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 achieved
Extension pointers for integrating Zoho CRM with Zoho products #8: Upload and manage Zoho Workdrive folders and files from within Zoho CRM
Keeping records on your customers and business prospects is essential for tracking data, conducting follow-ups, and running a business smoothly. When you use two separate applications, and store relevant data in each, checking and tracking data becomes