ConvertLead Operation

Database Method Syntax

LeadConvertResult Database.convertLead(LeadConvert leadToConvert, Boolean opt_allOrNone)
LeadConvertResult[] Database.convertLead(LeadConvert[] leadsToConvert, Boolean opt_allOrNone)

The optional opt_allOrNoneparameter specifies whether the operation allows partial success. If you specify false for this parameter and a record fails, the remainder of the DML operation can still succeed. This method returns a result object that can be used to verify which records succeeded, which failed, and why.

Rules and Guidelines

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. For more information about field mappings, see the Salesforce online help.
Merged fields: If data is merged into existing account and contact objects, only empty fields in the target object are overwritten—existing data (including IDs) are not overwritten. The only exception is if you specify setOverwriteLeadSource on the LeadConvert object to true, in which case the LeadSource field in the target contact object is overwritten with the contents of the LeadSource field in the source LeadConvert object.
Record types: If the organization uses record types, the default record type of the new owner is assigned to records created during lead conversion. The default record type of the user converting the lead determines the lead source values available during conversion. If the desired lead source values are not available, add the values to the default record type of the user converting the lead. 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.
Automatic feed subscriptions: 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 news feed on the user's home page. This is a useful way to stay up-to-date with changes to records in Salesforce.

Basic Steps for Converting Leads

Converting leads involves the following basic steps:

Your application determines the IDs of any lead(s) to be converted.
Optionally, your application determines the IDs of any account(s) into which to merge the lead. Your application can use SOQL to search for accounts that match the lead name, as in the following example:
```
SELECT Id, Name FROM Account WHERE Name='CompanyNameOfLeadBeingMerged'
```
Optionally, your application determines the IDs of the contact or contacts into which to merge the lead. The application can use 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 application determines whether opportunities should be created from the leads.
The 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 application calls convertLead.
The application iterates through the returned result or results and examines each LeadConvertResult object to determine whether conversion succeeded for each lead.
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.

LeadConvert Object Methods

The convertLead database method accepts up to 100 LeadConvert objects. A LeadConvert object supports the following methods:

Name	Arguments	Return Type	Description
`getAccountId`		ID	Gets the ID of the account into which the lead will be merged.
`getContactId`		ID	Gets the ID of the contact into which the lead will be merged.
`getConvertedStatus`		String	Get the lead status value for a converted lead
`getLeadID`		ID	Get the ID of the lead to convert.
`getOpportunityName`		String	Get the name of the opportunity to create.
`getOwnerID`		ID	Get the ID of the person to own any newly created account, contact, and opportunity.
`isDoNotCreateOpportunity`		Boolean	Indicates whether an Opportunity is created during lead conversion (`false`, the default) or not (`true`).
`isOverWriteLeadSource`		Boolean	Indicates whether the LeadSource field on the target Contact object is overwritten with the contents of the LeadSource field in the source Lead object (`true`), or not (`false`, the default).
`isSendNotificationEmail`		Boolean	Indicates whether a notification email is sent to the owner specified by `setOwnerId` (`true`) or not (`false`, the default).
`setAccountId`	ID `ID`	Void	Sets the ID of the account into which the lead will be merged. This value is required only when updating an existing account, including person accounts. Otherwise, if `setAccountID` is specified, a new account is created.
`setContactId`	ID `ID`	Void	Sets the ID of the contact into which the lead will be merged (this contact must be associated with the account specified with `setAccountId`, and `setAccountId` must be specified). This value is required only when updating an existing contact. Important If you are converting a lead into a person account, do not specify `setContactId` or an error will result. Specify only `setAccountId` of the person account. If `setContactID` is specified, then the application creates a new contact that is implicitly associated with the account. The contact name and other existing data are not overwritten (unless `setOverwriteLeadSource` is set to true, in which case only the `LeadSource` field is overwritten).
`setConvertedStatus`	String `Status`	Void	Sets the lead status value for a converted lead. This field is required.
`setDoNotCreateOpportunity`	Boolean `CreateOpportunity`	Void	Specifies whether to create an opportunity during lead conversion. The default value is `false`: opportunities are created by default. Set this flag to `true` only if you do not want to create an opportunity from the lead.
`setLeadId`	ID `ID`	Void	Sets the ID of the lead to convert. This field is required.
`setOpportunityName`	String `OppName`	Void	Sets the name of the opportunity to create. If no name is specified, this value defaults to the company name of the lead. The maximum length of this field is 80 characters. If `setDoNotCreateOpportunity` is true, no Opportunity is created and this field must be left blank; otherwise, an error is returned.
`setOverwriteLeadSource`	Boolean `OverwriteLeadSource`	Void	Specifies whether to overwrite the `LeadSource` field on the target contact object with the contents of the `LeadSource` field in the source lead object. The default value is false, to not overwrite the field. If you specify this as true, you must also specify `setContactId` for the target contact.
`setOwnerId`	ID `ID`	Void	Specifies the ID of the person to own any newly created account, contact, and opportunity. If the application does not specify this value, the owner of the new object will be the owner of the lead. This method is not applicable when merging with existing objects—if `setOwnerId` is specified, the `ownerId` field is not overwritten in an existing account or contact.
`setSendNotificationEmail`	Boolean `SendEmail`	Void	Specifies whether to send a notification email to the owner specified by `setOwnerId`. The default value is false, that is, to not send email.

LeadConvertResult Object

An array of LeadConvertResult objects is returned with the convertLead database method. Each element in the LeadConvertResult array corresponds to the SObject array passed as the SObject[] parameter in the convertLead database method, that is, the first element in the LeadConvertResult array matches the first element passed in the SObject array, the second element corresponds with the second element, and so on. If only one SObject is passed in, the LeadConvertResults array contains a single element.

A LeadConvertResult object has the following methods:

Name	Type	Description
`getAccountId`	ID	The ID of the new account (if a new account was specified) or the ID of the account specified when `convertLead` was invoked
`getContactId`	ID	The ID of the new contact (if a new contact was specified) or the ID of the contact specified when `convertLead` was invoked
`getErrors`	Database.Error []Database.Error []	If an error occurred, an array of one or more database error objects providing the error code and description. For more information, see Database Error Object Methods.
`getLeadId`	ID	The ID of the converted lead
`getOpportunityId`	ID	The ID of the new opportunity, if one was created when `convertLead` was invoked
`isSuccess`	Boolean	A Boolean value that is set to true if the DML operation was successful for this object, false otherwise

Database Method Example

Lead myLead = new Lead(LastName = 'Fry', Company='Fry And Sons');
insert myLead;

Database.LeadConvert lc = new database.LeadConvert();
lc.setLeadId(myLead.id);

LeadStatus convertStatus = [SELECT Id, MasterLabel FROM LeadStatus WHERE IsConverted=true LIMIT 1];
lc.setConvertedStatus(convertStatus.MasterLabel);

Database.LeadConvertResult lcr = Database.convertLead(lc);
System.assert(lcr.isSuccess());