Represents a prospect or potential Opportunity.
convertLead(), create(), update(), delete(), query(), search(), retrieve(), getDeleted(), getUpdated(), describeSObjects(), merge(), upsert()
| Field | Field Type | Field Properties | Description |
|---|---|---|---|
| AnnualRevenue | currency | Create | Annual revenue for the company of the lead. |
| City | string | Create | City for the address of the lead. |
| Company | string | Create | Required. Company of the lead. |
| ConnectionReceivedID | reference | Filter | ID of the PartnerNetworkConnection that shared this record with your organization. This field is only available if you have enabled Salesforce to Salesforce. |
| ConnectionSentID | reference | Filter | ID of the PartnerNetworkConnection that you shared this record with. This field is only available if you have enabled Salesforce to Salesforce. |
| ConvertedAccountId | reference | Filter | Object reference ID that points to the Account into which the Lead has been converted. For information on IDs, see ID Field Type. |
| ConvertedContactId | reference | Filter | Object reference ID that points to the Contact into which the Lead has been converted. |
| ConvertedDate | date | Filter | Date on which this Lead was converted. |
| ConvertedOpportunityId | reference | Filter | Object reference ID that points to the Opportunity into which the Lead has been converted. |
| Country | string | Create | Country for the address of the lead. |
| Description | textarea | Create | Description of the lead. |
| Create | Email address for the lead. | ||
| EmailBouncedDate | dateTime | Filter | If bounce management is activated and an email sent to the lead bounced, the date and time the bounce occurred. |
| EmailBouncedReason | string | Filter | If bounce management is activated and an email sent to the lead bounced, the reason the bounce occurred. |
| Fax | phone | Create | Fax number for the lead. |
| FirstName | string | Create | First name of the lead. Limited to 40 characters. |
| HasOptedOutOfEmail | boolean | Create | Indicates whether the lead has opted out of email (true) or not (false). Label is Email Opt Out. |
| Industry | picklist | Create | Industry the lead works in. |
| IsConverted | boolean | Create | Indicates whether the Lead has been converted (true) or not (false). Label is Converted. |
| IsDeleted | boolean | Defaulted on create |
Indicates whether the object has been moved to the Recycle Bin (true) or not (false). Label is Deleted. |
| IsUnreadByOwner | boolean | Create | If true, lead has been assigned, but not yet viewed. See Unread Leads for more information. Label is Unread By Owner. |
| LastActivityDate | date | Filter |
Value is one of the following, whichever is the most recent:
|
| LastName | string | Create | Required. Last name of the lead. Limited to 80 characters. |
| LeadSource | picklist | Create | Source from which the lead was obtained. |
| masterRecordId | reference | Filter | If this object was deleted as the result of a merge, this field contains the ID of the record that was kept. If this object was deleted for any other reason, or has not been deleted, the value is null. |
| MobilePhone | phone | Create | Mobile phone number for the lead. |
| Name | string | Filter | Concatenation of FirstName and LastName. Limited to 121 characters. |
| NumberOfEmployees | int | Create | Number of employees at the lead’s company. Label is Employees. |
| OwnerId | reference | Create | ID of the owner of the lead. |
| Phone | phone | Create | Phone number for the lead. |
| PostalCode | string | Create | Postal code for the address of the lead. Label is Zip/Postal Code. |
| Rating | picklist | Create | Rating of the lead. |
| Salutation | picklist | Create | Salutation for the lead. |
| State | string | Create | State for the address of the lead. |
| Status | picklist | Create | Status code for this converted lead. Status codes are defined in the lead status picklist and represented in the API by the LeadStatus object. See Lead Status Picklist for more information. |
| Street | textarea | Create | Street number and name for the address of the lead. |
| Title | string | Create | Title for the lead, for example CFO or CEO. |
| Website | url | Create | Website for the lead. |
Leads have a special state to indicate that they have been converted into an Account, Contact, and optionally, an Opportunity. Your client application can convert leads via the convertLead() call. Users can also convert leads through the Salesforce user interface. Once a lead has been converted, it is read-only. You cannot update() or delete() a converted lead. However, you can query converted Leads using the query() call.
Leads have several fields that indicate their converted status. These special fields are read-only via the API. You cannot set these fields directly; they are set when converting the lead in the Salesforce user interface. The fields are:
Leads have a special state to indicate that they have not been viewed or edited by the lead owner. In the Salesforce user interface, this is helpful for users to know which leads have been assigned to them but which they have not touched yet. The IsUnreadByOwner field is true if the lead owner has not yet viewed or edited the lead, and false if the lead owner has viewed or edited the lead at least once.
Each Status value corresponds to either a converted or unconverted status in the lead status picklist, as defined in the Salesforce user interface. To obtain the lead status values in the picklist, a client application can invoke the query() call on the LeadStatus object.
You cannot convert a lead via the API by changing the Status field 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 to assign to the lead. Leads with a “converted” status type are no longer available in the Leads tab, although you can include them in reports.
To update() a Lead or call convertLead(), your client application must be logged in with the “Edit” permission on leads.
When you create(), update(), or upsert() a lead, your client application can have the lead automatically assigned to one or more Users based on assignment rules that have been configured in the Salesforce user interface.
To use this feature, your client application needs to set either of the following options (but not both) in the AssignmentRuleHeader used in the create() or update() call:
| Field | Field Type | Description |
|---|---|---|
| assignmentRuleId | reference | ID of the assignment rule to use. Can be an inactive assignment
rule. If unspecified and useDefaultRule is true, then the default assignment
rule is used. To find the ID for a given assignment rule, you query the AssignmentRule object (specifying RuleType="leadAssignment"), iterate through the returned AssignmentRule objects, find the one you want to use, retrieve its ID, and then specify its ID in this field in the AssignmentRuleHeader. For information on IDs, see ID Field Type. |
| useDefaultRule | boolean | Specifies whether to use the default rule for rule-based assignment (true) or not (false). The default rule is assigned by users in the Salesforce user interface. |
The following example shows how to automatically assign a newly created lead.
package com.sforce;
import java.net.MalformedURLException;
import java.net.URL;
import java.rmi.RemoteException;
import com.sforce.soap.enterprise.LoginResult;
import com.sforce.soap.enterprise.QueryResult;
import com.sforce.soap.enterprise.SaveResult;
import com.sforce.soap.enterprise.SforceServiceLocator;
import com.sforce.soap.enterprise.SoapBindingStub;
import com.sforce.soap.enterprise._AssignmentRuleHeader;
import com.sforce.soap.enterprise._SessionHeader;
import com.sforce.soap.enterprise.fault.LoginFault;
import com.sforce.soap.enterprise.fault.UnexpectedErrorFault;
import com.sforce.soap.enterprise.sobject.Lead;
import com.sforce.soap.enterprise.sobject.SObject;
public class LeadAssignment {
static LeadAssignment _leadAssignment;
public static void main(String[] args) {
_leadAssignment = new LeadAssignment();
try {
_leadAssignment.CreateLead();
} catch (Exception e) {
e.printStackTrace();
}
}
public void CreateLead() throws UnexpectedErrorFault, LoginFault,
RemoteException {
//Create the proxy binding and login
SoapBindingStub binding = (SoapBindingStub) new SforceServiceLocator().getSoap();
LoginResult lr = binding.login("user@domain.net", "secret");
//Reset the binding to use the endpoint returned from login
binding._setProperty(SoapBindingStub.ENDPOINT_ADDRESS_POINT,
loginResult.getServerUrl());
//Create the session id header, and add it to the proxy binding
_SessionHeader sh = new _SessionHeader();
sh.setSessionId(lr.getSessionId());
binding.setHeader(new SforceServiceLocator().getServiceName().getNamespaceURI(),
"SessionHeader", sh);
//Create a new case 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
//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. You cannot use
//both of these values together.
QueryResult qr = binding.query("Select Id From AssignmentRule where Name =
'Mass Mail Campaign' and RuleType = 'leadAssignment'");
if (qr.getSize() == 0) {
arh.setUseDefaultRule(new Boolean(true));
} else {
arh.setAssignmentRuleId(qr.getRecords(0).getId());
}
binding.setHeader(new
SforceServiceLocator().getServiceName().getNamespaceURI(), "AssignmentRuleHeader",
arh);
// Every operation that results in a new or updated case, will
// use the specified rule until the header is removed from the
// proxy binding.
SaveResult[] sr = binding.create(new SObject[] {lead});
for (int i=0;i<sr.length;i++) {
if (sr[i].isSuccess())
System.out.println("Successfully creaeted lead with id of: " +
sr[i].getId().getValue() + ".");
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. Remember to add the
// session header back in.
binding.clearHeaders();
binding.setHeader(new
SforceServiceLocator().getServiceName().getNamespaceURI(), "SessionHeader", sh);
}
}