Convert Leads

Converts Leads each into an Account, Contact, as well as (optionally) an Opportunity.

sf_convert_lead(
  input_data,
  guess_types = TRUE,
  api_type = c("SOAP"),
  control = list(...),
  ...,
  verbose = FALSE
)

Arguments

input_data

named vector, matrix, data.frame, or tbl_df; data can be coerced into a data.frame. See the details below on how format your input data to control things like whether an opportunity will be created, an email will be sent to the new owner, and other control options.

guess_types

logical; indicating whether or not to use col_guess() to try and cast the data returned in the recordset. If TRUE then col_guess() is used, if FALSE then all fields will be returned as character. This is helpful when col_guess() will mangle field values in Salesforce that you'd like to preserve during translation into a tbl_df, like numeric looking values that must be preserved as strings ("48.0").

api_type

character; one of "REST", "SOAP", "Bulk 1.0", or "Bulk 2.0" indicating which API to use when making the request.

control

list; a list of parameters for controlling the behavior of the API call being used. For more information of what parameters are available look at the documentation for sf_control.

...

arguments passed to sf_control

verbose

logical; an indicator of whether to print additional detail for each API call, which is useful for debugging. More specifically, when set to TRUE the URL, header, and body will be printed for each request, along with additional diagnostic information where available.

Value

tbl_df with details of the converted record

Details

When converting leads owned by a queue, the owner must be specified. This is because accounts and contacts cannot be owned by a queue. Below is a complete list of options to control the conversion process. Include a column in your input data to specify an option for each record. For example, if you want opportunities to not be created for each converted lead then add a column in your input data called doNotCreateOpportunity and set its value to TRUE. The default is FALSE which creates opportunities. The order of columns in the input data does not matter, just that the names match (case-insensitive).

leadId

ID of the Lead to convert. Required.

convertedStatus

Valid LeadStatus value for a converted lead. Required.

accountId

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.

contactId

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.

ownerId

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.

opportunityId

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.

doNotCreateOpportunity

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.

opportunityName

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

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.

sendNotificationEmail

Specifies whether to send a notification email to the owner specified in the ownerId (TRUE) or not (FALSE, the default).

Salesforce Documentation

Examples

if (FALSE) {
# create a new lead at Grand Hotels & Resorts Ltd
new_lead <- tibble(FirstName = "Test", LastName = "Prospect",
                   Company = "Grand Hotels & Resorts Ltd")
rec <- sf_create(new_lead, "Lead")

# find the Id of matching account to link to
acct_id <- sf_query("SELECT Id from Account WHERE name = 'Grand Hotels & Resorts Ltd' LIMIT 1")

# create the row(s) for the leads to convert
to_convert <- tibble(leadId = rec$id, 
                     convertedStatus = "Closed - Converted", 
                     accountId = acct_id$Id)
converted_lead <- sf_convert_lead(to_convert)
}