Supported Calls
create(), delete(), describeLayout(), describeSObjects(), getDeleted(), getUpdated(), merge(), query(), retrieve(), search(), undelete(), update(), upsert()
Fields
| Field | Details |
|---|---|
| ActionCadenceAssigneeId |
|
| ActionCadenceId |
|
| ActionCadenceState |
|
| ActiveTrackerCount |
|
| ActivityMetricId |
|
| ActivityMetricRollupId |
|
| Address |
|
| AnnualRevenue |
|
| City |
|
| CleanStatus |
|
| Company |
|
| CompanyDunsNumber |
|
| ConvertedAccountId |
|
| ConvertedContactId |
|
| ConvertedDate |
|
| ConvertedOpportunityId |
|
| ConnectionReceivedId | |
| ConnectionSentId |
|
| Country |
|
| CountryCode |
|
| CurrencyIsoCode |
|
| DandBCompanyId |
|
| Description |
|
| Division |
|
|
|
| EmailBouncedDate |
|
| EmailBouncedReason |
|
| ExportStatus |
|
| Fax |
|
| FirstCallDateTime |
|
| FirstEmailDateTime |
|
| FirstName |
|
| GeocodeAccuracy |
|
| GenderIdentity |
|
| HasOptedOutOfEmail |
|
| HasOptedOutOfFax |
|
| IndividualId |
|
| Industry |
|
| IsConverted |
|
| IsDeleted |
|
| IsPriorityRecord |
|
| IsUnreadByOwner |
|
| Jigsaw |
|
| JigsawContactId |
|
| LastActivityDate | |
| LastName |
|
| LastReferencedDate |
|
| LastViewedDate |
|
| Latitude |
|
| LeadSource |
|
| Longitude |
|
| MasterRecordId |
|
| MiddleName |
|
| MobilePhone |
|
| Name |
|
| NumberOfEmployees |
|
| OwnerId |
|
| PartnerAccountId |
|
| Phone |
|
| PhotoUrl |
|
| PostalCode |
|
| Pronouns |
|
| Rating |
|
| RecordTypeId |
|
| Salutation |
|
| ScheduledResumeDateTime |
|
| ScoreIntelligenceId |
|
| State |
|
| StateCode |
|
| Status |
|
| Street |
|
| Suffix |
|
| Title |
|
| Website |
|
Note
When importing lead data, users need the Set Audit Fields upon Record Creation permission to assign values to audit fields such as CreatedDate. Audit fields are automatically updated during API operations unless you set these fields yourself.
Converted Leads
Leads have a special state to indicate that they’ve been converted into an account, a contact, and an opportunity. Your client application can convert leads via the convertLead() call. Users can also convert leads in Salesforce. After a lead has been converted, it’s read only. However, you can query converted lead records. Only users with the View and Edit Converted Leads permission can update converted lead records.
Leads have several fields that indicate their converted status. These special fields are set when converting the lead in the user interface.
- ConvertedAccountId
- ConvertedContactId
- ConvertedDate
- ConvertedOpportunityId
- IsConverted
- Status
Unread Leads
Leads have a special state to indicate that they haven’t been viewed or edited by the lead owner. In Salesforce, it’s helpful for users to know which leads have been assigned to them but that they haven’t touched yet. IsUnreadByOwner is true if the lead owner hasn’t yet viewed or edited the lead, and false if the lead owner has viewed or edited the lead at least one time.
Lead Status Picklist
Each Status value corresponds to either a converted or unconverted status in the lead status picklist, as defined in the user interface. To obtain the lead status values in the picklist, a client application can query LeadStatus.
You can't convert a lead via the API by changing Status to one of the converted lead status values. When you convert qualified leads into an account, contact, and opportunity, you can select one of the converted status types for the lead. Leads with a converted status type are no longer available in the Leads tab, although you can include them in reports.
Usage
If lead data is imported and you need to set the value for an audit field, such as CreatedDate, contact Salesforce Support. Audit fields are automatically updated during API operations unless you request to set these fields yourself.
To update a lead or to convert one with convertLead(), log in to your client application with the Edit permission on leads.
When you create, update, or upsert a lead, your client application can have the lead assigned to multiple user records based on assignment rules that have been configured in Salesforce.
To use this feature, your client application needs to set either of these options (but not both) in the AssignmentRuleHeader used in create or update:
Java Sample
The following Java sample shows how to automatically assign a newly created lead.
package wsc; import com.sforce.soap.enterprise.Connector; import com.sforce.soap.enterprise.EnterpriseConnection; import com.sforce.ws.ConnectionException; import com.sforce.ws.ConnectorConfig; import com.sforce.soap.enterprise.sobject.Lead; import com.sforce.soap.enterprise.QueryResult; import com.sforce.soap.enterprise.SaveResult; import com.sforce.soap.enterprise.sobject.SObject; public class LeadAssignment { static final String USERNAME = "REPLACE USER NAME"; static final String PASSWORD = "REPLACE PASSWORD"; static EnterpriseConnection connection; static LeadAssignment _leadAssignment; // Main public static void main(String[] args) { // Establish connection and login ConnectorConfig config = new ConnectorConfig(); config.setUsername(USERNAME); config.setPassword(PASSWORD); try { connection = Connector.newConnection(config); System.out.println("Logged in, endpoint: " + config.getAuthEndpoint()); } catch (ConnectionException e1) { e1.printStackTrace(); } // Create lead _leadAssignment = new LeadAssignment(); try { _leadAssignment.CreateLead(); } catch (Exception e) { e.printStackTrace(); } // Logout try { connection.logout(); System.out.println("Logged out"); } catch (ConnectionException ce) { ce.printStackTrace(); } } public void CreateLead() throws ConnectionException { // Create a new Lead and assign various properties Lead lead = new Lead(); lead.setFirstName("Joe"); lead.setLastName("Smith"); lead.setCompany("ABC Corporation"); lead.setLeadSource("API"); // The lead assignment rule will assign any new leads that // have "API" as the LeadSource to a particular user // In this sample we will look for a particular rule and if found // use the id for the lead assignment. If it is not found we will // instruct the call to use the current default rule. You can't use // both of these values together. QueryResult qr = connection.query("SELECT Id FROM AssignmentRule WHERE Name = " + "'Mass Mail Campaign' AND SobjectType = 'Lead'"); if (qr.getSize() == 0) { connection.setAssignmentRuleHeader(null, true); } else { connection.setAssignmentRuleHeader(qr.getRecords()[0].getId(), false); } // Every operation that results in a new or updated lead will // use the specified rule until the header is removed from the // connection. SaveResult[] sr = connection.create(new SObject[] {lead}); for (int i=0;i<sr.length;i++) { if (sr[i].isSuccess()) { System.out.println("Successfully created lead with id of: " + sr[i].getId() + "."); } else { System.out.println("Error creating lead: " + sr[i].getErrors()[0].getMessage()); } } // This call effectively removes the header, the next lead will // be assigned to the default lead owner. connection.clearAssignmentRuleHeader(); } }
C# Sample
The following C# sample shows how to automatically assign a newly created lead.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.ServiceModel;
using LeadSample.sforce;
namespace LeadSample
{
class LeadAssignment
{
private static SoapClient client;
private static SoapClient apiClient;
private static SessionHeader header;
private static LoginResult loginResult;
private static readonly string Username = "REPLACE USERNAME";
private static readonly string Password = "REPLACE PASSWORD AND SECURITY TOKEN";
// Create the proxy binding and login
private LeadAssignment()
{
client = new SoapClient();
try
{
loginResult = client.login(null, Username, Password);
}
catch (Exception e)
{
Console.WriteLine("Unexpected login error: " + e.Message);
Console.WriteLine(e.StackTrace);
return;
}
// Access API endpoint and create new client
header = new SessionHeader();
header.sessionId = loginResult.sessionId;
apiClient = new SoapClient("Soap", loginResult.serverUrl);
}
[STAThread]
static void Main(string[] args)
{
LeadAssignment leadAssignment = new LeadAssignment();
try
{
leadAssignment.CreateLead();
}
catch (Exception e)
{
Console.WriteLine(e.Message);
Console.WriteLine(e.StackTrace);
Console.WriteLine(e.InnerException);
}
// logout
client.logout(header);
}
public void CreateLead()
{
// Create a new Lead and assign various properties
Lead lead = new Lead();
lead.FirstName = "John";
lead.LastName = "Brown";
lead.Company = "ABC Corporation";
lead.LeadSource = "Advertisement";
// Setting the lead source for a pre-existing lead assignment rule. This
// rule was created outside of this sample and will assign any new leads
// that have "Advertisement" as the LeadSource to a particular user.
// Create the assignment rule header and add it to the proxy binding
AssignmentRuleHeader arh = new AssignmentRuleHeader();
// In this sample we will look for a particular rule and if found
// use the id for the lead assignment. If it is not found we will
// instruct the call to use the current default rule. Both these
// values can't be used together.
QueryResult qr = null;
string query = "SELECT Id FROM AssignmentRule WHERE Name = " +
"'Mass Mail Campaign' AND SobjectType = 'Lead'";
try
{
LimitInfo[] limitArray = apiClient.query(
header, // sessionheader
null, // queryoptions
null, // mruheader
null, // packageversionheader
query, // SOQL query
out qr);
}
catch (Exception e)
{
Console.WriteLine("Unexpected query error: " + e.Message);
Console.WriteLine(e.StackTrace);
}
if (qr.size == 0)
{
arh.useDefaultRule = true;
}
else
{
arh.assignmentRuleId = qr.records[0].Id;
}
// Create the lead using our Assignment Rule header
LimitInfo[] li;
SaveResult[] sr;
apiClient.create(
header, // sessionheader
arh, // assignmentruleheader
null, // mruheader
null, // allowfieldtrunctionheader
null, // disablefeedtrackingheader
null, // streamingenabledheader
null, // allornoneheader
null, // duplicateruleheader
null, // localeoptions
null, // debuggingheader
null, // packageversionheader
null, // emailheader
new sObject[] { lead },
out li,
out sr);
foreach (SaveResult s in sr)
{
if (s.success)
{
Console.WriteLine("Successfully created Lead with ID: {0}", s.id);
}
else
{
Console.WriteLine("Error creating Lead: {0}", s.errors[0].message);
}
}
}
}
}
Associated Objects
This object has these associated objects. If the API version isn’t specified, they’re available in the same API versions as this object. Otherwise, they’re available in the specified API version and later.
- LeadChangeEvent (API version 44.0)
- Change events are available for the object.
- LeadFeed (API version 18.0)
- Feed tracking is available for the object.
- LeadHistory
- History is available for tracked fields of the object.
- LeadOwnerSharingRule
- Sharing rules are available for the object.
- LeadShare
- Sharing is available for the object.