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 an account, contact, and (optionally) an opportunity, the owner of the generated records is automatically subscribed and the lead owner is unsubscribed from the lead record. Any users that were subscribed to the lead are now subscribed to the generated records and unsubscribed from the lead. This means that the lead owner and other users that were subscribed to the lead see any changes to the account, contact, and opportunity records in their news feed. The subscription occurs unless the user has selected the Stop automatically following records checkbox in Your Name | Setup | My Chatter Settings | My Feeds.

A user can subscribe to a record so that changes to the record are displayed in the Chatter feed on the user's home page, which is a useful way to stay up-to-date 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:

The client application determines the IDs of any lead(s) to be converted.
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'
```
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...'
```
Optionally, the client application determines whether opportunities should be created from the leads.
The client application queries the LeadSource table to obtain all of the possible converted status options (SELECT ... FROM LeadStatus WHERE IsConverted='1'), and then selects a value for the Converted Status.
The client application calls convertLead().
The client application iterates through the returned result(s) and examine each LeadConvertResult object to determine whether conversion succeeded for each lead.
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.
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

public String[] convertLeadRecords() {
  String[] result = new String[4];
  try {
    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);
    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();
        if ( i % 2 == 0 ) {
          leadsToConvert[i].setConvertedStatus("Qualified");
        }
        leadsToConvert[i].setLeadId(saveResults[i].getId());
        result[0] = saveResults[i].getId();
      } else {
        System.out.println("\nError creating new Lead: " +
            saveResults[i].getErrors()[0].getMessage());
      }
    }
    LeadConvertResult[] lcResults = 
        connection.convertLead(leadsToConvert);
    for (int j = 0; j < lcResults.length; ++j) {
      if (lcResults[j].isSuccess()) {
        String acctId = lcResults[j].getAccountId();
        System.out.println("Success! Account ID: " + acctId);
        result[1] = lcResults[j].getAccountId();
        result[2] = lcResults[j].getContactId();
        result[3] = 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#

private bool convertLead(string leadId, string contactId, 
   string accountId, bool overWriteLeadSource, 
   bool doNotCreateOpportunity, string opportunityName, 
   string convertedStatus, bool sendEmailToOwner)  
{

   sforce.LeadConvert leadConvert = new sforce.LeadConvert();
   leadConvert.leadId = leadId;
   leadConvert.contactId = contactId;
   leadConvert.accountId = accountId;
   leadConvert.overwriteLeadSource = overWriteLeadSource;
   leadConvert.doNotCreateOpportunity = doNotCreateOpportunity;
   leadConvert.opportunityName = opportunityName;
   leadConvert.convertedStatus = convertedStatus;
   leadConvert.sendNotificationEmail = sendEmailToOwner;

   sforce.LeadConvertResult[] lcr = null;
   try 
   {

      lcr = binding.convertLead(new sforce.LeadConvert[] {leadConvert});
      for (int i=0;i<lcr.Length;i++)
         if (lcr[i] 
    .success)
        {
            Console.WriteLine("Conversion succeeded.\n");
            sforce.LeadConvertResult result = lcr[i] 
    ;
            Console.WriteLine("The new contact id is: " + result.contactId);
         } 
         else 
         {
            Console.WriteLine("The conversion failed because: " + lcr[i] 
    .errors[0].message);
         }
   }

   catch (Exception e) 
   {
      Console.WriteLine("Unexpected error encountered:\n\n" + e.Message);
      return false;
   }

   return true;
}

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