Newer Version Available
Lead
Represents a prospect or potential Opportunity.
Supported Calls
create(), delete(), describeLayout(), describeSObjects(), getDeleted(), getUpdated(), merge(), query(), retrieve(), search(), undelete(), update(), upsert()
Fields
| Field | Details |
|---|---|
| Address |
|
| AnnualRevenue |
|
| City |
|
| CleanStatus |
|
| Company |
|
| CompanyDunsNumber |
|
| ConnectionReceivedId | |
| ConnectionSentId |
|
| ConvertedAccountId |
|
| ConvertedContactId |
|
| ConvertedDate |
|
| ConvertedOpportunityId |
|
| Country |
|
| CountryCode |
|
| CurrencyIsoCode |
|
| Description |
|
| Division |
|
|
|
| EmailBouncedDate |
|
| EmailBouncedReason |
|
| Fax |
|
| FirstName |
|
| HasOptedOutOfEmail |
|
| GeocodeAccuracy |
|
| Industry |
|
| IsConverted |
|
| IsDeleted |
|
| IsUnreadByOwner |
|
| Jigsaw |
|
| LastActivityDate |
|
| LastName |
|
| LastReferencedDate |
|
| LastViewedDate |
|
| Latitude | |
| Longitude | |
| LeadSource |
|
| MasterRecordId |
|
| MiddleName |
|
| MobilePhone |
|
| Name |
|
| NumberOfEmployees |
|
| OwnerId |
|
| PartnerAccountId | |
| Phone |
|
| PhotoUrl |
|
| PostalCode |
|
| Rating |
|
| RecordTypeId |
|
| Salutation |
|
| State |
|
| StateCode |
|
| Status |
|
| Street |
|
| Suffix |
|
| Title |
|
| Website |
|
Converted Leads
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 user interface. Once a lead has been converted, it is read-only. You can’t update or delete a converted lead. However, you can query 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 have not been viewed or edited by the lead owner. In the user interface, this is helpful for users to know which leads have been assigned to them but which they have not touched yet. IsUnreadByOwner 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.
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
To update a Lead or to convert one with convertLead(), your client application must log 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 User records based on assignment rules that have been configured in the 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 create or update:
Java Sample
The following Java sample shows how to automatically assign a newly created lead.
1package wsc;
2
3import com.sforce.soap.enterprise.Connector;
4import com.sforce.soap.enterprise.EnterpriseConnection;
5import com.sforce.ws.ConnectionException;
6import com.sforce.ws.ConnectorConfig;
7import com.sforce.soap.enterprise.sobject.Lead;
8import com.sforce.soap.enterprise.QueryResult;
9import com.sforce.soap.enterprise.SaveResult;
10import com.sforce.soap.enterprise.sobject.SObject;
11
12public class LeadAssignment {
13
14 static final String USERNAME = "REPLACE USER NAME";
15 static final String PASSWORD = "REPLACE PASSWORD";
16 static EnterpriseConnection connection;
17
18 static LeadAssignment _leadAssignment;
19
20 // Main
21 public static void main(String[] args)
22 {
23 // Establish connection and login
24 ConnectorConfig config = new ConnectorConfig();
25 config.setUsername(USERNAME);
26 config.setPassword(PASSWORD);
27 try {
28 connection = Connector.newConnection(config);
29 System.out.println("Logged in, endpoint: " + config.getAuthEndpoint());
30 } catch (ConnectionException e1) {
31 e1.printStackTrace();
32 }
33
34 // Create lead
35 _leadAssignment = new LeadAssignment();
36 try {
37 _leadAssignment.CreateLead();
38 } catch (Exception e) {
39 e.printStackTrace();
40 }
41
42 // Logout
43 try {
44 connection.logout();
45 System.out.println("Logged out");
46 } catch (ConnectionException ce) {
47 ce.printStackTrace();
48 }
49 }
50
51 public void CreateLead() throws ConnectionException
52 {
53 // Create a new Lead and assign various properties
54 Lead lead = new Lead();
55
56 lead.setFirstName("Joe");
57 lead.setLastName("Smith");
58 lead.setCompany("ABC Corporation");
59 lead.setLeadSource("API");
60 // The lead assignment rule will assign any new leads that
61 // have "API" as the LeadSource to a particular user
62
63 // In this sample we will look for a particular rule and if found
64 // use the id for the lead assignment. If it is not found we will
65 // instruct the call to use the current default rule. You can't use
66 // both of these values together.
67 QueryResult qr = connection.query("SELECT Id FROM AssignmentRule WHERE Name = " +
68 "'Mass Mail Campaign' AND SobjectType = 'Lead'");
69 if (qr.getSize() == 0) {
70 connection.setAssignmentRuleHeader(null, true);
71 } else {
72 connection.setAssignmentRuleHeader(qr.getRecords()[0].getId(), false);
73 }
74
75 // Every operation that results in a new or updated lead will
76 // use the specified rule until the header is removed from the
77 // connection.
78 SaveResult[] sr = connection.create(new SObject[] {lead});
79 for (int i=0;i<sr.length;i++) {
80 if (sr[i].isSuccess()) {
81 System.out.println("Successfully created lead with id of: " +
82 sr[i].getId() + ".");
83 } else {
84 System.out.println("Error creating lead: " +
85 sr[i].getErrors()[0].getMessage());
86 }
87 }
88
89 // This call effectively removes the header, the next lead will
90 // be assigned to the default lead owner.
91 connection.clearAssignmentRuleHeader();
92 }
93}C# Sample
The following C# sample shows how to automatically assign a newly created lead.
1using System;
2using System.Collections.Generic;
3using System.Linq;
4using System.Text;
5using System.Threading.Tasks;
6using System.ServiceModel;
7using LeadSample.sforce;
8
9namespace LeadSample
10{
11 class LeadAssignment
12 {
13 private static SoapClient client;
14 private static SoapClient apiClient;
15 private static SessionHeader header;
16 private static LoginResult loginResult;
17 private static readonly string Username = "REPLACE USERNAME";
18 private static readonly string Password = "REPLACE PASSWORD AND SECURITY TOKEN";
19
20 // Create the proxy binding and login
21 private LeadAssignment()
22 {
23 client = new SoapClient();
24
25 try
26 {
27 loginResult = client.login(null, Username, Password);
28 }
29 catch (Exception e)
30 {
31 Console.WriteLine("Unexpected login error: " + e.Message);
32 Console.WriteLine(e.StackTrace);
33 return;
34 }
35 // Access API endpoint and create new client
36 header = new SessionHeader();
37 header.sessionId = loginResult.sessionId;
38 apiClient = new SoapClient("Soap", loginResult.serverUrl);
39 }
40
41 [STAThread]
42 static void Main(string[] args)
43 {
44 LeadAssignment leadAssignment = new LeadAssignment();
45 try
46 {
47 leadAssignment.CreateLead();
48 }
49 catch (Exception e)
50 {
51 Console.WriteLine(e.Message);
52 Console.WriteLine(e.StackTrace);
53 Console.WriteLine(e.InnerException);
54 }
55 // logout
56 client.logout(header);
57 }
58
59 public void CreateLead()
60 {
61 // Create a new Lead and assign various properties
62 Lead lead = new Lead();
63
64 lead.FirstName = "John";
65 lead.LastName = "Brown";
66 lead.Company = "ABC Corporation";
67 lead.LeadSource = "Advertisement";
68 // Setting the lead source for a pre-existing lead assignment rule. This
69 // rule was created outside of this sample and will assign any new leads
70 // that have "Advertisement" as the LeadSource to a particular user.
71
72 // Create the assignment rule header and add it to the proxy binding
73 AssignmentRuleHeader arh = new AssignmentRuleHeader();
74
75 // In this sample we will look for a particular rule and if found
76 // use the id for the lead assignment. If it is not found we will
77 // instruct the call to use the current default rule. Both these
78 // values can't be used together.
79 QueryResult qr = null;
80 string query = "SELECT Id FROM AssignmentRule WHERE Name = " +
81 "'Mass Mail Campaign' AND SobjectType = 'Lead'";
82 try
83 {
84 LimitInfo[] limitArray = apiClient.query(
85 header, // sessionheader
86 null, // queryoptions
87 null, // mruheader
88 null, // packageversionheader
89 query, // SOQL query
90 out qr);
91 }
92 catch (Exception e)
93 {
94 Console.WriteLine("Unexpected query error: " + e.Message);
95 Console.WriteLine(e.StackTrace);
96 }
97 if (qr.size == 0)
98 {
99 arh.useDefaultRule = true;
100 }
101 else
102 {
103 arh.assignmentRuleId = qr.records[0].Id;
104 }
105
106 // Create the lead using our Assignment Rule header
107 LimitInfo[] li;
108 SaveResult[] sr;
109 apiClient.create(
110 header, // sessionheader
111 arh, // assignmentruleheader
112 null, // mruheader
113 null, // allowfieldtrunctionheader
114 null, // disablefeedtrackingheader
115 null, // streamingenabledheader
116 null, // allornoneheader
117 null, // duplicateruleheader
118 null, // localeoptions
119 null, // debuggingheader
120 null, // packageversionheader
121 null, // emailheader
122 new sObject[] { lead },
123 out li,
124 out sr);
125 foreach (SaveResult s in sr)
126 {
127 if (s.success)
128 {
129 Console.WriteLine("Successfully created Lead with ID: {0}", s.id);
130 }
131 else
132 {
133 Console.WriteLine("Error creating Lead: {0}", s.errors[0].message);
134 }
135 }
136 }
137 }
138}