LeadConvert
Converts leads to accounts, contacts, deal registrations, or opportunities.
Usage
You use the LeadConvert method to convert leads. To download the Lead Conversion WSDL and to convert leads using Web service calls, the Convert Leads privilege must be enabled for your user role. You can create account, contact, deal registration, and opportunity records, or copy lead information to existing records by converting the lead record. Depending on your company’s settings, the new opportunity record can include information that affects revenue calculations.
If the necessary options are available in the lead conversion layouts, you can also do the following:
Copy the members of the lead team to the team on the account, contact, and opportunity that are created or linked to the lead during the conversion process. You can also determine the record access level to grant to the lead owner in the team.
Link the lead’s associated custom object records to the account, contact, and opportunity that are created or linked to the lead during the conversion process. Custom Objects 01 through 40 are supported.
The LeadConvert method provides the same functionality that is available in the Lead Convert page in the UI. For conversion, a contact record is required, either an existing contact record or a new record.
The following table shows how the fields in the Lead Convert UI page map to fields used in LeadConvert Web service requests.
UI Field | LeadConvert Method Field | Comments |
---|---|---|
Account Fields |
||
Associated Account |
AccountName |
For existing accounts. The following fields can be used to pick an existing account: - Id, ExternalSystemId, AccountName and Location. |
Account Name |
AccountName |
For new accounts. |
Copy Lead Team |
CopyLeadTeamtoAccount |
Possible values: true or false, 1 or 0. |
Lead Owner Record Access in Account Team |
AccountTeamLeadOwnerAccess |
The record access level to grant to the lead owner in the account team. |
Associate Custom Object 01 through Associate Custom Object 40 |
AssociateCO1ToAccount through AssociateC40ToAccount |
Possible values: true or false, 1 or 0. |
Contact Fields |
||
Associated Contact |
ContactFirstName ContactLastName |
For existing contacts. The following fields can be used to pick an existing contact: Id, ExternalSystemId, ContactFirstName and ContactLastName. |
Contact First Name |
ContactFirstName |
Required in a conversion request |
Contact Last Name |
ContactLastName |
Required in a conversion request |
Copy Lead Team |
CopyLeadTeamtoContact |
Possible values: true or false, 1 or 0. |
Lead Owner Record Access in Contact Team |
Contact TeamLeadOwnerAccess |
The record access level to grant to the lead owner in the contact team. |
Associate Custom Object 01 through Associate Custom Object 40 |
AssociateCO1ToContact through AssociateC40ToContact |
Possible values: true or false, 1 or 0. |
Opportunity Fields |
||
Associated Opportunity |
OpportunityName |
For new opportunities |
Potential Revenue |
PotentialRevenue |
Also a Deal Registration field |
Estimated close date |
EstimatedCloseDate |
Also a Deal Registration field |
Next Step |
NextStep |
Also a Deal Registration field |
Description |
Description |
Also a Deal Registration field |
Copy Lead Team |
CopyLeadTeamtoOpportunity |
Possible values: true or false, 1 or 0. |
Lead Owner Record Access in Opportunity Team |
OpportunityTeamLeadOwnerAccess |
The record access level to grant to the lead owner in the opportunity team. |
Associate Custom Object 01 through Associate Custom Object 40 |
AssociateCO1ToOppty through AssociateC40ToOppty |
Possible values: true or false, 1 or 0. |
Deal Registration Fields |
||
Deal Registration Name |
DealRegistrationName |
For new opportunities |
Principal Partner Account |
PartnerName |
Required when converting to a deal registration. Principal Partner Account can be specified using the PartnerName, PartnerId, or PartnerExternalSystemId fields. |
Company Name |
Company |
None |
Usually you convert leads that have previously been qualified to opportunities.
You can include up to 20 leads in the request for conversion. You can convert the same lead to an account or contact multiple times, but you can convert a lead to a deal registration or opportunity only once. If you have converted a lead to a deal registration or opportunity, you cannot later convert it to a different deal registration or opportunity. However, a lead that has been converted to a deal registration can also later be converted to a different account or contact.
Arguments
The following table describes the arguments taken by the LeadConvert method.
Name | Description | Required | Default | I/O |
---|---|---|---|---|
ListOfLead |
The list of leads and associated account, contact, deal registration, and opportunity records. |
Yes |
Not applicable |
Input/Output |
Return Value of the Call
The status keys of the converted lead and the account, contact, opportunity, and deal registration records are returned.
Sample SOAP Request - LeadConvert
The following SOAP request creates new account, contact, opportunity, and deal registration records for a lead.
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wsse="http://docs.oasis-
open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:xsd="http://
www.w3.org/2001/XMLSchema">
<soap:Header>
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsse:UsernameToken>
<wsse:Username>%%%USERNAME%%%</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">%%%PASSWORD%%%</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</soap:Header>
<soap:Body>
<LeadConvert_Input xmlns="urn:crmondemand/ws/leadconvert/">
<ListOfLead>
<Lead>
<LeadFirstName>lead1</LeadFirstName>
<LeadLastName>test</LeadLastName>
<Account>
<AccountName>My New Opty Account</AccountName>
<Location>Will not show</Location>
</Account>
<Contact>
<ContactFirstName>Converted</ContactFirstName>
<ContactLastName>Contact</ContactLastName></Contact>
<Opportunity>
<OpportunityName>Converted</OpportunityName>
<PotentialRevenue>2500</PotentialRevenue>
<EstimatedCloseDate>2015-12-10T05:00:00Z</EstimatedCloseDate>
<NextStep>Reconvert</NextStep>
<Description>Converted Lead - Test</Description>
<ExternalSystemId>LEAD-CONV-DATA</ExternalSystemId>
</Opportunity>
<DealRegistration>
<DealRegistrationName>DR Converted</DealRegistrationName>
<Company>Test</Company>
<PotentialRevenue>2500</PotentialRevenue>
<EstimatedCloseDate>2015-12-10T05:00:00Z</EstimatedCloseDate>
<NextStep>Reconvert</NextStep>
<Description>Converted Lead - Test</Description>
<ExternalSystemId>LEAD-CONV-DR</ExternalSystemId>
<PartnerName>test</PartnerName>
</DealRegistration>
</Lead>
</ListOfLead>
</LeadConvert_Input>
</soap:Body>
</soap:Envelope>
Sample SOAP Response
The following response contains the status keys of the newly-created records:
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Body>
<ns:LeadConvert_Output xmlns:ns="urn:crmondemand/ws/leadconvert/">
<ListOfLead xmlns="urn:/crmondemand/xml/leadconvert/Data">
<Lead>
<Id>1QA2-2EYBDY</Id>
<ExternalSystemId></ExternalSystemId>
<ModId>0</ModId>
<CreatedById>1-CZ10</CreatedById>
<CreatedDate>2015-12-08T07:52:59Z</CreatedDate>
<CreatedBy>%%%USERNAME%%%, 2015-12-08T07:52:59Z</CreatedBy>
<ModifiedDate>2015-12-08T07:52:59Z</ModifiedDate>
<ModifiedById>1-CZ10</ModifiedById>
<ModifiedBy>%%%USERNAME%%%, 2015-12-08T07:52:59Z</ModifiedBy>
<Account>
<Id>1QA2-2EXDFQ</Id>
<ExternalSystemId></ExternalSystemId>
<ModId>0</ModId>
<CreatedById>1-CZ10</CreatedById>
<CreatedDate>2015-12-08T07:52:59Z</CreatedDate>
<CreatedBy>%%%USERNAME%%%, 2015-12-08T07:52:59Z</CreatedBy>
<ModifiedDate>2015-12-08T07:52:59Z</ModifiedDate>
<ModifiedById>1-CZ10</ModifiedById>
<ModifiedBy>%%%USERNAME%%%, 2015-12-08T07:52:59Z</ModifiedBy>
</Account>
<Contact>
<Id>1QA2-R22RU</Id>
<ExternalSystemId></ExternalSystemId>
<ModId>0</ModId>
<CreatedById>1-CZ10</CreatedById>
<CreatedDate>2015-12-08T07:52:59Z</CreatedDate>
<CreatedBy>%%%USERNAME%%%, 2015-12-08T07:52:59Z</CreatedBy>
<ModifiedDate>2015-12-08T07:52:59Z</ModifiedDate>
<ModifiedById>1-CZ10</ModifiedById>
<ModifiedBy>%%%USERNAME%%%, 2015-12-08T07:52:59Z</ModifiedBy>
</Contact>
<Opportunity>
<Id>1QA2-2EY4IO</Id>
<ExternalSystemId></ExternalSystemId>
<ModId>0</ModId>
<CreatedById>1-CZ10</CreatedById>
<CreatedDate>2015-12-08T07:52:59Z</CreatedDate>
<CreatedBy>%%%USERNAME%%%, 2015-12-08T07:52:59Z</CreatedBy>
<ModifiedDate>2015-12-08T07:52:59Z</ModifiedDate>
<ModifiedById>1-CZ10</ModifiedById>
<ModifiedBy>%%%USERNAME%%%, 2015-12-08T07:52:59Z</ModifiedBy>
</Opportunity>
<DealRegistration>
<Id>1QA2-2EY41J</Id>
<ExternalSystemId></ExternalSystemId>
<ModId>0</ModId>
<CreatedById>1-CZ10</CreatedById>
<CreatedDate>2015-12-08T07:52:59Z</CreatedDate>
<CreatedBy>%%%USERNAME%%%, 2015-12-08T07:52:59Z</CreatedBy>
<ModifiedDate>2015-12-08T07:52:59Z</ModifiedDate>
<ModifiedById>1-CZ10</ModifiedById>
<ModifiedBy>%%%USERNAME%%%, 2015-12-08T07:52:59Z</ModifiedBy>
</DealRegistration>
</Lead>
</ListOfLead>
</ns:LeadConvert_Output>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>