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
Centralize Knowledge. Transform Learning.
All-in-one knowledge management and training platform for your employees and customers.
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 #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.Kaizen #226: Using ZRC in Client Script
Hello everyone! Welcome to another week of Kaizen. In today's post, lets see what is ZRC (Zoho Request Client) and how we can use ZRC methods in Client Script to get inputs from a Salesperson and update the Lead status with a single button click. In thisKaizen #222 - Client Script Support for Notes Related List
Hello everyone! Welcome to another week of Kaizen. The final Kaizen post of the year 2025 is here! With the new Client Script support for the Notes Related List, you can validate, enrich, and manage notes across modules. In this post, we’ll explore howKaizen #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 are
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
Is this a SCAM email or is it really Zoho?
L.S. I received the following message. Is this from Zoho? I have had a Zoho One account for many years and my website has been online for years. If it is a scam, I think you should know about it.Is it possible to use HTML formatting in SMS messages sent from Zoho?
Hi everyone, I have a question regarding sending SMS from Zoho When we send emails from Zoho, we can include HTML code to format the message (like adding links, styling, etc.). Is it possible to do something similar when sending SMS messages through Zohoan issue in Zoho CRM where the workflow rule is not triggering
H I’m currently facing an issue in Zoho CRM where the workflow rule is not triggering when a new lead is created through a webform. I’ve double-checked the criteria and field updates, everything seems fine but it still doesn’t fire. Has anyone faced thisOption in pipeline deal to select which hotel or branch or store if client has more than one local store
Hi, I would like to know if there is an option in the deal pipeline to select which hotel, branch, or store a deal is related to—if the company has more than one location. For example, I have a client that owns several hotels under the same company, andEmail Insights included in Bigin emals are marked as SPAM everywhere
Today I noticed that email recipients who use Office 365 never receive emails sent from Bigin. Further examination showed that all Email Insights links in email headers are marked as spam/phishing by Office 365. Example screen included. The problem isEmail Parser Not Extracting Fields Correctly with Certain Label Formats
I’ve been testing the Email Parser functionality in Zoho CRM to automatically extract data from incoming emails and map it to CRM fields. During testing, I noticed that parsing sometimes fails when the email contains field labels formatted like this:How do I import Connected Records for a Deal?
Can you point me to an example of the CSV file that would add related records to an existing CRM Deal? I imported a Deal, then tried importing a connected record using a unique ID that references the Deal ID, but it doesn't attach it to the Deal recFile Upload Field in Zoho Forms Not Updating Existing File in Zoho CRM
Hi everyone, I’m trying to understand the behavior of a file upload field mapped from Zoho Forms to Zoho CRM. Scenario There is a File Upload field in a Zoho CRM module. A Zoho Form also has a File Upload field, which is mapped to that CRM field. WhenZoho Training
Greetings! I am trainer. My focus area is Project Management and MS Project. I have used Zoho CRM to a good extent. Though, I was interested in using ZOHO projects, as there were no live projects, I could not take it up for studies. Recently a clientDetailed list of scoring rules in Zoho CRM
Good morning Zoho community, warm greetings The reason for my message today is that I have a problem with my CRM, which I will explain below: Our organization has scoring rules designed to rate our potential customers or leads in the application basedHow to create a summary document from Projects details
Hi, Our team is creating many projects inside Zoho Project. When closing a project, they write a summary document containing data from the projects it-self (understand project budget, customers, etc...), and editable (ie the document is either a WriterRequest to Recover Deleted Task List – Project ID: RIV-MOD-10722
Hi Zoho Team, I hope this message finds you well. My Zoho task list associated with Project ID: RIV-MOD-10722 appears to have been deleted. When I clicked on the task link from the email notification, I received the following message: "Task has been deletedHost in US Data Centre
I humble apply to be registered on US Data centreconvert the project to templet
i have some deployment ME product for different customer , i need to create a fixed template for use it rather then keeping creating this template every timeBest practices for managing Project Charters, Business Case and RAID logs within Zoho?
Hello everyone, I’m currently refining our PMO setup within Zoho Projects and I’m curious how others are handling high-level governance documentation. We’ve been using the standardized Project Charter, Business Case and RAID frameworks from projectmanagertemplate.comResource Management System built using Zoho CRM, Creator, Projects, and People:
In a Resource Management System built using Zoho CRM, Creator, Projects, and People: CRM Deal Closed → Creator Allocation Engine → Zoho Projects Task Assignment What is the recommended architecture to handle dynamic reassignment when: an employee goesDynamic Remaining Quantity in Lookup During Allocation
Hi everyone, From what I understand in Zoho Creator, lookup fields only display the stored value from the source record and do not dynamically update while a form is being filled. Because of this, showing a real-time updated remaining quantity insideconnect zoho creator with google drive
Hello everyone, I need to connect to a folder drive. The idea, is that google drive loads a text document with some data, I must read that text document to be able to autofill a form that I have in zoho creator with that data. I also attach PDFs and placeAbility to Attach Record-Specific Files Automatically in Workflow Email Templates
Currently in Zoho CRM, email templates allow attachments to be added, but these attachments are static and remain the same for every recipient. There is no straightforward option to automatically attach a file that is stored within the specific CRM recordUploaded files are not included when using "Include user submitted data" in Email Notification
In Send Email notification workflow in Zoho Creator, there is an option called "Include user submitted data" which allows the email to contain all the form submission details. However, when this option is enabled, files or images uploaded through Filekanban view for client portal
Are kanban views an option for client portals? Access to Kanban views in the client portals would solve some mobile-compliant issues I have with the UI. Kanban functions very nicely on mobile and would be a super asset for my clients and vendors as theyCredit Card Pre-Authorization with later Capture/Settlement
We really enjoy the convenience of being able to pay off a customer's invoice using our Auth.Net integration with Zoho Books. Unfortunately, we can only take advantage of this feature with a small percentage of our customers as it leaves a gaping holeZoho Cliq not working on airplanes
Hi, My team and I have been having this constant issue of cliq not working when connected to an airplane's wifi. Is there a reason for this? We have tried on different Airlines and it doesn't work on any of them. We need assistance here since we are constantlyZoho Sign 2025–2026: What's new and what's next
Hello! Every year at Zoho Sign, we work hard to make document signing and agreement execution easy for all users. This year we sat down with our head of product, Mr. Subramanian Thayumanasamy, to discuss what we delivered in 2025 and our goals for 2026.Work Orders / Bundle Requests
Zoho Inventory needs a work order / bundle request system. This record would be analogous to a purchase order in the purchasing workflow or a sales order in the sales cycle. It would be non-journaling, but it would reserve the appropriate inventory ofIzettle or Sumup Integration for Zoho Books.
The Stripe & Square clearing works great in Zoho Books. Any further integrations planned in the future for Izettle or Sumup? These card processors are very common for taking payments with a card reader.Train Zoho Answer Bot Based on Customer
Hi all, Is it currently possible to mark Help Centre articles to a specific customer, and restrict the answer bot to only use relevant information if it is either marked as "General", or tagged for the specific customer in question? We currently haveTrying to access records in a custom module in Zoho Desk and not having luck
I've built a custom module in Zoho Desk and am using a custom function to query the records in the module and I'm not having any luck. The only way I have found to retreive a record is by getting it by its recordID (the long zoho assigned one). The functionComposite items inside of composite items; bill of materials needed
Hi Zoho and Everyone, I am evaluating whether Zoho Inventory will work for my small business. I grow and harvest herbs and spices but also get from wholesalers. I use all these items to make herbal teas, but also sell them as individual items on my Shopify store and Etsy. I discovered the composite item bundling and am wondering if I could get some assistance since there is no bill of materials: Our herbal company's best selling tea is a sleepytime tea. Sleepytime Tea can be purchased in three weightsZOHO Books Smart Accounting Software for Travel Agency
Dear Travel partner, Contact for Travel Agency Accounting Setup & Training Vansh Travel (ZOHO Books Authorised partner) Email: info@vanshtravel.com Mo: +91 98984 95155 Please find PDF452 Mailbox delivery restricted by policy error
We have been testing Zoho desk for about a week now and have been forwarding emails in via an Exchange Online Mail flow rule without issue until yesterday. Suddenly yesterday morning we started getting the vast majority of the emails stuck in PendingSend Email reply on behalf of Agent
Hi, When using the send email reply via the API I can set the reply on behalf of the customer by using impersonatedUserId in the header of the API call. Is there a way to do this for Agents too? I need to be able to send an email reply on behalf of anSharing Tickets to a team within a department
Hi there, We have a need for one department to be able to share tickets to a specific team within a department, I'm wondering if this is possible? All the shared tickets are going into the 'Shared Tickets' view for the whole department but is there aRemoving To or CC Addresses from Desk Ticket
I was hoping i could find a way to remove unnecessary email addresses from tickets submitted via email. For example, a customer may email the support address AND others who are in the helpdesk notification group, in either the TO or CC address. This resultsDo not use isnull()
Does not always return booleans. Can also return null. Never use this function. Just use var==null instead.Organization wide Account and Contacts Visibility/Sharing Capabilities?
Has anyone figured out a way to make visibility or sharing of Accounts and Contacts to be available across the entire organization without having to have every individual user edit their Sharing permissions? For our sales folks they need to be able toIs there a way to configure dark mode for Campaigns emails that go out to customers?
I've found a lot of information on how to configure dark mode for my (The user) personal Zoho workspace and email, but is there any way to edit dark mode settings on emails that we send out to customers via campaigns? We sent out a test email the otherWhen Does WorkDrive integrate with Books?
When Does WorkDrive integrate with Books?FSM integration with Books
Hi, I have spent a few months working with FSM and have come across a critical gap in the functionality, which I find almost shocking....either that, or I am an idiot. The lack of bi-directional sync between Books and FSM on Sales Orders/ Work OrdersHow to close an estimate ?
Hello, I have created estimates, and converted them to invoices to get 50% payment. Now I have 2 cases where the estimate stills shows status partially invoiced, however: 1. for one of them, project stopped half way, so the remaining part will never beNext Page