The following table lists supported calls in the API in alphabetical order, and provides a brief description for each. Click a call name to see syntax, usage, and more information for that call.
Note: For a list of API utility calls, see Utility Calls Reference, and for a list of describe calls, see Describe Calls Reference.
Description Call
Converts a Lead into an Account,Contact, or (optionally) an Opportunity.
convertLead
Adds one or more new individual objects to your organization’s data.
create
Deletes one or more individual objects from your organization’s data.
delete
Retrieves the IDs of individual objects of the specified object that have been deleted since the specified time. For information on IDs, see ID Field Type.
getDeleted
Retrieves the IDs of individual objects of the specified object that have been updated since the specified time. For information on IDs, see ID Field Type.
getUpdated
Logs in to the login server and starts a client session.
login
Merges records of the same object type.
merge
Submits an array of approval process instances for approval, or processes an array of approval process instances to be approved, rejected, or removed.
process
Executes a query against the specified object and returns data that matches the specified criteria.
query
Same as query, but includes deleted and archived items.
queryAll
Retrieves the next batch of objects from a query.
queryMore
Retrieves one or more objects based on the specified object IDs.
retrieve
Executes a text search in your organization’s data.
search
Undelete records identified with queryAll.
undelete
Updates one or more existing objects in your organization’s data.
update
Creates new objects and updates existing objects; matches on a custom field to determine the presence of existing objects.
upsert
convertLead
Converts a Lead into an Account,Contact, or (optionally) an Opportunity.
Syntax
LeadConvertResult[] = sfdc.convertLead(leadConverts LeadConvert[]);
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 and contact 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.
Basic Steps for Converting Leads
Converting leads involves the following basic steps:
1. The client application determines the IDs of any lead(s) to be converted.
2. 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:
select id, name from account where name='CompanyNameOfLeadBeingMerged'
3. 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:
select id, name from contact where firstName='FirstName' and lastName='LastName' and accountId = '001…'
convertLead
4. Optionally, the client application determines whether opportunities should be created from the leads.
5. The client 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.
6. The client application calls convertLead.
7. The client application iterates through the returned result(s) and examine each LeadConvertResult object to determine whether conversion succeeded for each lead.
8. 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.
9. 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
private Boolean convertLead (String leadId, String contactId,
String accountId, boolean overWriteLeadSource, boolean doNotCreateOpportunity, String opportunityName, String convertedStatus, boolean sendEmailToOwner) {
LeadConvert leadConvert = new LeadConvert();
leadConvert.setLeadId(leadId);
leadConvert.setContactId(contactId);
leadConvert.setAccountId(accountId);
leadConvert.setOverwriteLeadSource(overWriteLeadSource);
leadConvert.setDoNotCreateOpportunity(doNotCreateOpportunity);
leadConvert.setOpportunityName(opportunityName);
leadConvert.setConvertedStatus(convertedStatus);
leadConvert.setSendNotificationEmail(sendEmailToOwner);
LeadConvertResult[] lcr = null;
try {
lcr = binding.convertLead(new LeadConvert[] {leadConvert});
for (int i=0; i<lcr.length; i++) { if (lcr[i].isSuccess()) {
System.out.println("Conversion succeeded.\n");
LeadConvertResult result = lcr[i];
System.out.println("The new contact id is: " + result.getContactId());
} else {
System.out.println("The conversion failed because: " + lcr[i].getErrors(0).getMessage());
} }
} catch (UnexpectedErrorFault e) {
System.out.println("Unexpected error encountered:\n\n" + e.getExceptionMessage());
return Boolean.FALSE;
} catch (RemoteException e) {
System.out.println("Remote exception encountered:\n\n" + e.getMessage());
return Boolean.FALSE;
}
return Boolean.TRUE;
}
Sample Code—C#
private bool convertLead(string leadId, string contactId, string accountId, bool overWriteLeadSource,
bool doNotCreateOpportunity, string opportunityName, string convertedStatus, bool sendEmailToOwner) {
sforce.LeadConvert leadConvert = new sforce.LeadConvert();
leadConvert.leadId = leadId;
leadConvert.contactId = contactId;
convertLead
leadConvert.doNotCreateOpportunity = doNotCreateOpportunity;
leadConvert.opportunityName = opportunityName;
leadConvert.convertedStatus = convertedStatus;
leadConvert.sendNotificationEmail = sendEmailToOwner;
sforce.LeadConvertResult[] lcr = null;
try {
lcr = binding.convertLead(new sforce.LeadConvert[] {leadConvert});
for (int i=0;i<lcr.Length;i++)
Console.WriteLine("The conversion failed because: " + lcr[i].errors[0].message);
} }
catch (Exception e) {
Console.WriteLine("Unexpected error encountered:\n\n" + e.Message);
return false;
}
return true;
}
LeadConvert Arguments
This call accepts an array of LeadConvert objects (100 maximum). A LeadConvert object contains the following properties.
Description Type
Name
ID of the Account into which the lead will be merged. Required only when updating an existing account. If no accountID is specified, then ID
accountId
the Apex Web service 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.
ID of the Contact into which the lead will be merged (this contact must be associated with the specified accountId, and an accountId ID
contactId
must be specified). Required only when updating an existing contact.
If no contactID is specified, then the Apex Web service 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). For information on IDs, see ID Field Type.
convertLead
Description Type
Name
Valid LeadStatus value for a converted lead. Required. To obtain the list of possible values, the client application queries the LeadStatus object, as in:
Select Id, MasterLabel
from LeadStatus where IsConverted=true string
convertedStatus
Specifies whether to create an Opportunity during lead conversion (false, the default) or not (true). Set this flag to true only if you boolean
doNotCreateOpportunity
do not want to create an opportunity from the lead. An opportunity is created by default.
ID of the Lead to convert. Required. For information on IDs, see ID Field Type.
ID leadId
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 string
opportunityName
of this field is 80 characters. If doNotCreateOpportunity argument is true, then no Opportunity is created and this field must be left blank; otherwise, an error is returned.
Specifies whether to overwrite the LeadSource field on the target Contact object with the contents of the LeadSource field in the source boolean
overwriteLeadSource
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.
Specifies the ID of the person to own any newly created account, contact, and opportunity. If the client application does not specify this ID
ownerId
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 Apex Web service does not overwrite the ownerId field in an existing account or contact. For information on IDs, see ID Field Type.
Specifies whether to send a notification email to the owner specified in the ownerId (true) or not (false, the default).
boolean sendNotificationEmail
Response
LeadConvertResult[]
convertLead
Fault
UnexpectedErrorFault