Convert Leads — sf_convert_lead • salesforcer

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

Usage

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 along with anytime() and anydate(). If FALSE then all fields will be returned as character. Specifying FALSE helpful when guessing the column data type will result in NA values and you would like to return the results as strings and then cast in your script according to your unique specifications.
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) { # \dontrun{
# 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)
} # }