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 #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 FAQsKaizen #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
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
Can't change form's original name in URL
Hi all, I have been duplicating + editing forms for jobs regarding the same department to maintain formatting + styling. The issue I've not run into is because I've duplicated it from an existing form, the URL doesn't seem to want to update with the newNeed Inactive accounts to be visible in Reports in Zoho Books
I N=need Inactive accounts to be visible in Reports in Zoho Books to do recons of the accounts but when i see the same they are not visible in the Accountant - Account Transactions reportunblock e-mail
please unblock my e-mails info@meatnews.gr and myrtokaterini@meatnews.grAdd Zoho Mail for users who do not need Zoho One
We have licenses for ZOho One for teams that need to use the suite of products that Zoho One offers. We have 8 more people who only need email access and we would like to add just a Zoho Mail. They do not need the Zoho One license. We are currentlyZoho Projects - Q2 Updates | 2025
Hello Users, With this year's second quarter behind us, Zoho Projects is marching towards expanding its usability with a user-centered, more collaborative, customizable, and automated attribute. But before we chart out plans for what’s next, it’s worthZML vs HTML Snippet - which is better?
Are there certain use cases where one is better than the other?Auto CheckOut Based On Shift.
This Deluge script runs on a scheduled basis to automatically set the 'Actual_Check_Out' time for employees who haven't manually checked out. If the current time is past their scheduled 'Shift_End_Time', the script updates the check-out time to matchHow to remove some users in zoho accounts
How to remove some users in Zoho accounts.Customizing Form Questions per Recipient Group in Zoho Campaigns/Forms
Hello everyone, I would like to ask if it’s possible in Zoho Campaigns or Zoho Forms to send out a campaign where the form questions can be customized based on the group of recipients. Use case example: I have prepared 20 questionnaire questions. ForInfinite loop of account verification
Hi I can't do anything on my zoho account. I always get this message Hi Sheriffo Ceesay As a security measure, you need to link your phone number with this account and verify it to proceed further. When ever I supply the details, it displays that the number is associated with another account. I don't have any other account on zoho so this is really annoying.Load PO_Date field (Purchase Order) with current date in Deluge
Hi, I'm not a full time developer, just helping to customize our CRM, in the small company I work for. There must be something wrong with me, because I can't do something so simple as complete a field with the current date in a function using Deluge.Zoho CRM in Microsoft Power Automate Custom Connector
Hi everyone, I’m building a Power Automate flow that integrates Microsoft Bookings with Zoho CRM. The goal is to automatically create a meeting (event) in Zoho CRM whenever a new appointment is booked via Microsoft Bookings. To achieve this, I createdSpell check sucks
Come on guys, it's 2024 and your spell check is completely retarded. You gotta fix it.How to include total km for multiple trips in expense report.
Whenever I create a mileage report it only shows the total dollar amount to be reimbursed. The mileage for each individual trip is included but I also need to see the total distance for all trips in a report? How do I do this?Outgoing blocked: Unusual activity detected.
I just made payment for my Zohomail Today and have been debited so i will like to be Unblocked because this is what it says (Outgoing blocked: Unusual activity detected) Thank you i await your swift responsesZoho One Login Issue - Unable to receive OTP
Hi Support Team, I am experiencing a unique login issue with Zoho One. I am attempting to log in from India using Zoho Login credentials provided by a USA-based client. Their Zoho account is hosted on a US data center. After entering the username andQuestion Regarding Managing Sale Items in Zoho Books
Good day, I was wondering about something. Right now, Zoho Books doesn’t seem to have a way to flag certain items as being on sale. For example, if I want a list of specific items to be on sale from October 1 to October 12, the user would have to exportIn the Zoho Creator Customer Payment form i Have customer field on select of the field Data want to fetch from the invoice from based on the customer name In the Customer Payment form i Have subf
In the Zoho Creator Customer Payment form i Have customer field on select of the field Data want to fetch from the invoice from based on the customer name In the Customer Payment form i Have subform update Invoice , there i have date field,Invoice numberProblem of Import Client Users From CRM and or Expense
I am premium plan user on Projects. I have about 500 customers on Expense and CRM that integrated with each other. According to at below link, I am trying to import clients from CRM, system not allowed to select any customer. If I import from Expense,Unable to see free plan option
Hello Zoho Support Team, I hope you are doing well. I am trying to sign up for Zoho Mail, but I am unable to see the option for the free plan. Could you please guide me on how I can access or activate the free plan? Thank you for your assistance.unblock my zoho mail account. outlines@zoho.com
please unblock my zoho mail account, outlines@zoho.comdomain not verified error
Hi when i try to upload a video from zoho creator widget to zoho work drive iam getting domain not verified error.I don't know what to do .In zoho api console this is my home page url https://creatorapp.zoho.com/ and this is my redirect url:www.google.com.Iamequest to Disassociate Bigin from Zoho One and Migrate to Standalone (Upgrade to Bigin Premier – 3 Seats, Annual)
Dear Zoho One Support Team, I’m writing to request your assistance to disassociate (remove) the Bigin application from our Zoho One organization while preserving all existing Bigin data. After the disconnection is successfully completed, we intend toSMTP email sending problem
Hello, I've sent emails before, but you haven't responded. Please respond. My work is being disrupted. I can't send emails via SMTP. Initially, there were no problems, but now I'm constantly receiving 550 bounce errors. I can't use the service I paidbilling
hi, I am being billed $12/year, and I can't remember why. My User ID is 691273115 Thanks for your help, --Kitty PearlHow to add receipts
How to add receiptsUnable to enable tax checkboxes
Hi Zoho Commerce Support, I'm writing to report an issue I'm having with the tax settings in my Zoho Commerce store. I've created several tax rates under Settings > Taxes, but all of them appear with the checkbox disabled. When I try to enable a checkbox,Does Zoho Learn integrate with Zoho Connect,People,Workdrive,Project,Desk?
Can we propose Zoho LEarn as a centralised Knowledge Portal tool that can get synched with the other Zoho products and serve as a central Knowledge repository?Zoho Commerce - Enable Company Name and Tax Number collection for B2B orders in Global Edition
Please enable Company Name and Tax Details option on checkout settings in Zoho Commerce Global Edition. It is still important to collect Company Name and Tax Number for B2B sales in many countries. My business is based in Ireland (in the EU) and I haveZohoSign and ZohoBooks Integration/Workflow
Hello All, We utilize ZohoSign for signatures on tax eFiles. We utilize Dynamic KBA. Additionally, we use ZohoBooks for invoicing for these services. Is there a way to accomplish the following: Send a copy of the Tax Return, Invoice and eFiles in oneManage monthly tasks with projectsf
Hi All I run a finance and operations team where we need both teams to complete monthly tasks to ensure we hit our deadlines. Can Zoho projects be used for this. There many finance focused tools but we have Zoho one so want to explore Thanks WillZoho Suite is very slow
Since today Zoho is incredibly slow over all applications! What's going on?How can I track which zoho users are actively using Zoho CRM
I have several licenses of Zoho CRM. We now need to add a new user. I could purchase a new license, but before I do, I would like to see if any of our existing users are not actively using the license assigned to them. How can I determine the activityIs anyone else having trouble saving a custom image in their email signature, or is it just me?
When I try to save the image I get an error that says "Operation Failed" I opened a support ticket two weeks ago and received a response that it would be debugged, but it still isn’t workingCombine and hide invoice lines
In quickbooks we are able to create a invoice line that combines and hides invoices lines below. eg. Brochure design $1000 (total of lines below, the client can see this line) Graphic Design $600 (hidden but entered to reporting andOption to Disable Knowledge Base Section in Feedback Widget Popup Hello Zoho Desk Team
Hello Zoho Desk Team, How are you? We are actively using Zoho Desk and would like to make more use of the Feedback Widget. One of the ways we implement it is through the popup option. At the moment, the popup always displays the Knowledge Base section,The Social Wall: August 2025
Hello everyone, As summer ends, Zoho Social is gearing up for some exciting, bigger updates lined up for the months ahead. While those are in the works, we rolled out a few handy feature updates in August to keep your social media management running smoothly.Transaction Locking with the dynamic date
Is it possible to dynamically update dates on transaction locking. We want to lock transaction x days from todayZoho Devops
We have a Zoho one account which we have integrated with an SAS educational product, sold on a subscription model, using webhooks and API calls. We make some use of custom fields and cross module lookups and relationships. We utilize CRM, Books and billingFuel up your sales with the Zoho SalesIQ + Bigin integration
Hi everyone! We’re happy to bring you the all-new Zoho SalesIQ + Bigin integration. With this, every prospect from your website instantly becomes a contact in Bigin, complete with transcripts and follow-up tasks, so you never lose a lead again. Let'sNext Page