SOAP API Developer Guide
jNewer Version Available
convertLead()
Converts a Lead into an Account, Contact, or (optionally) an Opportunity.
Syntax
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, contact, and opportunity 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.
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 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:
- 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:
- Optionally, the client application determines whether opportunities should 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 the following
example:
- The client application queries the LeadStatus table to obtain all of the possible
converted status options
(), 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
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.
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.
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. 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: |
| 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. |
| opportunityId | ID | The ID of an existing opportunity to relate to the lead. The opportunityId and opportunityName arguments are mutually exclusive. Specifying a value for both results in an error. If doNotCreateOpportunity argument is true, then no Opportunity is created and this field must be left blank; otherwise, an error is returned. |
| 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. The opportunityId and opportunityName arguments are mutually exclusive. Specifying a value for both results in an error. 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). |