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, as well as (optionally) an Opportunity. 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, but typically, a lead can be converted as soon as it becomes a real opportunity that you want to forecast.

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

When converting leads, consider the following 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 the Salesforce online 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 big 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.

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 account. 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 the following basic steps:

  1. The client application determines the IDs of any lead(s) to be converted.
  2. Optionally, the client application determines the IDs of any account(s) to merge the lead into. The client application can use SOSL or SOQL to search for accounts that match the lead name, as in the following example:
    select id, name from account where name='CompanyNameOfLeadBeingMerged'
  3. Optionally, the client application determines the IDs of contact(s) 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 the following example:
    select id, name from contact where firstName='FirstName' and lastName='LastName' and accountId = '001...'
  4. Optionally, the client application determines whether opportunities should be created from the leads.
  5. The client application queries the LeadStatus table to obtain all of 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(s) and examine 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. This is because accounts and contacts cannot 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 the following properties.

Name Type Description
accountId ID ID of the Account into which the lead will be merged. Required only when updating an existing account, including person accounts. If no accountID is specified, then the API creates a new account. To create a new account, the client application must be logged in with sufficient access rights. To merge a lead into an existing account, the client application must be logged in with read/write access to the specified account. The account name and other existing data are not overwritten. For information on IDs, see ID Field Type.
contactId ID ID of the Contact into which the lead will be merged (this contact must be associated with the specified accountId, and an accountId must be specified). Required only when updating an existing contact.
Important
If you are converting a lead into a person account, do not specify the contactId or an error will result. Specify only the accountId of the person account.
If no contactID is specified, then the API creates a new contact that is implicitly associated with the Account. To create a new contact, the client application must be logged in with sufficient access rights. To merge a lead into an existing contact, the client application must be logged in with read/write access to the specified contact. The contact name and other existing data are not overwritten (unless overwriteLeadSource is set to true, in which case only the LeadSource field is overwritten).
convertedStatus string Valid LeadStatus value for a converted lead. Required. To obtain the list of possible values, the client application queries the LeadStatus object. For example:
SELECT Id, MasterLabel
FROM LeadStatus WHERE IsConverted=true
doNotCreateOpportunity boolean Specifies whether to create an Opportunity during lead conversion (false, the default) or not (true). Set this flag to true only if you do not want to create an opportunity from the lead. An opportunity is created by default.
leadId ID ID of the Lead to convert. Required. For information on IDs, see ID Field Type.
opportunityName string Name of the opportunity to create. If no name is specified, then this value defaults to the company name of the lead. The maximum length of this field is 80 characters. If doNotCreateOpportunity argument is true, then no Opportunity is created and this field must be left blank; otherwise, an error is returned.
overwriteLeadSource boolean Specifies whether to overwrite the LeadSource field on the target Contact object with the contents of the LeadSource field in the source Lead object (true), or not (false, the default). To set this field to true, the client application must specify a contactId for the target contact.
ownerId ID Specifies the ID of the person to own any newly created account, contact, and opportunity. If the client application does not specify this value, then the owner of the new object will be the owner of the lead. Not applicable when merging with existing objects—if an ownerId is specified, the API does not overwrite the ownerId field in an existing account or contact. For information on IDs, see ID Field Type.
sendNotificationEmail boolean Specifies whether to send a notification email to the owner specified in the ownerId (true) or not (false, the default).

Response

LeadConvertResult[]

Fault

UnexpectedErrorFault

© Copyright 2000–2014 salesforce.com, inc. All rights reserved.
Various trademarks held by their respective owners.