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
Can't login to Zoho mail
I'm logged into Zoho but when I try to go in zoho mail I get: Invalid request! The input passed is invalid or the URL is invoked without valid parameters. Please check your input and try again. I just set up my mx records and stuff with namecheap a fewZoho IP blocked by SpamCop
Hi, Many of my emails are blocked and I receive this: INVALID_ADDRESS, ERROR_CODE :550, ERROR_CODE :spamcop.mimecast.org Blocked - see https://www.spamcop.net/bl.shtml?136.143.188.51. - https://community.mimecast.com/docs/DOC-1369#550 [DGwIYPPSOfWICan I execute two 'functions' when completing a mail merge from CRM?
Hi, I have set up a mail merge from CRM Deals to a template. I want a copy of this to be saved in Workdrive, and then a copy also saved back into the deal record from which the merge occurred. I can do both independent of each other, and managed to getDifferences between Zoho Books and Zoho Billing
Without a long drawn out process to compare these. If you were looking at these Books and Billing, what made you opt for one and not the other. ThanksAuto-sync field of lookup value
This feature has been requested many times in the discussion Field of Lookup Announcement and this post aims to track it separately. At the moment the value of a 'field of lookup' is a snapshot but once the parent lookup field is updated the values diverge.Custom validation in CRM schema
Validation rules in CRM layouts work nicely, good docs by @Kiran Karthik P https://help.zoho.com/portal/en/kb/crm/customize-crm-account/validation-rules/articles/create-validation-rules I'd prefer validating data input 'closer to the schema'No Ability to Rename Record Template PDFs in SendMail Task
As highlighted previously in this post, we still have to deal with the limitation of not being able to rename a record template when sent as a PDF using the SendMail Task. This creates unnecessary complexity for what should be a simple operation, andServer error when trying to Data > Sort > Custom Sort
Been using Data > Sort > Custom Sort for a while, now it has suddenly stopped working. When selecting the same data range and trying to execute, I get "Sorry! There was a problem saving your last edit. Please try again."To Assign a genrated pdf to a file upload field using delug
content = "<html><body>HTML Content on page One <div style='page-break-after:always'></div> HTML Content on page Two </body></html>"; file = zoho.file.convertToPDF(content); file.setFileName("Name of the file"); <variableName> = <FormLinkName>[ID == input.ID];TArgets To Accounts (Modules)
How can i set sale target to Customers (Accounts Module)Breaking barriers with multilingual WhatsApp templates in IM
Ever wondered what it feels like to be greeted in your own language by a brand you love? A “Welcome!” feels nice, but a “¡Bienvenido!” or “स्वागत है!” feels personal. In today’s global world, conversations often need to cross both time zones and crossSuper 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 workingHow to share private Opportunities with whole org at an account level
Opportunities are currently set to private, so our sales team only sees their own opportunities, along with their manager and upper leadership. The need is the ability for the rest of the Org to see the opportunities at an account level, not within theNew in Smart Prompt: Record Assistant for contextual assistance, and support for new AI models
Smart Prompt helps teams stay informed and move faster by providing relevant suggestions where work happens in CRM. With this update, Smart Prompt becomes more adaptable to your organization’s AI preferences. You can now choose which Large Language ModelSubform edits don't appear in parent record timeline?
Is it possible to have subform edits (like add row/delete row) appear in the Timeline for parent records? A user can edit a record, only edit the subform, and it doesn't appear in the timeline. Is there a workaround or way that we can show when a userProblema Verificacion con proveedor NIC.AR
No puedo realizar la verificación del correo, he seguido los pasos indicados y configurado los MX. Y no puedo verificar el correo. He leido en el foro que otros han tenido el mismo problema. Alguno pudo solucionarlo?How to remove some users in zoho accounts
How to remove some users in Zoho accounts.Reupload and rename from one field to another field (file upload)
Hi Everyone, Sorry, i have question to use invoke url for rename and reupload attachments file to another field. Tested on development mode. Zoho C6. Refer to https://www.zoho.com/creator/help/api/v2/upload-file.html look my error notification. Does anyoneUnified Inbox for all, including fetched mails
I fetch mails from different third-parties mailboxes. But I need to switch mailbox too see fetched mails. It's strange. All mailboxes have one shared disk space for own mail and fetched mail, but why do we need to switch mailbox (on the left bottom) toWhatsapp Limitation Questions
Good day, I would like to find out about the functionality or possibility of all the below points within the Zoho/WhatsApp integration. Will WhatsApp buttons ever be possible in the future? Will WhatsApp Re-directs to different users be possible basedUsers Not Automatically Being Added To WorkDrive Team
I have already created a ticket for this issue, but the support team doesn't seem to understand what's happening. Our organization started with a trial of Zoho Workplace around November 10, 2025. I created 10 users, including myself. I sent out the invites,Synchronization between Gmail and Zoho Mail
Hello! I am using Zoho Mail within the Zoho One platform. I have completed the basic setup and added all the required DNS records with our domain provider. Our goal is to set up two-way synchronization between our current Gmail inbox and Zoho Mail, butIMAP login problem
I have my domain hosted with zoho @wilson.ie I have added a new user and have enabled IMAP access to this user account The user can login to zoho mail on the web. When we enter the server settings into Outlook as per below, Outlook cannot login to theContact data removes Account data when creating a quote
Hi, Our customer has address fields in their quote layout which should be the address of the Account. They prefill the information, adding the account name - the address data is populated as per what is in the account - great. However when they then addChanges to subform in Zoho CRM Portal Timeline History Unavailable
Hi Support Team, We have noticed a feature limitation in the Zoho CRM portal. We created a portal for our vendors to edit records directly, but when vendors make updates, the Modified Time and Date fields are not being updated. Additionally, these updatesThis mobile number has been marked spam. Please contact support.
Hi Support, Can you tell me why number was marked as spam. I have having difficult to add my number as you keep requesting i must use it. My number is +63....163 Or is Zoho company excluding Philippines from their services?Zoho CRM Portal Field Level Permission Issue
Hi Support Team, I am using the Zoho CRM Portal and configuring field-level editing permissions. However, we are unable to restrict portal users from editing certain fields. We have created a portal and provided View and Edit (Shared Only) access forFunction #11: Apply unused credits automatically to invoices
Today, we bring you a custom function that automatically applies unused credits from excess payments, credit notes, and retainer payments to an invoice when it is created. Prerequisites: Create a Connection named "zbooks" to successfully execute the function.Edit Contact Roles in the Potentials Mod
New to ZOHO so I need some help. I work the same people on different projects concurrency. Their contact info remains the same but their role changes from project to project. In the Potential Mod you can pick contacts and assign a Role to them. I know how to edit the roles. What I want to do is add some fields. Specifically I want to add the following "Expectation" "Requirements" and "Communication "Requirements." This will allow me to look at a Potential and see information associated with thisDuplicating report but custom layout does not
Dear Zoho Creator, I need to duplicate a report into 10 copies, but unfortunately the custom layout (detail view) doesn’t copy along with it. I tried exporting and importing the custom layout, but the field mappings are incorrect. I believe everyone areCredit Card Readers?
We would like to use our commerce website at conferences (and eventually in store) to swipe credit cards to pay for orders. How would we accomplish this? Does Zoho have anything available for a developer write code to integrate something like Stripe TerminalAI generated meeting notes associated to Account or Deal
As our organization works to improve efficiency we are looking for a solution to leverage AI to generate meeting notes and then add those notes to a CRM record such as an Account or Deal. I see Zoho has a Notebook AI offering that talks about the abilityStock count by bin location
Is there a configuration to make a stock count by bin or area and not by product. these is useful to manage count by area RegardsAdd Prebuilt "Partner Finder" Template with Native Zoho CRM Integration in Zoho Sites To: Zoho Sites Product Team
Hi Zoho Team, We hope you're doing well. We would like to request a prebuilt "Partner Finder" template for Zoho Sites, modeled after your excellent implementation here: 🔗 https://www.zoho.com/partners/find-partner-results.html ✅ Use Case: Our organizationHow Do I Refund a Customer Directly to Their Credit Card?
Hi, I use books to auto-charge my customers credit card. But when I create a credit note there doesn't seem to be a way to directly refund the amount back to their credit card. Is the only way to refund a credit note by doing it "offline" - or manually-Can we generate APK and IOS app?
Dears, I want to know the availability to develop the app on zoho and after that .. generate the APK or IOS app and after that I added them to play store or IOS store.. Is it possible to do this .. I want not to use zoho app or let my customers use it. thanksLimitation with Dynamic Email Attachment Capture
I've discovered a flaw in how Zoho Creator handles email attachments when using the Email-to-Form feature, and I'm hoping the Zoho team can address this in a future update. The Issue According to the official documentation, capturing email attachmentsZoho Learn Course Completion Notifications/Triggers/API
Zoho Learn works great and will suit our course creation needs, but it appears to be lacking a bit when it comes to integration with other Zoho services (creator etc.) when it comes to course completion. 1) Is there an API or Zoho Flow trigger for whenSorting a list of record acquired from the zoho.crm.searchRecords function.
This is something for which I'm trying to figure out a straightforward way to do. The searchRecords does a great job fetching me the records that I want. However, in some cases, where it returns multiple records, I want it to sort the returned list by date of creation of that record, so that when I do records.get(0), I get the most recent record. As an example, here's my sample pseudo code: records = zoho.crm.searchRecords("Clients", "Office_Number:equals:123456"); Now the "records" list above containsEnhanced Recording Permission Controls for Zoho Cliq Meetings (Similar to Zoom)
Hello Zoho Cliq Team, We hope you are doing well. We would like to request an enhancement to the recording permission functionality in Zoho Cliq Meetings. Current Limitation: in Zoho Cliq Only hosts and co-hosts can record a meeting. Participants cannotNext Page