convertLead()

Converts a Lead into an Account, Contact, or (optionally) an Opportunity.

Syntax

LeadConvertResult[] = connection.convertLead(leadConverts LeadConvert[]);

Usage

Use convertLead() to convert a Lead into an Account and Contact, and (optionally) an Opportunity. If appropriate for your business, you can also use convertLead() to convert a lead to an account and a person account instead of a contact. To convert a Lead, your client application must be logged in with the “Convert Leads” permission and the “Edit” permission on leads, as well as “Create” and “Edit” on the Account, Contact, and Opportunity objects.

This call provides an easy way to convert the information in a qualified lead to a new or updated account, contact, and opportunity. Your organization can set its own guidelines for determining when a lead is qualified. Typically, a lead can be converted when it becomes a real opportunity that you want to forecast.

If data is merged into existing account, contact, and opportunity objects, then only empty fields in the target object are overwritten—existing data (including IDs) aren’t overwritten. The only exception is if your client application sets overwriteLeadSource to true. In this case, the LeadSource field in the target Contact object is overwritten with the contents of the LeadSource field in the source Lead object.

When converting leads, consider these rules and guidelines.

Field Mappings

The system automatically maps standard lead fields to standard account, contact, and opportunity fields. For custom lead fields, your Salesforce administrator can specify how they map to custom account, contact, and opportunity fields.

Record Types

If the organization uses record types, the default record type of the new owner is assigned to records created during lead conversion. For more information about record types, see Salesforce Help .

Picklist Values

The system assigns the default picklist values for the account, contact, and opportunity when mapping any standard lead picklist fields that are blank. If your organization uses record types, blank values are replaced with the default picklist values of the new record owner.

String Values

Starting with API version 15.0, if you specify a value for a field that contains a string, and the value is too large for the field, the call fails, and an error is returned. In previous versions of the API the value was truncated and the call succeeded. If you wish to keep the old behavior with versions 15.0 and later, use the AllowFieldTruncationHeader SOAP header.

Errors

If any of the leads fail to convert as part of a bulk operation, the lead conversion is retried for each lead individually.

Automatic Subscriptions for Chatter Feeds

When you convert a lead into a new account, contact, and opportunity, the lead owner is unsubscribed from the lead record’s Chatter feed. The lead owner, the owner of the generated records, and users that were subscribed to the lead aren't automatically subscribed to the generated records, unless they have automatic subscriptions enabled in their Chatter feed settings. They must have automatic subscriptions enabled to see changes to the account, contact, and opportunity records in their news feed.

A user can subscribe to a record or to another user. Changes to the record and updates from the users are displayed in the Chatter feed on the user's home page, which is a useful way to stay up to date with other users and with changes made to records in Salesforce. Feeds are available in API version 18.0 and later.

Basic Steps for Converting Leads

Converting leads involves these basic steps.

1. The client application determines the IDs of any leads to be converted.
2. Optionally, the client application determines the IDs of any accounts to merge the lead into. The client application can use SOSL or SOQL to search for accounts that match the lead name, as in this example.
   select id, name from account where name='CompanyNameOfLeadBeingMerged'

3. Optionally, the client application determines the IDs of contacts to merge the lead into. The client application can use SOSL or SOQL to search for contacts that match the lead contact name, as in this example.
   select id, name from contact where firstName='FirstName' and lastName='LastName' and accountId = '001...'

4. Optionally, the client application determines whether opportunities must be created from the lead, or the ID of an opportunity to merge the lead into. The client application can use SOSL or SOQL to search for contacts that match the lead contact name, as in this example.
   select id, name from opportunity where name='OpportunityNameOfOpportunityBeingMerged'

5. The client application queries the LeadStatus table to obtain the possible converted status options (
   SELECT Id, MasterLabel FROM LeadStatus WHERE IsConverted=true

   ), and then selects a value for the Converted Status.
6. The client application calls convertLead().
7. The client application iterates through the returned result and examines each LeadConvertResult object to determine whether conversion succeeded for each lead.
8. As an optional best practice, the client application creates tasks in which the WhoId is the ContactId and, if an opportunity is created, the WhatId is the OpportunityId.
9. Optionally, when converting leads owned by a queue, the owner must be specified. Accounts and contacts can’t be owned by a queue. Even if you are specifying an existing account or contact, you must still specify an owner.

Sample Code—Java

This sample shows how to convert leads. It creates two leads and converts them. Next, it iterates through the lead conversion results and writes the IDs of the account, contact, and opportunity created for each lead.

public String[] convertLeadRecords() {
   String[] result = new String[4];
   try {

      // Create two leads to convert
      Lead[] leads = new Lead[2];
      Lead lead = new Lead();
      lead.setLastName("Mallard");
      lead.setFirstName("Jay");
      lead.setCompany("Wingo Ducks");
      lead.setPhone("(707) 555-0328");
      leads[0] = lead;
      lead = new Lead();
      lead.setLastName("Platypus");
      lead.setFirstName("Ogden");
      lead.setCompany("Denio Water Co.");
      lead.setPhone("(775) 555-1245");
      leads[1] = lead;
      SaveResult[] saveResults = connection.create(leads);

      // Create a LeadConvert array to be used
      // in the convertLead() call
      LeadConvert[] leadsToConvert = new LeadConvert[saveResults.length];

      for (int i = 0; i < saveResults.length; ++i) {
         if (saveResults[i].isSuccess()) {
            System.out
                  .println("Created new Lead: " + saveResults[i].getId());
            leadsToConvert[i] = new LeadConvert();
            leadsToConvert[i].setConvertedStatus("Closed - Converted");
            leadsToConvert[i].setLeadId(saveResults[i].getId());
            result[0] = saveResults[i].getId();
         } else {
            System.out.println("\nError creating new Lead: "
                  + saveResults[i].getErrors()[0].getMessage());
         }
      }
      // Convert the leads and iterate through the results
      LeadConvertResult[] lcResults = connection.convertLead(leadsToConvert);
      for (int j = 0; j < lcResults.length; ++j) {
         if (lcResults[j].isSuccess()) {
            System.out.println("Lead converted successfully!");
            System.out.println("Account ID: " + lcResults[j].getAccountId());
            System.out.println("Contact ID: " + lcResults[j].getContactId());
            System.out.println("Opportunity ID: "
                  + lcResults[j].getOpportunityId());
         } else {
            System.out.println("\nError converting new Lead: "
                  + lcResults[j].getErrors()[0].getMessage());
         }
      }
   } catch (ConnectionException ce) {
      ce.printStackTrace();
   }
   return result;
}

Sample Code—C#

This sample shows how to convert leads. It creates two leads and converts them. Next, it iterates through the lead conversion results and writes the IDs of the account, contact, and opportunity created for each lead.

public String[] convertLeadRecords()
{
   String[] result = new String[4];
   try
   {
      // Create two leads to convert
      Lead[] leads = new Lead[2];
      Lead lead = new Lead();
      lead.LastName = "Mallard";
      lead.FirstName = "Jay";
      lead.Company = "Wingo Ducks";
      lead.Phone = "(707) 555-0328";
      leads[0] = lead;
      lead = new Lead();
      lead.LastName = "Platypus";
      lead.FirstName = "Ogden";
      lead.Company = "Denio Water Co.";
      lead.Phone = "(775) 555-1245";
      leads[1] = lead;
      SaveResult[] saveResults = binding.create(leads);

      // Create a LeadConvert array to be used
      //   in the convertLead() call
      LeadConvert[] leadsToConvert =
            new LeadConvert[saveResults.Length]; ;
      for (int i = 0; i < saveResults.Length; ++i)
      {
         if (saveResults[i].success)
         {
            Console.WriteLine("Created new Lead: " +
                  saveResults[i].id);
            leadsToConvert[i] = new LeadConvert();
            leadsToConvert[i].convertedStatus = "Closed - Converted";
            leadsToConvert[i].leadId = saveResults[i].id;
            result[0] = saveResults[i].id;
         }
         else
         {
            Console.WriteLine("\nError creating new Lead: " +
                  saveResults[i].errors[0].message);
         }
      }
      // Convert the leads and iterate through the results
      LeadConvertResult[] lcResults =
            binding.convertLead(leadsToConvert);
      for (int j = 0; j < lcResults.Length; ++j)
      {
         if (lcResults[j].success)
         {
            Console.WriteLine("Lead converted successfully!");
            Console.WriteLine("Account ID: " +
                     lcResults[j].accountId);
            Console.WriteLine("Contact ID: " +
                     lcResults[j].contactId);
            Console.WriteLine("Opportunity ID: " +
                     lcResults[j].opportunityId);
         }
         else
         {
            Console.WriteLine("\nError converting new Lead: " +
                  lcResults[j].errors[0].message);
         }
      }
   }
   catch (SoapException e)
   {
      Console.WriteLine("An unexpected error has occurred: " +
                        e.Message + "\n" + e.StackTrace);
   }
   return result;
}

LeadConvert Arguments

This call accepts an array of LeadConvert objects (100 maximum). A LeadConvert object contains these properties.

SELECT Id, MasterLabel
FROM LeadStatus WHERE IsConverted=true

Response

LeadConvertResult[]

Fault

UnexpectedErrorFault