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 #222 - Client Script Support for Notes Related List

      Hello everyone! Welcome to another week of Kaizen. The final Kaizen post of the year 2025 is here! With the new Client Script support for the Notes Related List, you can validate, enrich, and manage notes across modules. In this post, we’ll explore how

    • Kaizen #217 - Actions APIs : Tasks

      Welcome to another week of Kaizen! In last week's post we discussed Email Notifications APIs which act as the link between your Workflow automations and you. We have discussed how Zylker Cloud Services uses Email Notifications API in their custom dashboard.

    • Kaizen #216 - Actions APIs : Email Notifications

      Welcome to another week of Kaizen! For the last three weeks, we have been discussing Zylker's workflows. We successfully updated a dormant workflow, built a new one from the ground up and more. But our work is not finished—these automated processes are

    • Kaizen #152 - Client Script Support for the new Canvas Record Forms

      Hello everyone! Have you ever wanted to trigger actions on click of a canvas button, icon, or text mandatory forms in Create/Edit and Clone Pages? Have you ever wanted to control how elements behave on the new Canvas Record Forms? This can be achieved

    • Kaizen #142: How to Navigate to Another Page in Zoho CRM using Client Script

      Hello everyone! Welcome back to another exciting Kaizen post. In this post, let us see how you can you navigate to different Pages using Client Script. In this Kaizen post, Need to Navigate to different Pages Client Script ZDKs related to navigation A.

    • Recent Topics

    • Zoho Books Invoices Templates

      It would be really helpful to have more advanced features to customise the invoice templates in Zoho Books. Especially I´m thinking of the spacing of the different parts of the invoice (Address line etc.). If you have a sender and receiver address in

    • Can add a colum to the left of the item in Zoho Books?

      I would need to add a column to the left of the item column in Books. When i create custom fields, i can only display them to the right of the item.

    • Verifying Zoho Mail Functionality After Switching DNS from Cloudflare to Hosting Provider

      I initially configured my domain's (https://roblaxmod.com/) email with Zoho Mail while using Cloudflare to manage my DNS records (MX, SPF, etc.). All services were working correctly. Recently, I have removed my site from Cloudflare and switched my domain's

    • AI Bot and Advanced Automation for WhatsApp

      Most small businesses "live" on WhatsApp, and while Bigin’s current integration is helpful, users need more automation to keep up with volume. We are requesting features based on our customer Feedbacks AI Bot: For auto-replying to FAQs. Keyword Triggers:

    • Improved Contact Sync flow in Google Integration with Zoho CRM

      Hello Everyone, Your contact sync in Google integration just got revamped! We have redesigned the sync process to give users more control over what data flows into Google and ensure that this data flows effortlessly between Zoho CRM and Google. With this

    • 2025 Ask the Experts sessions wrap-up : Key highlights from the experts

      Here is a rewind journey of our Ask the Experts (ATE) Sessions, where we brought you expert insights and practical best practices together in one place. This recap highlights the key takeaways, learnings, and best practices from all these sessions so

    • How to disable the edit option in subform

      How to disable the edit option in subform

    • Adding non-Indian billing address for my Zoho subscription

      Hey Need help with adding a non-Indian billing address for my Zoho subscription, trying to edit the address to my Singapore registered company. Won't let me change the country. Would appreciate the help. Regards, Rishabh

    • Move record from one custom module to another custom module

      Is it possible to create a button or custom field that will transfer a record from one custom module to another? I already have the 'Leads' module used for the Sr. Sales department, once the deal is closed they convert it to the 'Accounts' module. I would like to create a 'Convert' button for a custom module ('Locations') for the department that finds locations for each account. Once the location is secured, I want to move the record to another custom module called 'Secured Locations'. It's basically

    • Convert Lead Automation Trigger

      Currently, there is only a convert lead action available in workflow rules and blueprints. Also, there is a Convert Lead button available but it doesn't trigger any automations. Once the lead is converted to a Contact/Account the dataset that can be fetched

    • Notes Not Saving

      Hello,  My notes are continuously not saving.  I make sure to save them, I know the process to save them.  It is not operator error.  I go back into a Leads profile a while later and do not see the previous notes that I have made.  I then have to go back and do unnecessary research that would have been in the notes in the first place.  Not a good experience and it is frustrating.  Slows me down and makes me do unnecessary work.  Please resolve.   As a quick heads up, deleting cookies is not a fix

    • Integration between "Zoho Sprints Stories" and "Zoho Projects Tasks/Subtasks"

      We have two separate teams in our organization using Zoho for project management: The Development team uses Zoho Sprints and follows Agile/Scrum methodology. The Infrastructure team uses Zoho Projects for traditional task-based project management. In

    • Prefill form with CRM/Campaigns

      I created a form in zForms and created prefill fields. I added this to the CRM and selected the fields so when sending from the CRM, the form works great. However, I want to use the same form in Campaigns and I want it to pull the data from CRM (which

    • Triggering a campaign automation from a Form

      I used Forms to create a lead form that is accessed by a button on my website. The field information flows into the CRM. However, I am trying to figure out how to use Campaign automations to start a workflow (series of campaign emails) that is triggered

    • Name changed in settings for mailbox but still not changed when typed in To field

      In the email account secretary@ i have updaetd the new staff members details but the old members name still appears when I type secretary@ in the To field. I cant work out where Zoho is finding the old name from. I have deleted the browser cache. If I

    • Employee Appraisal Applicability - Why is Date of Joining Hard-Coded?

      In the new (to me, at least) Performance Appraisal Cycle wizard, it's possible to set criteria to determine for whom the appraisal process should apply. This makes sense on its face. However, one MUST use the Date of Joining criterion as a filter. Why

    • Formula fields

      Zoho People now supports formula fields. This post illustrates it. Formula fields are fields whose value is calculated instead of being entered by the user. Using this, number, decimal and date manipulations can be done. The value of this field could be numeric or date depending on the output of the formula. In date manipulations, the result will be given in milliseconds, which you can format as per you need. The operators we support are +, - , *, /. Formula fields get recalculated automatically

    • Copy paste from word document deletes random spaces

      Hello Dear Zoho Team, When copying from a word document into Notebook, often I face a problem of the program deleting random spaces between words, the document become terribly faulty, eventhough it is perfect in its original source document (and without

    • Is it possible to use module field filters via URL parameters?

      It would be really convenient if I could quickly link to a filter. For reference, this is the filter functionality I'm referring to: https://help.zoho.com/portal/en/kb/crm/customize-crm-account/advanced-filters/articles/advanced-filters For example: My

    • Transitioning FESCO Bill Project to Zoho Sheets and Integration Options

      Hello Zoho Support, I'm considering transitioning my FESCO bill project from Google Sheets to Zoho Sheets and wanted to know if there are integration options to seamlessly migrate our existing work. You can view our platform here, any guidance would be

    • Support for Custom Fonts in Zoho Recruit Career Site and Candidate Portal

      Dear Zoho Recruit Team, I hope you're doing well. We would like to request the ability to use custom fonts in the Zoho Recruit Career Site and Candidate Portal. Currently only the default fonts (Roboto, Lato, and Montserrat) are available. While these

    • Lightbox Pop-up form

      I would like to embed my form using the lightbox pop up. I don't want it to load automatically. I want it to load when some clicks the button. I can see this option, however when I use the "show pop-up launch button" on the website, the button automatically

    • Data Processing Basis

      Hi, Is there a way to automate the data processing for a candidate every time an application arrives from job boards, without requiring manual intervention? That is, to automatically acquire consent for data processing. I've seen a workflow that allows

    • Lightbox Pop-up form

      I would like to embed my form using the lightbox pop up. I don't want it to load automatically. I want it to load when some clicks the button. I can see this option, however when I use the "show pop-up launch button" on the website, the button automatically

    • Zoho CRM for Everyone's NextGen UI Gets an Upgrade

      Hello Everyone We've made improvements to Zoho CRM for Everyone's Nextgen UI. These changes are the result of valuable feedback from you where we’ve focused on improving usability, providing wider screen space, and making navigation smoother so everything

    • Customer Management: #5 Never Let the Customer Slip

      When Rahul started Knight's Watch Consulting, his focus was simple: deliver good work and keep clients happy. He offered one-time consulting projects, monthly advisory retainers and usage-based support for growing clients. Business was steady, and customers

    • 10GB Email Storage Limits in Zoho CRM

      We’ve had Zoho One for almost 5 years and have always synced our emails from Gmail via IMAP… As of late, we’ve run into issues with our emails not syncing, due to being over the 10GB storage cap… What’s very odd is that we haven’t changed a thing? I know

    • Zoho Projects Android and iOS app update: Mobile device permission based on user profiles

      Hello everyone! We have brought in support for mobile device permissions based on the user profiles which are configured in organization level. Administrators can now configure the permissions on the web app(projects.zoho.com) by following the steps mentioned

    • Unlocking New Levels: Zoho Payroll's Journey in 2025

      Every year brings its own set of challenges and opportunities to rethink how payroll works across regulations and teams. In 2025, Zoho Payroll continued to evolve with one clear focus: giving businesses more flexibility, clarity, and control as they grow.

    • Zoho Projects Android and iOS app update: Timesheet module is now renamed as 'Time Logs', delete option has been renamed to 'Trash'.

      Hello everyone! We have now renamed the Timesheet module as Time Logs and the delete option as 'Trash' on the Zoho Projects Android and iOS app. Time Logs Android: Time Logs iOS: Trash option Android: Trash option iOS: Please update the app to the latest

    • Zoho Mail app update: Manage profile picture, Chinese (Traditional) language support

      Hello everyone! In the latest version (v3.1.9) of the Zoho Mail app update, we have brought in support to manage profile picture. You can now set/ modify the profile picture within the app. To add a new profile picture, please follow the below steps:

    • Reminders for Article Approval

      Is there a way to send reminders for approvers to review articles and approve/deny them? I'm not seeing that option anywhere.

    • To print Multiple delivery notes in batches

      In Zoho Books, we can print a Delivery Note from an Invoice using the Print Delivery Note option, but it is non-editable and always prints all line items from the invoice. Our requirement is to deliver invoiced items in batches and print delivery notes

    • Add Full-Screen Viewing for Quartz Recordings in the Client Interface

      Hi Zoho Team, We would like to request an enhancement to the Zoho Quartz client interface when viewing submitted recordings. Current Limitation: When viewing a Quartz recording from the client (user) interface, there is currently no option to switch the

    • 2025 Recap: A Year to Remember | Zoho Inventory

    • Important Update : Pipedrive deprecated fields no longer supported in Zoho Analytics

      Dear Pipedrive users, We would like to inform you about a recent update related to your Pipedrive integration with Zoho Analytics. The Pipedrive team has deprecated certain fields from their application. You can find more details in the official Pipedrive

    • Product Updates in Zoho Workplace applications | November 2025

      Hello Workplace Community, Let’s take a look at the new features and enhancements that went live across all Workplace applications this November. Zoho Mail Format comments easily using Slash Commands With Slash commands, you can easily format text, insert

    • Right-Click Pipeline to Open in New Tab

      Please add the ability to right-click on a pipeline to open it in a new tab

    • Adjusting Physical Inventory

      Not getting very far with support on this one, they say they are going to fix it but nothings happened since November. Please give this a thumbs up if you would like to see this feature or comment if you have some insight. Use Case: Inventory set to be

    • How to install Widget in inventory module

      Hi， I am trying to install a app into Sales Order Module related list, however there is no button allow me to do that. May I ask how to install widget to inventory module related list?

    • Next Page