Kaizen #137 - Lead Conversion using Zoho CRM APIs

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

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"
        },
        "Cont​acts": [
            {
                "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:



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











                            Zoho Developer Community





                                                  • Desk Community Learning Series


                                                  • Digest


                                                  • Functions


                                                  • Meetups


                                                  • Kbase


                                                  • Resources


                                                  • Glossary


                                                  • Desk Marketplace


                                                  • MVP Corner


                                                  • Word of the Day


                                                  • Ask the Experts





                                                            Manage your brands on social media



                                                                  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

                                                                                      • CRM Community Learning Series

                                                                                        CRM Community Learning Series


                                                                                      • Kaizen

                                                                                        Kaizen

                                                                                      • Functions

                                                                                        Functions

                                                                                      • Meetups

                                                                                        Meetups

                                                                                      • Kbase

                                                                                        Kbase

                                                                                      • Resources

                                                                                        Resources

                                                                                      • Digest

                                                                                        Digest

                                                                                      • CRM Marketplace

                                                                                        CRM Marketplace

                                                                                      • MVP Corner

                                                                                        MVP Corner







                                                                                          Design. Discuss. Deliver.

                                                                                          Create visually engaging stories with Zoho Show.

                                                                                          Get Started Now


                                                                                            Zoho Show Resources


                                                                                              Zoho Writer Writer

                                                                                              Get Started. Write Away!

                                                                                              Writer is a powerful online word processor, designed for collaborative work.

                                                                                                Zoho CRM コンテンツ




                                                                                                  Nederlandse Hulpbronnen


                                                                                                      ご検討中の方




                                                                                                            • Recent Topics

                                                                                                            • Market cap

                                                                                                              Market cap formula?? Kaise nikale
                                                                                                            • Zoho Sheet for Desktop

                                                                                                              Does Zoho plans to develop a Desktop version of Sheet that installs on the computer like was done with Writer?
                                                                                                            • Option to Customize Career Site URL Without “/jobs/Careers”

                                                                                                              Dear Zoho Recruit Team, I hope you are doing well. We would like to request an enhancement to the Career Site URL structure in Zoho Recruit. In the old version of the career site, our URL was simply: 👉 https://jobs.domain.com However, after moving to
                                                                                                            • SOME FEATURES ARE NOT IN THE ZOHO SHEET IN COMPARISION TO ZOHO SHEET

                                                                                                              TO ZOHO sir/maam with due to respect i want to say that i am using ZOHO tool which is spreadsheet i want to say that some features are not there in zoho sheet as comparison to MS EXCEL like advance filter and other Features which should be there in ZOHO
                                                                                                            • Auto-upload Creator Files to WorkDrive

                                                                                                              Hi everyone, I’m working on a workflow that uploads files from Zoho Creator to specific subfolders in Zoho WorkDrive, as illustrated in the attached diagram. My Creator application form has two multi-file upload fields, and I want—on successful form submission—to
                                                                                                            • Google enhanced conversions not working

                                                                                                              Hi guys, I've connected Zoho CRM through Google Ads interface with the goal to setup the enhanced conversion tracking in Google Ads. I have to Zoho related conversion goals which you can see in the images below: For the conversion goal above I've setup
                                                                                                            • Need Help to setup plugs along with codeless bot buidler. To send sms OTPs to users via Zoho Voice and to verify it

                                                                                                              Need Help to setup plugs along with codeless bot buidler. To send sms OTPs to users via Zoho Voice and to verify it. I get leads from our website and we need to make sure those are not junk. So we are using proactive chat bot and we need mobile OTPs to
                                                                                                            • Direct Integration Between Zoho Cliq Meetings and Google Calendar

                                                                                                              Dear Zoho Team, We’d like to submit the following feature request based on our current use case and the challenges we’re facing: 🎯 Feature Request: Enable meetings scheduled in Zoho Cliq to be automatically added to the host's Google Calendar, not just
                                                                                                            • Cliq iOS can't see shared screen

                                                                                                              Hello, I had this morning a video call with a colleague. She is using Cliq Desktop MacOS and wanted to share her screen with me. I'm on iPad. I noticed, while she shared her screen, I could only see her video, but not the shared screen... Does Cliq iOS is able to display shared screen, or is it somewhere else to be found ? Regards
                                                                                                            • Zoho Desk - Cannot Invite or Register New User

                                                                                                              Hi who may concern, we encountered a problem that we cannot invite user or the visitor cannot register for a user at all through our help center portal, with the snapshot shown as below and the attachement. It always pops up that "Sorry, Unable to process
                                                                                                            • Zoho sheet

                                                                                                              Unable to share zoho sheet with anyone on internet with editer option only view option is show
                                                                                                            • Allocating inventory to specific SO's

                                                                                                              Is there a way that allocate inventory to a specific sales order? For example, let's say we have 90 items in stock. Customer 1 orders 100 items. This allocates all 90 items to their order, and they have a back order for the remaining 10 items which could
                                                                                                            • Mail and OS

                                                                                                              Jai Hind! Zoho is doing good by creating good software (made in india) on par with other tech giants. 🥰 Suggestion: 1. Whenever we sign up on zoho mail its asking for other mail id. It shouldn't be like that. You should ask general details of a user
                                                                                                            • Personal account created under org account

                                                                                                              Hi there, I am Jayesh. We are using ME Central, and we have an account by the email ID soc@kissht.com.. Now I have created a personal account., jayesh.auti@zohomail.in, accidentally. Can you help me to remove this jayesh.auti@zohomail.in from my organization
                                                                                                            • Add another account

                                                                                                              How to add another mail account to my zoho mail.
                                                                                                            • Recover deleted user

                                                                                                              Hi by mistake i have deleted an added user and his email associated. Please help me recover it thank you.
                                                                                                            • No connection to the server

                                                                                                              Hello! I can't add a new email address to my mailbox because your server is rejecting me. Please help. I took and added a screenshot of this problem Marek Olbrys
                                                                                                            • URGENT: Business Email Disruption – SMTP Authentication Failed

                                                                                                              Dear Zoho Support, I am writing to escalate a critical issue with my business email account: 📧 marek@olbrys.de My domain olbrys.de is fully verified in Zoho (MX, SPF, DKIM, DMARC all valid – green status). I am using the correct configuration: smtp.zoho.eu
                                                                                                            • Emails missing from desktop but visible on phone

                                                                                                              Subject says it all. Windows 11 laptop. Apple phone. all systems up to date.
                                                                                                            • Website Hosting

                                                                                                              Hello, I want to host my domain on Hostinger, and I want my emails to run through Zoho Mail. Please provide me with the SPF record, MX record (Type: TXT), and A record, so that I don’t face any issues with my emails. My website is on Hostinger hosting,
                                                                                                            • Can not search zoho mail after update V.1.7.0

                                                                                                              i can not search mail on to and cc box from attached picture and then search contacts box can't click or use anything. include replay mail too.
                                                                                                            • Urgent Security Feature Request – Add MFA to Zoho Projects Client Portal Hello Zoho Projects Team,

                                                                                                              Hello Zoho Projects Team, We hope you are doing well. We would like to submit an urgent security enhancement request regarding the Zoho Projects Client Portal. At this time, as far as we are aware, there is no Multi-Factor Authentication (MFA) available
                                                                                                            • How to retreive the "To be received" value of an Item displayed in Zoho inventory.

                                                                                                              Hi everyone, We have our own Deluge code to generate a PO according to taget quantity and box quantity, pretty usefull and powerful! However, we want to reduce our quantity to order according to "To be received" variable. Seems like this might not even
                                                                                                            • Add Support for Authenticator App MFA in Zoho Desk Help Center

                                                                                                              Hello Zoho Desk Team, We hope you are doing well. We would like to request an enhancement related to security for the Zoho Desk Help Center (customer portal). Currently, the Help Center supports MFA for portal users via SAML, JWT, SMS authentication,
                                                                                                            • Payment on a past due balance

                                                                                                              Scenario: Customer is past due on their account for 4 months. We suspend their billing in Zoho books. Customer finally logs into the portal and enters a new credit card. We associate that cardwith their subscription, which will permit the card to be used
                                                                                                            • Instant Sync of Zoho CRM Data?

                                                                                                              With how valuable Zoho Analytics is to actually creating data driven dashboards/reports, we are surprised that there is no instant or near instant sync between Zoho CRM and Zoho Analytics. Waiting 3 hours is okay for most of our reports, but there are
                                                                                                            • Kaizen #211 - Answering your Questions | Using Canvas and Widgets to Tailor CRM for Mobile

                                                                                                              Howdy, tech wizards! We are back with the final post in addressing the queries you shared for our 200th milestone. This week, we are focusing on a couple of queries on Zoho CRM mobile configurations and custom payment gateway integration. 1. Mobile SDK
                                                                                                            • Remove "Invalid entries found. Rectify and submit again" modal

                                                                                                              Following up on a post from a few years back, but can the Zoho team consider either removing the 'Invalid entries found. Rectify and submit again' modal that displays for empty mandatory fields OR allow an admin to change it? I've built a custom error
                                                                                                            • Validation function not preventing candidates under 18 or over 30 from submitting the web form

                                                                                                              Hello everyone, I’m trying to create a validation rule for the Candidate Webform in Zoho Recruit. I added a custom field called “Date of Birth”, and I want to make sure that candidates cannot submit the form unless their age is between 18 and 30 years.
                                                                                                            • Remember all the ways we've posted?

                                                                                                              The world celebrates World Postal Day in 2025 with the theme “#PostForPeople: Local Service. Global Reach". The story of the “post” is a story of human connection itself, evolving from simple handwritten notes carried over long distances to instant digital
                                                                                                            • Custom domain issue

                                                                                                              I recently changed records for my support area custom domain for a few months, I then wanted to come back to Zoho, but now I can't connect it and I can't login as it's having an SSL issue. I cannot get a good response from support, as I've been notified
                                                                                                            • Cadence reports as front-end reports

                                                                                                              Hello everyone, We have built a cadence which is connected to the Leads module. There are 11 steps in total, 7 are automatic emails and 4 are tasks for the Lead owners. As admins, we have access to this (very nicely made) 'View Reports' tab where we can
                                                                                                            • Zoho Commerce in multiple languages

                                                                                                              When will you be able to offer Zoho Commerce in more languages? We sell in multiple markets and want to be able to offer a local version of our webshop. What does the roadmap look like?
                                                                                                            • Show elapsed time on the thank-you page?

                                                                                                              Is it possible to display the total time a user spent filling out a Zoho Form on the thank-you? I’d like to show the difference between the `form submission timestamp` and the `start time` (currently have a hidden Date-Time field set to autofill the date
                                                                                                            • The present is a "present"

                                                                                                              The conversation around mental health has been gaining attention in recent years. Even with this awareness, we often feel stuck; the relentless pace of modern life makes us too busy to pause, reflect, and recharge. In the world of customer support, this
                                                                                                            • Kaizen# 209 - Answering Your Questions | All About Client Script

                                                                                                              Hello everyone! Welcome back to another exciting Kaizen post! Thanks for all your feedback and questions. In this post, let's see the answers to your questions related to Client Script. We took the time to discuss with our development team, carefully
                                                                                                            • Email Integration - Zoho CRM - OAuth and IMAP

                                                                                                              Hello, We are attempting to integrate our Microsoft 365 email with Zoho CRM. We are using the documentation at Email Configuration for IMAP and POP3 (zoho.com) We use Microsoft 365 and per their recommendations (and requirements) for secure email we have
                                                                                                            • Search in Zoho Community Not Working

                                                                                                              I realize this is a bit of a meta topic, but the search for the various Zoho Communities appears to not be working. I'm under the impression that they run on some version of the Zoho Desk platform, so I'm posting this here.
                                                                                                            • I need to do crud with snippet html

                                                                                                              I need to implement a form with an improved user interface. I would like to use snippets to build a CRUD that allows me to create and update records. How could I achieve this using snippets?
                                                                                                            • Allow Stripe Credit Card and Stripe ACH payment methods to be enabled separately on an invoice.

                                                                                                              I need to be able to pick at the invoice level whether Stripe Credit Card and/or Stripe ACH payment methods are available. Currently, I'm not able to select from the two Stripe payment methods individually on an invoice. However, there are some larger
                                                                                                            • Next Page