Retrieving lead conversion options in Zoho CRM lets you understand what records are created during conversion and how field data is mapped across modules — essential knowledge before triggering any conversion workflow or API call.
Why this matters
When a lead reaches a qualifying stage, Zoho CRM can convert it into an account, a contact, and a deal simultaneously. [1] Understanding the available conversion options — including which fields carry over and which modules are created — prevents data loss and ensures your pipeline is populated correctly. This is especially relevant when building automations, bulk-converting leads, or integrating third-party tools. [4]
> Note: Beam Help is an independent expert support resource, not official Zoho support.
---
Step-by-step
Step 1. Understand what conversion produces.
In Zoho CRM, converting a qualified lead generates linked records across the Accounts, Contacts, and Deals modules. The lead's status reaching a certain stage signals it is ready to be treated as a potential deal. [1] Knowing this upfront shapes which conversion options you need to retrieve or configure.
Step 2. Review lead conversion field mapping.
Before retrieving or customising conversion options, navigate to Settings → Customization → Modules and Fields → Leads to inspect how lead fields are mapped to destination module fields. [2] Any fields that are not explicitly selected during conversion are populated according to the default lead conversion mapping already configured in your org. [4]
Step 3. Access bulk lead conversion settings (Q4 2024 and later).
Zoho CRM's Q4 2024 update introduced the ability to choose specific deal fields during bulk lead conversion. Go to the Leads list view, select multiple lead records, and trigger the bulk conversion action. A configuration panel appears where you can pick which deal fields to populate manually; all remaining fields fall back to the standard conversion mapping. [4] This gives your team granular control without rewriting the entire mapping.
Step 4. Use the Zoho CRM API to retrieve conversion options programmatically.
If you need to retrieve conversion options via code, the Zoho CRM JavaScript SDK (v8, v7, or v6) provides methods to interact with the Leads module. [5] Set up your SDK connection, authenticate with the appropriate OAuth scopes, and call the relevant Leads endpoint to fetch record details and conversion-related field values. [5] The specific scopes required depend on your use case — add them when creating your connection under Settings → Developer Space → Connections. [2]
Step 5. Configure a CRM connection with the right scopes.
Navigate to Settings → Developer Space → Connections, click Create Connection, select your target services, name the connection, and add the OAuth scopes that cover lead read and conversion operations. [2] Authorise the connection once all scopes are added. This connection is what your custom functions or external integrations will reference when retrieving or acting on conversion options.
Step 6. Optionally extend conversion with custom fields.
If your conversion workflow needs to capture additional intent or status data, create custom fields on the Leads module (for example, a Picklist for intent category or a Checkbox for qualification flags) via Settings → Customization → Modules and Fields → Leads. [2] These fields can then be included in your conversion mapping so the data travels with the record when it converts.
Step 7. Explore Marketplace extensions for non-standard conversion targets.
Standard lead conversion creates accounts, contacts, and deals. If your process requires converting a lead to a vendor or syncing leads from external platforms, the Zoho Marketplace offers purpose-built extensions — for example, "Convert Lead to Vendor for Zoho CRM" — that surface additional conversion options beyond the defaults. [3]
---
Common pitfalls
- Missing field mapping: Fields that have no mapping defined are silently skipped during conversion. Always verify your conversion mapping in Settings → Customization → Modules and Fields → Leads before running bulk conversions. [4]
- Insufficient OAuth scopes: Attempting to retrieve conversion options via the API without the correct scopes will result in authorisation errors. Add all required scopes at connection creation time rather than editing them later. [2]
- SDK version mismatch: The Zoho CRM JavaScript SDK has multiple major versions (V8, V7, V6, V2.1, V2). Only V8 supports certain features like the Zoho Hosted LLM vendor. Confirm which API version your org is on before selecting an SDK version. [2] [5]
---
What to check
- Conversion mapping is complete: Confirm that every lead field you care about has a corresponding mapping to the target module field in the Leads customisation settings. [4]
- Connection is authorised: Verify that your Developer Space connection shows an active, authorised status with the correct OAuth scopes before making any API calls. [2]
- Bulk conversion deal fields are configured: If using the Q4 2024 bulk conversion feature, confirm that the deal fields you want to populate manually are selected in the conversion panel, so no critical pipeline data defaults to blank. [4]