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!  

    • Sticky Posts

    • Kaizen #197: Frequently Asked Questions on GraphQL APIs

      🎊 Nearing 200th Kaizen Post – We want to hear from you! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.

    • Kaizen #198: Using Client Script for Custom Validation in Blueprint

      Nearing 200th Kaizen Post – 1 More to the Big Two-Oh-Oh! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.

    • Celebrating 200 posts of Kaizen! Share your ideas for the milestone post

      Hello Developers, We launched the Kaizen series in 2019 to share helpful content to support your Zoho CRM development journey. Staying true to its spirit—Kaizen Series: Continuous Improvement for Developer Experience—we've shared everything from FAQs

    • Kaizen #193: Creating different fields in Zoho CRM through API

      🎊 Nearing 200th Kaizen Post – We want to hear from you! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.

    • Client Script | Update - Introducing Commands in Client Script!

      Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! Commands

    • Recent Topics

    • 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

    • Formula field with IF statement based on picklist field and string output to copy/paste in multi-line field via function

      Hello there, I am working on a formula field based on a 3-item picklist field (i.e. *empty value*, 'Progress payment', 'Letter of credit'). Depending on the picked item, the formula field shall give a specific multi-line string (say 'XXX' in case of 'Progress

    • CRM x WorkDrive: File storage for new CRM signups is now powered by WorkDrive

      Availability Editions: All DCs: All Release plan: Released for new signups in all DCs. It will be enabled for existing users in a phased manner in the upcoming months. Help documentation: Documents in Zoho CRM Manage folders in Documents tab Manage files

    • Zoho CRMの流入元について

      Zoho CRMとZoho formsを連携し、 formsで作成したフォームをサイトに埋め込み運用中です。 UTMパラメータの取得をformsを行い、Zoho CRMの見込み客タブにカスタム項目で反映される状況になっています。 広告に関してはUTMパラメータで取得できているため問題ないのですが、オーガニック流入でフォーム送信の場合も計測したいです。メールやGoogle、Yahoo、directなどの流入元のチャネルが反映されるようにしたいのですが、どのように設定したら良いでしょうか。 また、

    • Error While Sign in on Zoho Work Drive

      Dear Team, I hope this email finds you well. I have recently created a Zoho account and started using it. But while I am trying to log in to Zoho work drive it won't log me in its crashing every time I try it. I have tried it on android app, phone browser

    • Choosing a portal option and the "Unified customer portal"?

      I am trialling Zoho to replace various existing systems, one of which is a customer portal. Our portal allows clients to add and edit bookings, complete forms, manage their subscriptions and edit some CRM info. I am trying to understand how I might best

    • Elevate your CX delivery using CommandCenter 2.0: Simplified builder; seamless orchestration

      Most businesses want to create memorable customer experiences—but they often find it hard to keep them smooth, especially as they grow. To achieve a state of flow across their processes, teams often stitch together a series of automations using Workflow

    • Unified Directory : How to Access ?

      I signed in to Zoho One this morning and was met with the pop up about the upgraded directory (yay!) I watched the video and pressed "Get Started" ... and it took me back to the standard interface. How do I actually access the new portal/directory ?

    • Translation support expanded for Modules, Subforms and Related Lists

      Hello Everyone!   The translation feature enables organizations to translate certain values in their CRM interface into different languages. Previously, the only values that could be translated were picklist values and field names. However, we have extended

    • Unified task view

      Possible to enable the unified task view in Trident, that is currently available in Mail?

    • Bigin, more powerful than ever on iOS 26, iPadOS 26, macOS Tahoe, and watchOS 26.

      Hot on the heels of Apple’s latest OS updates, we’ve rolled out several enhancements and features designed to help you get the most from your Apple devices. Enjoy a refined user experience with smoother navigation and a more content-focused Liquid Glass

    • Importing data into Assets

      So we have a module in Zoho CRM called customers equipments. It links to customers modules, accounts (if needed) and products. I made a sample export and created extra fields in zoho fsm assets module. The import fails. Could not find a matching parent

    • Allow instruction field in Job Sheets

      Hello, I would like to know if it is possible to have an instruction field (multi line text) in a job sheet or if there is a workaround to be able to do it. Currently we are pretty limited in terms of fields in job sheets which makes it a bit of a struggle

    • Streamlining Work Order Automation with Zoho Projects, Writer & WorkDrive

      Hello Community, Here is the first post in 'Integration & Automation' Series. Use Case :: Create, Merge, Sign & Store Documents in Zoho WorkDrive. Scenario :: You have a standard Work Order template created in Zoho Writer. When a task status is chosen

    • The dimensions of multilingual power

      Hola, saludos de Zoho Desk. Bonjour, salutations de Zoho Desk. Hallo, Grüße von Zoho Desk. Ciao, saluti da Zoho Desk. Olá, saudações da Zoho Desk. வணக்கம், Zoho Desk இலிருந்து வாழ்த்துகள். 你好，来自 Zoho Desk 的问候。 مرحباً، تحيات من Zoho Desk. नमस्ते, Zoho

    • Multi-line address lines

      How can I enter and migrate the following 123 state street Suite 2 Into a contact address. For Salesforce imports, a CR between the information works. The ZOHO migration tool just ignores it. Plus, I can't seem to even enter it on the standard entry screen.

    • Accessing Zoho Forms

      Hi all, We're having trouble giving me access to our company's Zoho Forms account. I can log in to a Forms account that I can see was set up a year ago, but can't see any shared forms. I can log into Zoho CRM and see our company information there without

    • Archiving Contacts

      How do I archive a list of contacts, or individual contacts?

    • Cost of good field

      Is there a way we can have cost of good sold as a field added to the back end of the invoicing procedure and available in reports?

    • How to add image to items list in Invoice or Estimate?

      Hello! I have just started using Zoho Invoice to create estimates and, possibly to switch from our current CRM/ERP Vendor to Zoho. I have a small company that is installing CCTV systems and Alarm systems. My question is, can I add images of my "items" to item list in Zoho Invoice and Estimates and their description? I would like to show my clients the image of items in our estimates so they can decide if they like these items. And I tell you, often they choose more expensive products just because

    • Issue with the Permission to Zoho Form

      I am getting an error by signing in to zoho form as it is stated that i don't have permission to access this is admin account

    • CRM templates

      Hello everyone, In my company we use Zoho campaigns where we set up all newsletters and we use Zoho CRM for transactional emails. I have created some templates in Zoho campaigns but from my understanding i cannot use those in Zoho CRM, right?

    • Meet Canvas' Grid component: Your easiest way to build responsive record templates

      Visual design can be exciting—until you're knee-deep in the details. Whether it's aligning text boxes to prevent overlaps, fixing negative space, or simply making sure the right data stands out, just ironing out inconsistencies takes a lot of moving parts.

    • Addin Support in Zoho Sheet

      Is there any addin support available in zoho sheet as like google marketplace to enhance productivity by connecting with other apps, providing AI data analysis, streamlining business processes, and more?

    • Where to integrate Price Book and Product List Price

      Hello, We sync zoho crm all modules with all data to zoho analytics. In zoho crm, we have "Price Books" and "Products" modules, where each product is assigned to a few price books with different list prices. From zoho crm, I am able to export a dataset

    • Pending Sales Order Reports

      Pending sale order report is available for any single customer, Individual report is available after 3-4 clicks but consolidated list is needed to know the status each item. please help me.

    • Zoho Mail SMTP IP addresses

      We are using Zoho Mail and needs to whitelist IP for some redirections from your service to another e-mails. You can provide IP address list for Zohomail SMTP servers?

    • Migrate Your Notes from OneNote to Zoho Notebook Today

      Greetings Notebook Users, We’re excited to introduce a powerful new feature that lets you migrate your notes from Microsoft OneNote to Zoho Notebook—making your transition faster and more seamless than ever. ✨ What’s New One-click migration: Easily import

    • Zoho Campaigns - Why do contacts have owners?

      When searching for contacts in Zoho Campaigns I am sometimes caught out when I don't select the filter option "Inactive users". So it appears that I have some contacts missing, until I realise that I need to select that option. Campaigns Support have

    • One Contact with Multiple Accounts with Portal enabled

      I have a contact that manages different accounts, so he needs to see the invoices of all the companies he manage in Portal but I found it not possible.. any idea? I tried to set different customers with the same email contact with the portal enabled and

    • End Date in Zoho Bookings

      When I give my appointments a 30 minutes time I would expect the software not to even show the End Time.  But it actually makes the user pick an End Time.  Did I just miss a setting?  

    • email forwarding not working

      Your email forwarding service does not work. I received the confirmation email and completed the confirmation, after that nothing and nothing since no matter what I have tried. Shame as everything else was smooth. I spose it's harder to run one of these web based internet mail services than you guys thought!!! can you fix the email forwarding asap PLEASE!

    • Google Ads Conversions Not Being Tracked in Zoho CRM

      We have 3 different conversions created in our Google Ads Account. Only one of the 3 conversion types is tracking in Zoho CRM. Our forms are Elementor Forms that are mapped into Zoho CRM. It apprears to me that all leads are showing up in Zoho CRM, but

    • Enable Locations for Expense

      Hi, please enable Locations (ex Branches) for Zoho Expense so that there is consistency between this app and Zoho Books. Thanks in advance.

    • Currency abbreviations

      Hello, Im stuck, and need help. I need the currency fields for example, opportunity value, or total revenue, to be abbreviated, lets say for 1,000 - 1K, 1,000,000 - 1M, and so on, how should I do this?

    • in the Zoho Creator i have File Upload field get the file on submission of the form Get the File and upload to Zoho Books

      in the Zoho Creator i have File Upload field get the file on submission of the form Get the File and upload to Zoho Books . how I get the file From zoho creator and upload to Zoho Books . using Api response = invokeUrl [ url: "https://www.zohoapis.com/creator/v2.1/data/hh/l130/report/All_Customer_Payments/"+input.ID

    • Generate a link for Zoho Sign we can copy and use in a separate email

      Please consider adding functionality that would all a user to copy a reminder link so that we can include it in a personalized email instead of sending a Zoho reminder. Or, allow us to customize the reminder email. Use Case: We have clients we need to

    • Syntax for URLs in HTML Snippets

      What are some best practices for inserting a URL in an HTML snippet? I've looked at Zoho Help articles on navigation-based and functional-based URLs, but I'm still unclear on how to incorporate them in an HTML snippet. For example, 1. How do I link to

    • Rate Limiting in Zoho Flow (OpenAI API)

      Hi Everyone, We are facing some issues when using Zoho Flow as we have a deluge script running which is making external calls to OpenAI endpoint. Sometimes the response takes more than 30 seconds meaning the script will timeout. We want to implement a

    • Placing a condition before converting the LEAD

      Hi,  I need some assistance with Lead conversion. I need to place certain conditions before allowing the user to convert the lead.  For example: up until the certain status's doesn't equal "green" don't allow to convert lead.  I tried creating this using

    • Next Page