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
How to Create a Fixed Sliding Time Window (D-45 to D-15) in Zoho Analytics ?
Hello, I would like to create a report in Zoho Analytics based on a sliding time window between D-45 and D-15, with a fixed snapshot of that specific period. The data displayed should strictly reflect activity recorded between D-45 and D-15 only, withoutHow exactly does "Reply assistance" work in Zoho Desk? What context is sent to the LLM?
Hi, Im trying to better understand the technical behavior of the feature "Reply assistance" in Zoho Desk, and I couldn’t find detailed information in the current documentation. Specifically, I have questions about what data is actually being sent to theHow Does Knowledge Base Search and Article Recommendation Work?
Hello, I would like to understand how the Knowledge Base search engine works. Specifically, does it search based on: The article title only? The full article content? Both, the article and the content? Keywords? Tags? Also, how does the system determineView Answer Bot conversations?
We are trialing Zia and are experimenting with Answer Bot on our knowledge base. So far so good! Management asks me if it is possible to view Answer Bot conversations, the purpose being to look over its shoulder and confirm that it is working as desTrain Zia answer bot on only part of Knowledge Base?
We are trialing Zia answer bot and hope to use it on the knowledge base to help our users find the information they are looking for. I have found how to train Zia on the entirety of our knowledge base. But is there a way to train it on only certain categories🚀 WorkDrive 6.0 (Phase 1): Empowering Teams with Content Intelligence, Automation, Accessibility, and Control
Hello, everyone! WorkDrive continues to evolve from a robust file management solution into an intelligent, secure, and connected content collaboration platform for modern businesses. Our goal remains unchanged: to simplify teamwork, strengthen data security,Zoho Campaigns: An Outstanding Email Marketing Tool
Introducing Zoho Campaigns! A product designed by Zoho, the Zoho Campaigns is made to create, deliver, and manage integrated email campaigns that can help in boosting the sales of a company and its customer base. Zoho Campaigns is actually an email marketingZoho Creator Developer Console | Improved Distribution and Lifecycle Management for apps
Hello everyone, We're excited to introduce new enhancements now in the Zoho Creator Developer Console. These updates strengthen private app distribution through licensing controls and extend environment support across all installed apps, helping teamsAnchor Links in Dashboards
Hello, Our dashboards frequently have multiple sections that would be more easily skipped between using anchor links. Please consider adding an anchor link feature to the text widget? This could be done by adding an anchor link option to the text widget next to the "remove" option (see screenshot). The option would assign an ID to the <div> containing the text widget in the live dashboard. Then, the chosen ID could be linked using a traditional <a href="#link_id"> in the html section of the textZoho CRM for Everyone's NextGen UI Gets an Upgrade
Hello Everyone We've made improvements to Zoho CRM for Everyone's Nextgen UI. These changes are the result of valuable feedback from you where we’ve focused on improving usability, providing wider screen space, and making navigation smoother so everythingSync images with Shopify/Cart
Hello, sync images with shopify or other cart, it cuts out the double work of having to upload to shopify/cart and zoho. ThanksAllow selection of select inactive users in User data fields
Hello, We sometimes need to select a previous employee that has an inactive account in the User data field. For example, when doing database cleanup and indicating actions are done by a certain employee that weren't filled out when they were part of theIs it Possible to Modify Standard Report Urls
Is there a way to permanently modify standard report Urls? Use case: Suppose I have a Products report. Showing list as timeline, calendar, or kanban doesn't make sense. Want to hide that from users by adding #Report:Products?zc_ShowAs=false&zc_Print=falseAssessment Answered - Automation (Related List)
Hello everyone, We have linked a candidate assessment to our job posting. When someone applies, they are required to answer all the assessment questions. However, some candidates submit their applications without completing the questions. In such cases,Smarter holiday planning with yearly-specific Holiday Lists
Hello everyone! Managing holidays and business hours is now easier and more efficient. Holiday Lists now support holidays that fall on different dates every year, while business hours now supports more than one holiday list. This helps businesses manageExternal User onboarding for zoho connect is not really intuitive.
So the external user is sent an invite, which has a button that directs them to login to zoho to view the invite, but if they don't have a zoho account, they cannot access that invite, which seems kinda silly, as there is not real way on for them to createHaving trouble fetching contents of Zoho Connect Feeds using the API, requesting alternative API documentation.
I'm trying to retrieve feed/post data from Zoho Connect using the API but facing challenges with the current documentation. What I've tried: OAuth authentication is working correctly (getting 200 OK responses) Tested multiple endpoints: /pulse/nativeapi/v2/feeds,How to upload file to Connect using API?
Hi there. I looked at the API documentation and nowhere did it mention how to use the API method to upload a file even though it is mentioned that it is possible to be done so. Please help.Select the task view on the board in the Zoho Connect iPhone app
Hello. How do I select the task view on the board in the Zoho Connect iPhone app? The Android app has this functionality.The power of workflows in Zoho Marketing Automation - Video Webinar
In this Zoho Marketing Automation video webinar, our experts walk you through: Why you may want to create marketing workflows How to create marketing workflows Use Zoho CRM data and apply workflows to automate your marketing strategy How workflows canAuto tagging
Some of the articles I enter into Notebook get there when I enter them in Raindrop.io and IFTTT copies the articles in Notebook. When this happens the notes are tagged but instead of useful one word tags with topic the tag pertains to the specific articleConstant refresh required in lots of Zoho tabs
"Hey Zoho, if you can sync my notification bell across 15 tabs using a BroadcastChannel, why can't you send a 'Data Refresh' signal the same way? We don't need a browser reload—we just need the data to sync without us clicking F5 like it's 1999." "PS:What's New in Zoho Billing | January 2026
Excited about the latest enhancements in Zoho Billing? Our January updates bring an intelligent AI assistant, smarter subscription management, and improved tax compliance, saving you time and reducing manual work. Dive into the details below to see howCliq 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 ? RegardsInserting images into Articles or Knowledgebase
Hi, Are there any plans in improving the Knowledgebase text editor so it would allow inserting images through Windows clipboard via copy-paste? Say for example I took a screenshot using the snipping tool in Windows and I'd like to insert that image toLinks not functioning in Zoho mail
Links that are included in emails I receive are not activating. Nothing at all happens when I click on them. I have researched FAQs and this forum to no avail. Any suggestions?Zoho Mail iOS app update: Manage folders and tags
Hello everyone! In the most recent version of the Zoho Mail iOS app, we have brought in support to manage(create, edit and delete) the folders and tags. Create folders Create Tags Edit/ Delete folder In addition to this, we have also brought in supportZoho Social API for generating draft posts from a third-party app ?
Hello everyone, I hope you are all well. I have a question regarding Zoho Social. I am developing an application that generates social media posts, and I would like to be able to incorporate a feature that allows saving these posts as drafts in Zoho Social.[Important announcement] Zoho Writer will mandate DKIM configuration for automation users
Hi all, Effective Dec. 31, 2024, configuring DKIM for From addresses will be mandatory to send emails via Zoho Writer. DKIM configuration allows recipient email servers to identify your emails as valid and not spam. Emails sent from domains without DKIMCreate an Eye-Catching Announcement Widget for Your Help Center
Hello Everyone! In this week’s edition, let’s explore how to keep your customers updated with exciting news in the Help Center. See how ZylkerMobile wowed their customers by bringing updates right to their portal. ZylkerMobile, the renowned brand forUI issue with Organize Tabs
When looking at the organize Tabs window (bellow) you can see that some tabs are grayed out. there is also a "Add Module/Web Tab" button. When looking at this screen it's clear that the grayed out tabs can not be removed from the portal user's screenSuper 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 workingTask list flag Internal/External for all phases
Phases are commonly used in projects to note milestones in the progression of a project, while task lists can be used to group different types of tasks together. It makes sense to be able to define a task list as either internal or external however theZoho CRM Feature Requests - SMS and Emails to Custom Modules & Time Zone Form Field
TLDR: Add Date/Time/Timezone form field, and be able to turn off auto timezone feature. Allow for Zoho Voices CRM SMS Extension to be able to be added to custom modules, and cases. Create a feature that tracks emails by tracking the email chain, ratherOur Review Of Zoho CRM after 60 Days
The purpose of this is to just share with Zoho why I love their product, but ultimately why I could not choose Zoho CRM for our next CRM. About two months ago we begun a CRM exploration process for our financial planning firm, based in Texas. We alreadyLink Purchase Order to Deal
Zoho Books directly syncs with contacts, vendors and products in Zoho CRM including field mapping. Is there any way to associate vendor purchase orders with deals, so that we can calculate our profit margin for each deal with connected sales invoicesExtend the Image Choice Field
Hi, The New Yes/No field is great for what it does, and the Image Choice Field is good but could be better with some functions from the Yes/No field. Take an example, rather than just Yes/No you want Yes/No/Maybe (Or more than 3 choices), but unlike theCRM x WorkDrive: File storage for new CRM signups is now powered by WorkDrive
Availability Editions: All DCs: All Release plan: Released for new signups in all DCs. It will be enabled for existing users in a phased manner in the upcoming months. Help documentation: Documents in Zoho CRM Manage folders in Documents tab Manage filesNew 2026 Application Themes
Love the new themes - shame you can't get a little more granular with the colours, ie 3 different colours so one for the dropdown menu background. Also, I did have our logo above the application name but it appears you can't change logo placement positionZoho Desk: Macro to assign Ticket to self
Hello, We are using macros in Zoho Desk to set some fields and send a response. I would also like to assign the ticket to myself (or whoever applies the macro). I can only set a fixed agent in the macro, so I would have to create one for every agent.Next Page