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 Campaigns Resources




                          Zoho Developer Community



                              Bootcamp
                              Community
                              Pricing
                              Webinars
                              What's New
                              Integrations
                              Contact Support
                              Contact Sales
                                Zoho Survey Resources
                                  Features
                                  Survey Templates
                                  Integrations
                                  Community
                                  iOS Mobile Surveys
                                  Pricing
                                  Android Mobile Surveys
                                  Insurvey Blogs
                                  Insight Blogs
                                  Tips & Tricks





                                              Latest Feature Updates

                                                • Desk Community Learning Series


                                                • Digest


                                                • Functions


                                                • Meetups


                                                • Kbase


                                                • Resources


                                                • Glossary


                                                • Desk Marketplace


                                                • MVP Corner


                                                • Word of the Day


                                                • Ask the Experts




                                                    Zoho SalesIQ Resources


                                                          Manage your brands on social media
                                                          Access Zoho Social

                                                            Zoho Pagesense Resources


                                                                Zoho TeamInbox Resources

                                                                  Zoho DataPrep 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

                                                                                            Get Started. Write Away!

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

                                                                                              Zoho CRM コンテンツ






                                                                                                Nederlandse Hulpbronnen


                                                                                                    ご検討中の方




                                                                                                          • Recent Topics

                                                                                                          • When moments in customer support get "spooky"

                                                                                                            It’s Halloween again! Halloween is celebrated with spooky symbols and meanings based on history and traditions, with each region adding its own special touch. While we were kids, we would dress up in costumes along with friends, attend parties, and enjoy

                                                                                                          • How Zoho Desk contributes to the art of savings

                                                                                                            Remember the first time your grandmother gave you cash for a birthday or New Year's gift, Christmas gift, or any special day? You probably tucked that money safely into a piggy bank, waiting for the day you could buy something precious or something you

                                                                                                          • Empowered Custom Views: Cross-Module Criteria Now Supported in Zoho CRM

                                                                                                            Hello everyone, We’re excited to introduce cross-module criteria support in custom views! Custom views provide personalized perspectives on your data and that you can save for future use. You can share these views with all users or specific individuals

                                                                                                          • How can I delete duplicate transactions?

                                                                                                            I want to delete the duplicates not simply exclude them. I have duplicates, because I had automatic bank feeds turned on (had to make sure this critical functionality was working before migrating to Zoho). Now when I import my csv's exported from Wave,

                                                                                                          • Automatically Add Recurring Zoho Meeting Events to Zoho Calendar / Zoho Meeting Calendar

                                                                                                            Hello Zoho Meeting Team, Hope you are doing well. We would like to request an enhancement regarding recurring meetings created inside Zoho Meeting. At the moment, when we schedule a recurring meeting in Zoho Meeting, it does not appear in Zoho Calendar

                                                                                                          • Limited layout rules in a module

                                                                                                            There is a limit of 10 layout rules per module. Is there a way to get that functionality through different customization or workflow + custom function (easily accessible), etc. Having just 10 is limiting especially if module contains a lot of data. Are

                                                                                                          • Enhance Sign CRM integration

                                                                                                            Hello all, I'm working on a custom Deluge script to enhance the integration between Zoho CRM and Sign by using a writer merge template for additional flexibility. I want to replicate the post-sign document integration that exists between CRM and Sign

                                                                                                          • Python - code studio

                                                                                                            Hi, I see the code studio is "coming soon". We have some files that will require some more complex transformation, is this feature far off? It appears to have been released in Zoho Analytics already

                                                                                                          • Good news! Calendar in Zoho CRM gets a face lift

                                                                                                            Dear Customers, We are delighted to unveil the revamped calendar UI in Zoho CRM. With a complete visual overhaul aligned with CRM for Everyone, the calendar now offers a more intuitive and flexible scheduling experience. What’s new? Distinguish activities

                                                                                                          • Replacing email ID,

                                                                                                            In zoho sheets If I am sending it as an email attachments can I replace sender email ID from notifications to my email ID.

                                                                                                          • Move orders scan ISBN

                                                                                                            Hi We have ISBN setup to be searched in items zoho but move orders dissent recognize the ISBN is there q missing configuration? regards, JS

                                                                                                          • ViewID and Zoho Desk API

                                                                                                            I'm looking at the documentation for Listing contacts and it looks like you can filter by ViewID. I assume this is views created in a department or all departments. Is this correct? And if so, how do I find the ViewID for that view? EDIT: I see the view

                                                                                                          • Ability to Link Reported Issues from Zoho Desk to Specific Tasks or Subtasks in Zoho Projects

                                                                                                            Hi Zoho Desk Team, Hope you're doing well. When reporting a bug from Zoho Desk to Zoho Projects, we’ve noticed that it’s currently not possible to select an existing task or subtask to associate the issue with. However, when working directly inside Zoho

                                                                                                          • Automatically Update Ticket Status in Zoho Desk Based on Actions in Zoho Projects

                                                                                                            Hi Zoho Desk Team, Hope you’re doing well. We’re using the Zoho Desk–Zoho Projects integration to manage tasks related to customer tickets, and it works well for linking and tracking progress. However, there are a few important automation capabilities

                                                                                                          • Print Tickets

                                                                                                            We have field engineers who visit customers. We would like the option to print a job sheet with full details of the job and account/contact details.

                                                                                                          • Zoho Desk integration with Power BI

                                                                                                            Hi, I want to be able to create a Power BI report which has live updates of ticket data from zoho desk, is this possile at all? Thanks Jack

                                                                                                          • Ability to Attach Images When Reporting Issues to Zoho Projects from Zoho Desk

                                                                                                            Hi Zoho Desk Team, Hope you’re doing well. We’re using the Zoho Desk–Zoho Projects integration to report bugs directly from support tickets into the Zoho Projects issue tracker. This integration is extremely useful and helps us maintain smooth coordination

                                                                                                          • Ability to Choose Task List and Add Subtasks When Creating Tasks from Zoho Desk

                                                                                                            Hi Zoho Desk Team, Hope you’re doing well. We’re using the Zoho Desk–Zoho Projects integration to seamlessly connect customer tickets with project tasks. While the integration works great overall, we noticed two important limitations that affect our workflow

                                                                                                          • Sync Task Status from Zoho Projects to Zoho Desk

                                                                                                            Hi Zoho Desk Team, Hope you’re doing well. We’re actively using the Zoho Desk–Zoho Projects integration, which helps our support and project teams stay aligned. However, we noticed that when we change a task’s status in Zoho Projects, the change is not

                                                                                                          • Default/Private Departments in Zoho Desk

                                                                                                            1) How does one configure a department to be private? 2) Also, how does one change the default department? 1) On the list of my company's Zoho Departments, I see that we have a default department, but I am unable to choose which department should be default. 2) From the Zoho documentation I see that in order to create a private department, one should uncheck "Display in customer portal" on the Add Department screen. However, is there a way to change this setting after the department has been created?

                                                                                                          • Retainer invoice in Zoho Finance modlue

                                                                                                            Hello, Is there a way of creating retainer invoices in the Zoho Finance module? If not can I request this is considered for future updates please.

                                                                                                          • Can we do Image swatches for color variants?

                                                                                                            We want to do something like the attached screenshot on our new zoho store. We need image swatches instead of normal text selection. We want to user to select an image as color option. Is this doable? I don't see any option on zoho backend. Please h

                                                                                                          • Zoho CRM IP Addresses to Whitelist

                                                                                                            We were told to whitelist IP addresses from Zoho CRM.  (CRM, not Zoho Mail.) What is the current list of IP Addresses to whitelist for outbound mail? Is there a website where these IP addresses are published and updated?  Everything I could find is over

                                                                                                          • Color of Text Box Changes

                                                                                                            Sometimes I find the color of text boxes changed to a different color. This seems to happen when I reopen the same slide deck later. In the image that I am attaching, you see that the colors of the whole "virus," the "irology" part of "virology," and

                                                                                                          • The difference between Zoho Marketing Automation and Zoho Campaigns

                                                                                                            Greetings Marketers! This post aims to differentiate between Zoho Marketing Automation and Zoho Campaigns. By the time you get to the end of the post, you will be able to choose a product that objectively suits you. What is Zoho Marketing Automation?

                                                                                                          • How to use Rollup Summary in a Formula Field?

                                                                                                            I created a Rollup Summary (Decimal) field in my module, and it shows values correctly. When I try to reference it in a Formula Field (e.g. ${Deals.Partners_Requested} - ${Deals.Partners_Paid}), I get the error that the field can’t be found. Is it possible

                                                                                                          • Zoho Mail Android app update - View emails shared via Permalink on the app.

                                                                                                            Hello everyone! In the latest version(v2.8.2) of the Zoho Mail Android app update, we have brought in support to access the emails shared via permalink within the app. Earlier, when you click the permalink of an email, you'll be redirected to a mobile

                                                                                                          • Let us view and export the full price books data from CRM

                                                                                                            I quote out of CRM, some of my clients have specialised pricing for specific products - therefore we use Price Books to manage these special prices. I can only see the breakdown of the products listed in the price book and the specialised pricing for

                                                                                                          • Weekly Tips: Manage External Images in Zoho Mail

                                                                                                            When you receive emails every day, whether from clients, newsletters, or services, many of them contain external images that automatically load when you open the message. While this can make emails look more engaging, it can also impact your privacy and

                                                                                                          • How to display Motivator components in Zoho CRM home page ?

                                                                                                            Hello, I created KPI's, games and so but I want to be able to see my KPI's and my tasks at the same time. Is this possible to display Motivator components in Zoho CRM home page ? Has someone any idea ? Thanks for your help.

                                                                                                          • Introducing Record Summary: smarter insights at your fingertips

                                                                                                            Hello everyone, We’re excited to introduce the Record Summary feature. This powerful addition makes use of Zia to simplify how you interact with your CRM data, providing a seamless, consolidated view of critical record information. Scrolling through the

                                                                                                          • Account in Quick View Filter

                                                                                                            I have a report that I often run against a specific Account. Every time, I have to go into the edit menu and change the Advanced Filter. I would prefer to use the Quick View Filter, but it does not allow me to use the one and only field that makes any

                                                                                                          • Insert Cookie Policy in Zoho Sites

                                                                                                            Hello, i need to insert a banner on my site because i'm in Italy so i have to respect EU laws for Cookie Policy and Privacy Policy. I see that i need to insert a code in <head> section of my site to show a banner/popup with cookie info. How i can do this? Thank you Luca

                                                                                                          • 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

                                                                                                          • Unable to confirm Super Admin assignment — confirmation button not working

                                                                                                            I’m trying to change the roles within my organization. I am currently a super admin and would like to add another user as a super admin. When I attempt to confirm the action, a screen appears asking for my password to verify my identity. However, when

                                                                                                          • Delegates should be able to delete expenses

                                                                                                            I understand the data integrity of this request. It would be nice if there was a toggle switch in the Policy setting that would allow a delegate to delete expenses from their managers account. Some managers here never touch their expense reports, and

                                                                                                          • Let's Talk Recruit: Meet Zia, your all-in-one AI assistant (Part-2)

                                                                                                            Welcome back to Let’s Talk Recruit series. In Part 1, we introduced Zia and how AI is reshaping the way recruiters work. This time, we’re taking a closer look at how far Zia has come and how each update continues to simplify your everyday tasks. When

                                                                                                          • Function #9: Copy attachments of Sales Order to Purchase Order on conversion

                                                                                                            This week, we have written a custom function that automatically copies the attachments uploaded for a sales order to the corresponding purchase order after you convert it. Here's how to configure it in your Zoho Books organization. Custom Function: Hit

                                                                                                          • stock

                                                                                                            bom/bse : stock details or price =STOCK(C14;"price") not showing issue is #N/A! kindly resolve this problem

                                                                                                          • Kaizen #8 - Handling Recurrence and Participants in the Events Module via API

                                                                                                            Hello everyone! We are back this week with an exciting post—Handling recurrence and participants in the Events module through API. First things first—What is the Events module? "Events" is a part of the Activities module in Zoho CRM.  An event is an activity that happens at a given place and time. You can find Events on the user's Zoho CRM's home page, Activities home page, Calendar, and in other related records. What are the types of Events? Events are of two types—Recurring and non-recurring events.

                                                                                                          • Next Page