Lead Conversion Customization

Lead Conversion Customization

This skill activates when a practitioner needs Apex to control, extend, or react to lead conversion — including custom field transfer, selective record creation, and post-conversion side effects. It covers the Database.LeadConvert API and the Apex trigger patterns that fire during and after conversion.

Before Starting

Gather this context before working on anything in this domain:

• Confirm the converted LeadStatus API name. Database.LeadConvert.setConvertedStatus() requires the exact API name of a picklist value where IsConverted = true. Passing a display label causes a runtime error.
• Verify whether the org already has an after update trigger on Lead that fires on conversion. Conversion fires before update and after update on Lead, before insert/after insert on Contact, Account, and (optionally) Opportunity. Adding logic in multiple places without coordination causes duplicate processing.
• Know the batch size. Database.convertLead() accepts a maximum of 100 Database.LeadConvert instances per call. Exceeding this limit throws a System.LimitException at runtime.
• Understand which custom fields are mapped in Setup (Object Manager > Lead > Map Lead Fields). Only mapped fields are copied automatically. All others silently drop their values unless handled in Apex post-conversion.

Core Concepts

Database.LeadConvert and LeadConvertResult

Database.LeadConvert is the Apex object used to configure a single lead conversion. You build a list of these, one per lead, set properties on each, and pass the list to Database.convertLead(). The method returns a List<Database.LeadConvertResult>.

Key setters on Database.LeadConvert:

Database.LeadConvertResult exposes getAccountId(), getContactId(), getOpportunityId(), isSuccess(), and getErrors(). You cannot instantiate this class directly in test code — see the Testing Gotcha below.

Custom Field Transfer Is Not Automatic

Salesforce automatically copies Lead field values to Contact, Account, and Opportunity only for fields that are explicitly mapped in Setup > Object Manager > Lead > Map Lead Fields. Custom fields that are not mapped are silently dropped at conversion time. The Lead record remains in the database with the original field values, so recovery is possible, but it requires a follow-up query against the converted Lead.

The correct pattern is to perform a post-conversion DML update: after calling Database.convertLead(), query the converted Lead for the unmapped custom fields, then update the resulting Contact, Account, or Opportunity records with those values.

Conversion Fires Triggers on Multiple Objects

A single Database.convertLead() call fires triggers on:

All of this happens in a single transaction. Governor limits are shared across all trigger fires. SOQL queries and DML operations performed in any one trigger count against the same transaction limits.

The 100-Lead Batch Limit

Database.convertLead() enforces a hard limit of 100 Database.LeadConvert objects per invocation. When processing more than 100 leads, split the input list into chunks of 100 and call convertLead() multiple times. In a Batch Apex execute() method, set batch size to 100 or fewer to stay within this limit without manual chunking.

Common Patterns

Pattern 1: Controlled Bulk Lead Conversion Service

When to use: A user action, Flow, or scheduled job needs to convert leads in bulk with custom configuration — suppressing opportunity creation, targeting specific accounts, or running post-conversion field mapping.

How it works:

public class LeadConversionService {

    public static void convertLeads(List<Id> leadIds) {
        // Fetch the converted status once
        String convertedStatus = [
            SELECT MasterLabel FROM LeadStatus
            WHERE IsConverted = true
            LIMIT 1
        ].MasterLabel;

        List<Database.LeadConvert> conversions = new List<Database.LeadConvert>();
        for (Id leadId : leadIds) {
            Database.LeadConvert lc = new Database.LeadConvert();
            lc.setLeadId(leadId);
            lc.setConvertedStatus(convertedStatus);
            lc.setDoNotCreateOpportunity(true);
            lc.setSendNotificationEmail(false);
            conversions.add(lc);
        }

        // Enforce 100-lead batch limit
        List<Database.LeadConvertResult> results = new List<Database.LeadConvertResult>();
        for (Integer i = 0; i < conversions.size(); i += 100) {
            List<Database.LeadConvert> batch = conversions.subList(i,
                Math.min(i + 100, conversions.size()));
            results.addAll(Database.convertLead(batch));
        }

        // Collect converted record Ids for post-conversion field mapping
        List<Id> contactIds = new List<Id>();
        for (Database.LeadConvertResult r : results) {
            if (r.isSuccess()) {
                contactIds.add(r.getContactId());
            }
        }
        // Continue with custom field transfer...
    }
}

Why not the alternative: Calling convertLead() one record at a time in a loop hits governor limits quickly and cannot be bulkified across a trigger batch. Building a list-based service method keeps the conversion atomic and governor-safe.

Pattern 2: Post-Conversion Custom Field Transfer via After-Update Trigger on Lead

When to use: Unmapped custom fields on Lead must be transferred to Contact, Account, or Opportunity every time a conversion occurs — including conversions triggered from the UI, from Flow, or from Apex.

How it works:

Use an after update trigger on Lead. When IsConverted flips to true, query the Lead's custom fields, then update the related Contact.

trigger LeadTrigger on Lead (before insert, before update, after insert, after update) {
    if (!TriggerControl.isActive('Lead')) return;
    LeadTriggerHandler handler = new LeadTriggerHandler();

    if (Trigger.isBefore && Trigger.isInsert)  handler.onBeforeInsert(Trigger.new);
    if (Trigger.isBefore && Trigger.isUpdate)  handler.onBeforeUpdate(Trigger.new, Trigger.oldMap);
    if (Trigger.isAfter  && Trigger.isInsert)  handler.onAfterInsert(Trigger.new);
    if (Trigger.isAfter  && Trigger.isUpdate)  handler.onAfterUpdate(Trigger.new, Trigger.oldMap);
}

public with sharing class LeadTriggerHandler {

    public void onAfterUpdate(List<Lead> newLeads, Map<Id, Lead> oldMap) {
        List<Id> convertedLeadIds = new List<Id>();
        for (Lead l : newLeads) {
            if (l.IsConverted && !oldMap.get(l.Id).IsConverted) {
                convertedLeadIds.add(l.Id);
            }
        }
        if (convertedLeadIds.isEmpty()) return;

        // Re-query because ConvertedContactId is not in Trigger.new
        Map<Id, Lead> leads = new Map<Id, Lead>([
            SELECT Id, ConvertedContactId, Custom_Score__c, Demo_Requested__c
            FROM Lead
            WHERE Id IN :convertedLeadIds
        ]);

        List<Contact> contactsToUpdate = new List<Contact>();
        for (Lead l : leads.values()) {
            if (l.ConvertedContactId != null) {
                contactsToUpdate.add(new Contact(
                    Id = l.ConvertedContactId,
                    Lead_Score__c = l.Custom_Score__c,
                    Demo_Requested__c = l.Demo_Requested__c
                ));
            }
        }

        if (!contactsToUpdate.isEmpty()) {
            update contactsToUpdate;
        }
    }
}

Why not the alternative: Doing the update inside the Apex service that calls convertLead() works only for programmatic conversions. The trigger-based approach also covers UI conversions, Flow-driven conversions, and API conversions from external systems.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. Gather context — Identify the converted LeadStatus API name, which custom fields need to be transferred, whether Opportunity creation should be suppressed, and whether an existing Account or Contact should be targeted. Confirm the org edition and whether a trigger framework is already in use.
2. Check for existing Lead triggers — Query the org for any after update triggers on Lead. If one exists, add conversion logic inside the existing handler rather than creating a second trigger. One trigger per object is non-negotiable.
3. Build or extend the conversion service — Implement Database.LeadConvert list construction with correct setters. Add chunking logic for batches over 100. Use allOrNone = false with Database.convertLead(conversions, false) only if partial success is acceptable, and handle individual errors from LeadConvertResult.getErrors().
4. Add post-conversion field mapping — For unmapped custom fields, either add logic after convertLead() in the service (programmatic-only path) or add an after update trigger on Lead detecting IsConverted flip (covers all paths). Do not mix both without a guard to prevent double-processing.
5. Write the test class — Create a Lead, convert it using Database.convertLead(), retrieve the resulting LeadConvertResult from the return value, and assert on isSuccess() and resulting record Ids. Do not attempt to instantiate LeadConvertResult directly; use the returned instance.
6. Run the checker script and validate — Execute python3 scripts/skill_sync.py --skill skills/apex/lead-conversion-customization and then python3 scripts/validate_repo.py before marking the work complete.

Review Checklist

Run through these before marking work in this area complete:

• Converted LeadStatus API name is fetched dynamically or validated — not hardcoded as a display label
• Database.convertLead() calls are chunked to 100 leads per invocation
• Custom field transfer logic runs post-conversion, not inside the convertLead() call itself
• No second Lead trigger has been created if one already exists — logic added to existing handler
• Test class verifies isSuccess() on LeadConvertResult and does not instantiate the result class directly
• Post-conversion DML uses with sharing and respects FLS for the target fields
• Error handling covers partial failures when allOrNone = false is used

Salesforce-Specific Gotchas

1. LeadConvertResult cannot be instantiated in test code — The class has no public constructor. Attempting new Database.LeadConvertResult() fails at compile time. In tests, call Database.convertLead() with a real or test Lead and use the returned result instances. If mock results are needed, deserialize from a JSON string using (Database.LeadConvertResult) JSON.deserialize(...).

2. IsConverted flip fires after update, not a special event — There is no dedicated conversion trigger event. The only reliable detection in a trigger is checking l.IsConverted && !oldMap.get(l.Id).IsConverted in after update. Logic placed in before update cannot read ConvertedContactId or ConvertedAccountId yet — those fields are populated only after the conversion DML completes.

3. Unmapped custom fields silently drop their values — Salesforce does not warn or error when a custom Lead field has no mapping. The data disappears at conversion time. The original Lead record retains its values but the Contact, Account, and Opportunity do not receive the data without explicit post-conversion DML.

Output Artifacts

Related Skills

• admin/lead-management-and-conversion — Use for configuring lead conversion field mapping in Setup, managing lead status picklist values, and building assignment rules. This Apex skill assumes Setup configuration is already in place.
• apex/trigger-framework — Use when deciding how to structure the Lead trigger handler or when a trigger framework is already in the org and must be followed.
• apex/batch-apex-patterns — Use when converting more than a few hundred leads — Batch Apex handles the 100-per-call chunking cleanly at scale.
• apex/mixed-dml-and-setup-objects — Conversion is a DML-heavy operation; be aware of mixed-DML constraints if post-conversion logic touches Setup objects.