Kaizen #137 - Lead Conversion using Zoho CRM APIs
Leads represent potential sales opportunities sourced from various channels like trade shows, seminars, and marketing campaigns. When a Lead shows promise, you can convert them into Accounts, Contacts, and Deals.
Imagine you have a Lead named Pat Boyle with her email address as pat.boyle@zylker.com. You want to convert her into a Contact, but what if a Contact with the same email already exists? Converting the lead would create a duplicate record, making it harder to track your interactions with the lead.
The Lead Conversion Options API acts as your safety net before Lead Conversion. This API assists in identifying matching records from the Accounts, and Contacts module, ensuring data integrity and preventing duplication during the conversion process.
Step 1 : Identify matching records using Lead Conversion Options API
Consider the following lead generated through a marketing campaign for a software company.
Name : Pat Boyle
Company : Zylker Biotech
Phone : 9844444444
Email : pat.boyle@zylker.com
As the sales team progresses with Pat Boyle and decides to convert her into an Account or a Contact, they must be cautious about potential duplicates in their CRM. For instance, if there is already an Account named Zylker Biotech or a Contact named Pat Boyle, converting the lead to create a new Contact could create duplicate records. The Lead Conversion Options API response provides details of potential matches, including existing Accounts or Contacts, along with matching field details.
Matching Criteria:
The matching process relies on unique fields in the Contacts and Accounts modules. In cases where there are no unique fields in these modules, or when there are no matches found based on the unique fields, the matching is performed based on the Email field in the Contacts module, the Account_Name field in the Accounts module with the Company field of the fields module, or the Lead name with the Contact name.
Here is the order of preference for finding the matching records:
In the presence of unique fields in Contacts and/or Accounts module:
- Contacts module : Unique Field 1 > Unique Field 2 > Email
- Accounts module : Unique Field 1 > Unique Field 2 > Account name
In the absence of unique fields:
- Lead Email checked against the Email fields in the Contacts module.
- Lead Company checked against the account names (Account_Name) in the Accounts module.
- The lead's name checked against the Contacts' names in the Contacts module.
In our scenario, let us assume that the Phone in Contacts module is a unique field.
Request method : GET
Sample Response :
{ "__conversion_options": { "module_preference": { "api_name": "Contacts", "id": "4876876000000002179" }, "Contacts": [ { "Full_Name": "Boyle", "Email": "pat.boyle@zylker.com", "Phone": null, "Locked__s": false, "Account_Name": null, "$editable": true, "id": "4876876000007437017", "$approval_state": "approved", "Data_Processing_Basis": "null" }, { "Full_Name": "Pat Boyle", "Email": null, "Phone": "9844444444", "Locked__s": false, "Account_Name": { "name": "Zylker Biotech", "Locked__s": false, "id": "4876876000007421010" }, "$editable": true, "id": "4876876000007421001", "$approval_state": "approved", "Data_Processing_Basis": "null" } ], "preference_field_matched_value": { "Contacts": [ { "field": { "api_name": "Phone", "id": "4876876000000002503" }, "matched_lead_value": "9844444444" }, { "field": { "api_name": "Email", "id": "4876876000000002497" }, "matched_lead_value": "pat.boyle@zylker.com" } ], "Accounts": [ { "field": { "api_name": "Account_Name", "id": "4876876000000002425" }, "matched_lead_value": "Zylker Biotech" }, { "field": { "api_name": "Phone", "id": "4876876000000002427" }, "matched_lead_value": "9844444444" } ] }, "Accounts": [ { "Layout": { "name": "Standard", "id": "4876876000000091029" }, "Phone": null, "Account_Type": null, "Locked__s": false, "Website": null, "Account_Name": "Zylker Biotech", "$editable": true, "id": "4876876000007421010", "$approval_state": "approved" } ], "modules_with_multiple_layouts": [ // { "api_name": "Accounts", "id": "4876876000000002177" } ] } } |
The preference_field_matched_value object in the response contains the details such as the field and the value of the Contact and Account that matches with the lead. The Contacts and Accounts JSON objects contain the details of the matching records. As per the response, there are two Contacts and one Account with similar details to our Lead.
- A Contact (Pat Boyle) has the same Phone 9844444444 (matching field) as the Lead
- A Contact (Boyle) with the same Email pat.boyle@zylker.com (matching field) as the Lead
- An Account with the same Account_Name Zylker Biotech as the Company of the Lead.
Step 2 : Perform Lead Conversion using Convert Lead API
You can convert a Lead into a Contact, Account, and a Deal using this API. From the Lead conversion options API, we have the matching Contacts and Accounts for the specific deal. Based on the Lead Conversion Options API's response, you can choose to create a new record in the Contacts or Accounts module, or move the Lead record to existing matching records in these modules during Lead Conversion.
During Lead conversion, the Lead's field values are mapped to the corresponding Accounts, Contacts, and Deals records. By default, Zoho CRM automatically maps standard Lead fields to their corresponding fields in Accounts, Contacts, and Deals. The lead mapping tool allows for customization, enabling you to map any additional fields specific to your sales process.
Request method: POST
Input JSON keys:
Input JSON key | Description |
overwrite Boolean, optional | Represents whether to overwrite the account name in the contact if the account name and company in the lead mismatch. Ignored when the Lead has no value for the Company field. true: Overwrites the Contact's Account name with the Lead's company name. false: Leaves the existing Account name unchanged, potentially causing inconsistencies. Default value : false |
notify_lead_owner Boolean, optional | Specifies whether the lead owner should be notified about the lead conversion via email. Default value : false |
notify_new_entity_owner Boolean, optional | Specifies whether the owner of the newly created Contact or Account receives an email notification Default value : false |
move_attachments_to JSON object, optional | Specify the module (Contacts, Deals, or Accounts) where you want to move the Lead's attachments after conversion. Default value : Contacts |
Accounts JSON object, optional | Specify the account with which the lead being converted should be merged. Pass the valid account ID. |
Contacts JSON object, optional | Specify the contact with which the lead being converted should be merged. Pass the valid contact ID. |
assign_to JSON object, optional | The user to which the converted record should be assigned. Pass the valid user ID. |
Deals JSON object, optional | Create a new Deal associated with the converted Lead. Requires details like Deal_Name, Closing_Date, Pipeline, and Stage. You can also assign a Contact_Role by providing the unique contact role ID. |
carry_over_tags JSON object, optional | Carries over tags of the lead to contact, account, and deal. |
Case I : Convert Lead to merge with existing records:
In this case, you can merge the lead record with existing records in the Accounts and/or Contacts module to avoid duplication. You can also create a Deal record providing the necessary details like Deal_Name, Closing_Date, Pipeline, and Stage.
Sample Input:
{ "data": [ { "overwrite": true, "notify_lead_owner": true, "notify_new_entity_owner": true, "Accounts": { "id": "4876876000007421010" }, "Contacts": { "id": "4876876000007421001" }, "Deals": { "Deal_Name": "Zylker Deal", "Closing_Date": "2024-10-20", "Stage": "Negotiation/Review", "Amount": 20000000, "Pipeline": "Standard (Standard)" } } ] } |
Sample Response:
{ "data": [ { "code": "SUCCESS", "details": { "Contacts": { "name": "Pat Boyle", "id": "4876876000007421001" }, "Deals": { "name": "Zylker Deal", "id": "4876876000007459060" }, "Accounts": { "name": "Zylker Biotech", "id": "4876876000007421010" } }, "message": "The record has been converted successfully", "status": "success" } ] } |
Points to Note:
- If the record data doesn't match perfectly with the Lead data, an INVALID_DATA error will be thrown. For example,If you try to merge the Lead with a Contact or Account not found in the Lead Conversion Options API response, you will encounter this error if the data doesn't match.
- During lead conversion, you can transfer the lead to a contact, an account, or both. If you transfer to a contact that is already linked to an account, the lead will automatically be converted and associated with that account as well.
- To successfully merge a Lead record with an existing Contact and Account record, the Contact should be associated with the specified Account. If not, you will get an INVALID_DATA error.
- If the Lead record's Company field is empty, and no account is specified in the JSON input, an account will not be automatically created. However, even if you omit the account in the input JSON, a new account will be created if there is Company name associated with the Lead.
- Unless specified, a deal record will not be created.
Case II : Convert Lead and create new records:
If the Accounts and Contacts records are not specified during the Lead conversion, new Contact and Account records will be created from the converted Lead, mapping the field values according to the field mapping.
Points to Note :
- If there already exists a record in the Accounts or Contacts module with the same value for a unique field as the lead being converted, a DUPLICATE_DATA error will be thrown, with details about the existing record found in the Accounts or Contacts module.
- Unless specified, a deal record will not be created.
Sample Input:
{ "data": [ { "overwrite": true, "notify_lead_owner": true, "notify_new_entity_owner": true } ] } |
Sample Response:
{ "data": [ { "code": "SUCCESS", "details": { "Contacts": { "name": "Pat Boyle", "id": "4876876000007482059" }, "Deals": null, "Accounts": { "name": "Zylker Biotech", "id": "4876876000007482056" } }, "message": "The record has been converted successfully", "status": "success" } ] } |
Important Points :
- If the Contacts module is removed from organize modules, lead conversion is not allowed. In such cases, the Lead Conversion Options API will return a 204 response.
- If the Accounts module is removed from organize modules, the Lead Conversion Options API will not consider Accounts for matching. Only Contacts-related matching options will be listed.
- If the Company field is removed from the Leads module, Account-related matching will be skipped, and only contact-related options will be listed.
- You cannot convert Leads that are locked or have not been approved yet.
- Associating Leads with locked Contacts or Accounts is not possible.
- If the Lead you are trying to convert has already been converted, the ID_ALREADY_CONVERTED error will be thrown.
- To convert leads in bulk, use the Mass Convert Lead API, using which you can convert up to 50 leads in a single API call. The Mass Convert Lead API schedules a conversion job for the specified leads. You can then retrieve the details of the conversion job using the Mass Convert Lead Status API.
We hope that you found this post on Lead Conversion useful. If you have any queries or need further assistance, please feel free to comment below or email us at support@zohocrm.com. We are here to help!
Recommended Reads:
- Get Lead conversion options API
- Convert Lead API
- Mass convert Lead API
- Get status of mass Lead Conversion
- Convert Leads
- FAQs on Lead Management
- Lead Conversion - Field Mapping
- Tips on Lead Conversion Mapping
Previous Post : Zoho CRM Widgets using ReactJS | Kaizen Collection : Home
Join us for our upcoming Zoho CRM Developer Series: Zoho CRM APIs, where you can explore more about Zoho CRM APIs. Register Now!
Access your files securely from anywhere
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
Anu Abraham
Vigneshwaran K
Sticky Posts
Kaizen #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 areKaizen #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 achievedKaizen #142: How to Navigate to Another Page in Zoho CRM using Client Script
Hello everyone! Welcome back to another exciting Kaizen post. In this post, let us see how you can you navigate to different Pages using Client Script. In this Kaizen post, Need to Navigate to different Pages Client Script ZDKs related to navigation A.Kaizen #210 - Answering your Questions | Event Management System using ZDK CLI
Hello Everyone, Welcome back to yet another post in the Kaizen Series! As you already may know, for the Kaizen #200 milestone, we asked for your feedback and many of you suggested topics for us to discuss. We have been writing on these topics over the
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
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?Cliq 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 ? RegardsKnowledgebase SEO
We have a custom-domain mapped help center that is not restricted via login. I have some questions: a) will a robots.txt file still allow us to control indexing? b) do we have the ability to edit the sitemap? c) do category URLs get indexed by searchVLOOKUP FUNCTION PROBLEM
Hello, i have a problem with the VLOOKUP function in my sheet http://public.sheet.zoho.com/public/tonimoreno/indicemasacorporal2 in cell D2. This function doesn't work correctly and always returns the last content of the range. Can you help me?RouteIQ for Zoho FSM
Beste, Zou wel top zijn dat we een RouteIQ hebben voor FSM aangezien we constant moeten zien wat de beste route is voor onze monteurs. Nu moeten we een speciale aparte programma hebben om de beste route te berrekenen voor onze monteurs aangezien de planningExport Tickets from the Help Center
Hello everyone! We are now allowing end users to export tickets directly from the help center. The ticket export allows users to: Filter tickets by Department, Priority, and Account before exporting. Download files from Export History (Setup > Data administrationCRM x WorkDrive: We're rolling out the WorkDrive-powered file storage experience for existing users
Release plan: Gradual rollout to customers without file storage add-ons, in this order: 1. Standalone CRM 2. CRM Plus and Zoho One DCs: All | Editions: All Available now for: - Standalone CRM accounts in Free and Standard editions without file storageZoho Books Sandbox environment
Hello. Is there a free sandbox environment for the developers using Zoho Books API? I am working on the Zoho Books add-on and currently not ready to buy a premium service - maybe later when my add-on will start to bring money. Right now I just need aSuper Admin Logging in as another User
How can a Super Admin login as another user. For example, I have a sales rep that is having issues with their Accounts and I want to view their Zoho Account with out having to do a GTM and sharing screens. Moderation Update (8th Aug 2025): We are workingIs it possible to remove filtering options?
My CRM has a lot of custom fields that should not be used in filters or views. Fields that are automated and exist only to store temporary values that get used in functions. These create a lot of noise in the list of fields to filter. Isn't there anyPrint / Export full Dashboard page
Hello Zoho team, It is currently only possible to print/export one component of a dashboard at a time. Requesting the option to print/export a full dashboard page with all components to a pdf or picture. Doing through the browser doesn't give good results.Function #18: Associate invoice templates automatically based on customer language
For businesses dealing with a diverse linguistic clientele, it becomes crucial to send out invoices in the customer's preferred language to ensure effective communication. This requirement can be handled in Zoho Books by creating invoice templates inChanging field types
Question im a Zoho CRM user and curious, if I change a flied type from single or multi line text to a URL field type will i lose the data in the field or will it be converted to website link automatically. ThanksQuote PDF – Header image stopped rendering suddenly
Hello Zoho Support Team, We are facing an issue with Quote PDF templates in Zoho Books. Previously, images added inside the Quote header HTML were rendering correctly. However, recently the header image is no longer appearing, while header text stillChanging Default PDF Name
Is it possible to change the default name of a PDF? As of right now, all of my quotes are named 'QT_$QuoteNumber' (i,e: 'QT_19803471298374) - would it be possible to change this to: '$CompanyName - $AccountName - $QuoteNumber' for instance?Tip 2: Recursive functions in Deluge: How to dynamically run a function for a specified number of times.
Hi folks, As part of the Zoho Creator - Tips and Tricks series every fortnight, we are back today with a new tip on Recursive functions. Let us first quickly understand what Recursive functions are: A function that calls itself one or more times is known as a Recursive function. That is, you can execute a function to perform a particular action a specific number of times. And, at the end of each iteration, a new output is generated. Recursive functions are commonly used by programmers as it enablesRemoving "Products" as mandatory field from Sales Order creation page
Hello, friends According to our workflow, we should: 1) create Sales Order (Stage "New") 2) call and discuss the Products with a customer (Stage "Communication") 3) add the Products to the Sales Order during the call However, "Products" is mandatory toFunction #48: Manage fixed installment payments using Zoho Books
Hello everyone, and welcome back to our series! Businesses offer installment payment options to their customers, particularly for expensive purchases, to ease the financial burden on them. By breaking down the total cost into smaller, more manageableFunction #1: Convert an accepted Estimate to Sales Order automatically in Zoho Books
As you’re aware, Zoho Books provides a default option to have the estimates automatically converted to invoices once your customer accepts them. Many of you wanted a similar option for sales orders, so here’s a workflow that converts accepted estimatesSpotlight series #6: The Show app for Android TV has a new look!
Hello everyone! We are delighted to introduce our revamped and redesigned Show app for Android TV. Smart TVs are exploding in popularity. Android TV alone has over 110 million active monthly devices. Zoho Show, as part of a constant effort to improveEmployee Appraisal Applicability - Why is Date of Joining Hard-Coded?
In the new (to me, at least) Performance Appraisal Cycle wizard, it's possible to set criteria to determine for whom the appraisal process should apply. This makes sense on its face. However, one MUST use the Date of Joining criterion as a filter. WhyWorkDrive for Excel Add on
Dear Sir/Madam Have installed Workdrive for Microsoft add on But unable to view the same added in ExcelZoho Books integration sync from Zoho CRM does not work
Hi Zoho Community & Zoho Support We just tried to get a sync some products into Zoho Books from CRM using the native sync and we're getting an error: "It looks like some mandatory fields you're trying to map are empty. Please provide valid field namesAppraisals - Order of Previous Reviews Should Be Newest to Oldest
The new Zoho People layout generally does a decent job at providing the necessary information for performing appraisals of employee performance. One example of this is the Previous Reviews section: This information is helpful when conducting a review.Referencing a cell from another sheet
My workbook has multiple sheets. Each sheet has some calcluated totals in certain cells. The front master sheet has a list of everything that is detailed on the other sheets, with the totals. These could change at any time, so the totals need to be references to the other cell's value, not a fixed number. So on the master sheet, I put in =, then go the other sheet and choose the cell and hit Enter. In regular Excel, this works. But in the Zoho sheet, it doesn't work. I have to edit the result byauto close automated alert tickets which are similar
Hello ZOHO Community, we are using ZOHO Desk to process automated monitoring alerts. Scenario: Our monitoring system creates a ticket when a threshold is exceeded, e.g. Subject: Computer 1 – CPU usage 100% – Error A few minutes later, once the issue resolvesPaging through API results. a major gap in your documentation.
There is no way for me. to get all of my data through a single API call. Typically REST APis have mechanisms for paging through API results. But the documentation for the API I am using: https://desk.zoho.com/DeskAPIDocument#Introduction Has no mentionRecurring invoices were generated with old template...
I have recurring invoices setup. Ones generated on 10.20.2025 used the modified template I had used. But for some reason, on the ones created on 11/20/2025, it seems the invoices created reverted to the previous version of the invoice template. Notably,How do people handle using Outlook and Zoho Project calendar at the same time?
We have an ongoing problem in our organisation where we use Zoho Projects to plan all of our projects tasks and that also allows us to look forward using the workload report to see which of our consultants are overstretched etc and which are available.Please, make writer into a content creation tool
I'm tired of relying on Google Docs. I'm actually considering moving to ClickUp, but if Writer were a good content creation tool instead of just a word processor, I would finally be able to move all my development within the Zoho ecosystem, rather thanHow do I associate pricebooks to a customer?
I setup a few pricebooks, that worked fine. But now the only thing I can do with it, when I enter a quote or sales order, I can select which pricebook to use, but I have to do this product by product every time I add one. Is there a way to connect a pricebookWrite-Off multiple invoices and tax calculation
Good evening, I have many invoices which are long overdue and I do not expect them to be paid. I believe I should write them off. I did some tests and I have some questions: - I cannot find a way to write off several invoices together. How can I do that,Leave Report Emailed Weekly
I am wondering if someone knows how to have a report generated either weekly or monthly or both for department heads and ownership of upcoming employee leave. For instance, it would be nice to get an emailed report on Friday for the upcoming week of whoZoho desk desktop application
does zoho desk has a destop applicaion?Creating an extension in Sigma: Zoho CRM isn't selectable as a service
I have 2 Zoho accounts which are part of 2 different workplaces. One workplace is able to select 'Zoho CRM' as a service option when creating a new extension, the other one is not. I'm not sure what the exact differences are between them. What do I needTip #54- Exploring the Files Icon in Zoho Assist- 'Insider Insights'
As we’re already in mid-December, it’s a good time to take a closer look at one of the most useful options in the Zoho Assist remote support dashboard—the Files icon. To get started, log in to Zoho Assist using your credentials. Once you’re in, navigateTip#47: Estimation planner
Sprint planning becomes easier, smoother, more collaborative and more accurate with the Estimation Planner extension. Most work items involve multiple users, and each user's role and effort vary. To provide an unbiased and fair estimation point to thePainfully Slow Zoho mail
Since yesterday Zoho Mail seems to have starting functioning very slowly and having a few bugs. It's slow to open mails, slow to send, slow to change between email accounts. Sometimes clicking on a particular folder (eg Sent folder) stops working andUpcoming update to Google Drive integration in Zoho Creator
Hello everyone, We're writing to inform you about an upcoming update to how Zoho Creator integrates with Google Drive. In Zoho Creator, during actions like importing files to create an app or attaching files to fields, you can choose files directly fromTime Tracking on Iphone doesn't stop
When I start a time tracking session the timer starts as expected. However when I hit stop, the timer remains on that project. The only buttons available are discard and start. Start runs the timer more and discard says it will throw away the data fromNext Page