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 |
|
| 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.
1swfobject.registerObject("clippy.codeblock-0", "9");
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17package com.doc.samples;
18import java.net.MalformedURLException;
19import java.net.URL;
20import java.rmi.RemoteException;
21import javax.xml.rpc.ServiceException;
22
23import com.sforce.soap.enterprise.LoginResult;
24import com.sforce.soap.enterprise.QueryResult;
25import com.sforce.soap.enterprise.SaveResult;
26import com.sforce.soap.enterprise.SforceServiceLocator;
27import com.sforce.soap.enterprise.SoapBindingStub;
28import com.sforce.soap.enterprise._AssignmentRuleHeader;
29import com.sforce.soap.enterprise._SessionHeader;
30import com.sforce.soap.enterprise.fault.LoginFault;
31import com.sforce.soap.enterprise.fault.UnexpectedErrorFault;
32import com.sforce.soap.enterprise.sobject.Lead;
33import com.sforce.soap.enterprise.sobject.SObject;
34
35public class LeadAssignment
36{
37
38 static LeadAssignment _leadAssignment;
39
40 public static void main(String[] args)
41 {
42 _leadAssignment = new LeadAssignment();
43 try {
44 _leadAssignment.CreateLead();
45 } catch (Exception e) {
46 e.printStackTrace();
47 }
48 }
49
50 public void CreateLead() throws UnexpectedErrorFault, LoginFault,
51 RemoteException, ServiceException
52 {
53 //Create the proxy binding and login
54 SoapBindingStub binding = (SoapBindingStub) new SforceServiceLocator().getSoap();
55 LoginResult lr = binding.login("user@domain.net", "secret");
56
57 //Reset the binding to use the endpoint returned from login
58 binding._setProperty(SoapBindingStub.ENDPOINT_ADDRESS_PROPERTY,
59 lr.getServerUrl());
60
61 //Create the session id header, and add it to the proxy binding
62 _SessionHeader sh = new _SessionHeader();
63 sh.setSessionId(lr.getSessionId());
64 binding.setHeader(
65 new SforceServiceLocator().getServiceName().getNamespaceURI(),
66 "SessionHeader", sh );
67
68 //Create a new case and assign various properties
69 Lead lead = new Lead();
70
71 lead.setFirstName("Joe");
72 lead.setLastName("Smith");
73 lead.setCompany("ABC Corporation");
74 lead.setLeadSource("API");
75 //The lead assignment rule will assign any new leads that
76 //have "API" as the LeadSource to a particular user
77
78 //Create the assignment rule header and add it to the proxy binding
79 _AssignmentRuleHeader arh = new _AssignmentRuleHeader();
80
81 //In this sample we will look for a particular rule and if found
82 //use the id for the lead assignment. If it is not found we will
83 //instruct the call to use the current default rule. You can't use
84 //both of these values together.
85 QueryResult qr = binding.query("Select Id From AssignmentRule where Name = " +
86 "'Mass Mail Campaign' and RuleType = 'leadAssignment'");
87 if (qr.getSize() == 0) {
88 arh.setUseDefaultRule(new Boolean(true));
89 } else {
90 arh.setAssignmentRuleId(qr.getRecords(0).getId());
91 }
92
93 binding.setHeader(
94 new SforceServiceLocator().getServiceName().getNamespaceURI(),
95 "AssignmentRuleHeader", arh);
96
97 // Every operation that results in a new or updated case, will
98 // use the specified rule until the header is removed from the
99 // proxy binding.
100 SaveResult[] sr = binding.create(new SObject[] {lead});
101 for (int i=0;i<sr.length;i++) {
102 if (sr[i].isSuccess()) {
103 System.out.println("Successfully created lead with id of: " +
104 sr[i].getId().getValue() + ".");
105 }
106 else {
107 System.out.println("Error creating lead: " +
108 sr[i].getErrors(0).getMessage());
109 }
110 }
111
112 // This call effectively removes the header, the next lead will
113 // be assigned to the default lead owner. Remember to add the
114 // session header back in.
115 binding.clearHeaders();
116 binding.setHeader(
117 new SforceServiceLocator().getServiceName().getNamespaceURI(),
118 "SessionHeader", sh);
119
120 }
121}C# Sample
The following C# sample shows how to automatically assign a newly created lead.
1swfobject.registerObject("clippy.codeblock-1", "9");
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17using System;
18using System.Collections.Generic;
19using System.Text;
20using LeadAssignment.sforce;
21
22namespace LeadAssignment
23{
24 class LeadAssignment
25 {
26 private SforceService binding;
27
28 private static readonly string Username = "ENTERUSERNAME";
29 private static readonly string Password = "ENTERPASSWORD";
30
31 /// <summary>
32 /// Create the proxy binding and login
33 /// </summary>
34 private LeadAssignment()
35 {
36 this.binding = new SforceService();
37 LoginResult lr = binding.login(LeadAssignment.Username, LeadAssignment.Password);
38
39 // Reset the binding to use the endpoint returned from login
40 this.binding.Url = lr.serverUrl;
41
42 // Create the session ID header and add it to the proxy binding
43 this.binding.SessionHeaderValue = new SessionHeader();
44 this.binding.SessionHeaderValue.sessionId = lr.sessionId;
45 }
46
47 [STAThread]
48 static void Main(string[] args)
49 {
50 LeadAssignment leadAssignment = new LeadAssignment();
51 try
52 {
53 leadAssignment.CreateLead();
54 }
55 catch (Exception e)
56 {
57 Console.WriteLine(e.Message);
58 Console.WriteLine(e.StackTrace);
59 Console.WriteLine(e.InnerException);
60 }
61 }
62
63 public void CreateLead()
64 {
65 // Create a new Lead and assign various properties
66 Lead lead = new Lead();
67
68 lead.FirstName = "John";
69 lead.LastName = "Brown";
70 lead.Company = "ABC Corporation";
71 lead.LeadSource = "Advertisement";
72 // Setting the lead source for a pre-existing lead assignment rule. This
73 // rule was created outside of this sample and will assign any new leads
74 // that have "Advertisement" as the LeadSource to a particular user
75
76 // Create the assignment rule header and add it to the proxy binding
77 AssignmentRuleHeader arh = new AssignmentRuleHeader();
78
79 // In this sample we will look for a particular rule and if found
80 // use the id for the lead assignment. If it is not found we will
81 // instruct the call to use the current default rule. Both these
82 // values can't be used together.
83 QueryResult qr = binding.query("Select Id from AssignmentRule where Name = " +
84 "'Mass Mail Campaign' and SobjectType = 'lead'");
85 if (qr.size == 0)
86 {
87 arh.useDefaultRule = true;
88 }
89 else
90 {
91 arh.assignmentRuleId = qr.records[0].Id;
92 }
93 binding.AssignmentRuleHeaderValue = arh;
94
95 // Every operation that results in a new or updated lead will use the
96 // specified rule until the header is removed from the proxy binding
97 SaveResult[] sr = binding.create(new sObject[] { lead });
98 foreach (SaveResult s in sr)
99 {
100 if (s.success)
101 {
102 Console.WriteLine("Successfully created Lead with ID: {0}", s.id);
103 }
104 else
105 {
106 Console.WriteLine("Error creating Lead: {0}", s.errors[0].message);
107 }
108 }
109
110 // This call effectively removes the header. The next lead will be assigned
111 // to the default lead owner.
112 binding.AssignmentRuleHeaderValue = null;
113 }
114 }
115}
116