Lead

Represents a prospect or lead.

Supported Calls

create(), delete(), describeLayout(), describeSObjects(), getDeleted(), getUpdated(), merge(), query(), retrieve(), search(), undelete(), update(), upsert()

Fields

Field Details
Address
Type
address
Properties
Filter, Nillable
Description
The compound form of the address. Read-only. For details on compound address fields, see Address Compound Fields.
AnnualRevenue
Type
currency
Properties
Create, Filter, Nillable, Sort, Update
Description
Annual revenue for the lead’s company.
City
Type
string
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
City for the lead’s address.
CleanStatus
Type
picklist
Properties
Create, Filter, Group, Nillable, Restricted picklist, Sort, Update
Description
Indicates the record’s clean status compared with Data.com. Values include: Matched, Different, Acknowledged, NotFound, Inactive, Pending, SelectMatch, or Skipped.
Several values for CleanStatus appear with different labels on the lead record.
  • Matched appears as In Sync
  • Acknowledged appears as Reviewed
  • Pending appears as Not Compared
Company
Type
string
Properties
Create, Filter, Group, Sort, Update
Description
Required. The lead’s company.
Note

Note

If person account record types have been enabled, and if the value of Company is null, the lead converts to a person account.

CompanyDunsNumber
Type
string
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The Data Universal Numbering System (D-U-N-S) number, which is a unique, nine-digit number assigned to every business location in the Dun & Bradstreet database that has a unique, separate, and distinct operation. Industries and companies use D-U-N-S numbers as a global standard for business identification and tracking. Maximum size is 9 characters.
Note

Note

This field is only available to organizations that use Data.com Prospector or Data.com Clean.

ConnectionReceivedId
Type
reference
Properties
Filter, Group, Nillable, Sort
Description
ID of the PartnerNetworkConnection that shared this record with your organization. This field is available if you enabled Salesforce to Salesforce.
ConnectionSentId
Type
reference
Properties
Filter, Group, Nillable, Sort
Description
ID of the PartnerNetworkConnection that you shared this record with. This field is available if you enabled Salesforce to Salesforce. This field is supported using API versions earlier than 15.0. In all other API versions, this field’s value is null. You can use the new PartnerNetworkRecordConnection object to forward records to connections.
ConvertedAccountId
Type
reference
Properties
Filter, Group, Nillable, Sort
Description
Object reference ID that points to the account into which the lead converted.
ConvertedContactId
Type
reference
Properties
Filter, Group, Nillable, Sort
Description
Object reference ID that points to the contact into which the lead converted.
ConvertedDate
Type
date
Properties
Filter, Group, Nillable, Sort
Description
Date on which this lead was converted.
ConvertedOpportunityId
Type
reference
Properties
Filter, Group, Nillable, Sort
Description
Object reference ID that points to the opportunity into which the lead has been converted.
Country
Type
string
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The lead’s country.
CountryCode
Type
picklist
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The ISO country code for the lead’s address.
CurrencyIsoCode
Type
picklist
Properties
Create, Defaulted on create, Filter, Group, Nillable, Restricted picklist, Sort, Update
Description
Available only for organizations with the multicurrency feature enabled. Contains the ISO code for any currency allowed by the organization.
Description
Type
textarea
Properties
Create, Nillable, Update
Description
The lead’s description.
Division
Type
picklist
Properties
Defaulted on create, Filter, Group, Restricted picklist, Sort
Description
A logical segment of your organization's data. For example, if your company is organized into different business units, you could create a division for each business unit, such as “North America,” “Healthcare,” or “Consulting.” Available only if the organization has the Division permission enabled.
Email
Type
email
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The lead’s email address.
EmailBouncedDate
Type
dateTime
Properties
Filter, Nillable, Sort, Update
Description
If bounce management is activated and an email sent to the lead bounced, the date and time of the bounce.
EmailBouncedReason
Type
string
Properties
Filter, Group, Nillable, Sort, Update
Description
If bounce management is activated and an email sent to the lead bounced, the reason for the bounce.
Fax
Type
phone
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The lead’s fax number.
FirstName
Type
string
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The lead’s first name up to 40 characters.
HasOptedOutOfEmail
Type
boolean
Properties
Create, Defaulted on create, Filter, Update
Description
Indicates whether the lead opted out of email (true) or not (false). Label is Email Opt Out.
GeocodeAccuracy
Type
picklist
Properties
Retrieve, Query, Restricted picklist, Nillable
Description
Accuracy level of the geocode for the address. For details on geolocation compound fields, see Compound Field Considerations and Limitations.
IndividualId
Type
reference
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
ID of the data privacy record associated with this lead. This field is available if you enabled Data Protection and Privacy in Setup.
Industry
Type
picklist
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
Industry in which the lead works.
IsConverted
Type
boolean
Properties
Create, Defaulted on create, Filter, Group, Sort
Description
Indicates whether the lead has been converted (true) or not (false). Label is Converted.
IsDeleted
Type
boolean
Properties
Defaulted on create, Filter
Description
Indicates whether the object has been moved to the Recycle Bin (true) or not (false). Label is Deleted.
IsUnreadByOwner
Type
boolean
Properties
Create, Defaulted on create, Filter, Group, Sort, Update
Description
If true, lead has been assigned, but not yet viewed. See Unread Leads for more information. Label is Unread By Owner.
Jigsaw
Type
string
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
References the ID of a contact in Data.com. If a lead has a value in this field, it means that a contact was imported as a lead from Data.com. If the contact (converted to a lead) was not imported from Data.com, the field value is null. Maximum size is 20 characters. Available in API version 22.0 and later. Label is Data.com Key.
Important

Important

The Jigsawfield is exposed in the API to support troubleshooting for import errors and reimporting of corrected data. Do not modify the value in the Jigsaw field.

LastActivityDate
Type
date
Properties
Filter, Group, Nillable, Sort
Description
Value is the most recent of either:
  • Due date of the most recent event logged against the record.
  • Due date of the most recently closed task associated with the record.
LastName
Type
string
Properties
Create, Filter, Group, Sort, Update
Description
Required. Last name of the lead up to 80 characters.
LastReferencedDate
Type
date
Properties
Filter, Nillable, Sort, Update
Description
The timestamp for when the current user last viewed a record related to this record.
LastViewedDate
Type
date
Properties
Filter, Nillable, Sort, Update
Description
The timestamp for when the current user last viewed this record. If this value is null, this record might only have been referenced (LastReferencedDate) and not viewed.
Latitude
Type
double
Properties
Create, Filter, Nillable, Sort, Update
Description
Used with Longitude to specify the precise geolocation of an address. Acceptable values are numbers between –90 and 90 up to 15 decimal places. For details on geolocation compound fields, see Compound Field Considerations and Limitations.
Longitude
Type
double
Properties
Create, Filter, Nillable, Sort, Update
Description
Used with Latitude to specify the precise geolocation of an address. Acceptable values are numbers between –180 and 180 up to 15 decimal places. For details on geolocation compound fields, see Compound Field Considerations and Limitations.
LeadSource
Type
picklist
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The lead’s source.
MasterRecordId
Type
reference
Properties
Filter, Group, Nillable, Sort
Description
If this record was deleted as the result of a merge, this field contains the ID of the record that was kept. If this record was deleted for any other reason, or has not been deleted, the value is null.
Note

Note

When using Apex triggers to determine which record was deleted in a merge event, this field’s value is the ID of the record that remains in Trigger.old. In Trigger.new, the value is null.

MiddleName
Type
string
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The lead’s middle name up to 40 characters. To enable this field, ask Salesforce Customer Support for help.
MobilePhone
Type
phone
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The lead’s mobile phone number.
Name
Type
string
Properties
Filter, Group, Sort
Description
Concatenation of FirstName, MiddleName, LastName, and Suffix up to 121 characters.
NumberOfEmployees
Type
int
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
Number of employees at the lead’s company. Label is Employees.
OwnerId
Type
reference
Properties
Create, Defaulted on create, Filter, Group, Sort, Update
Description
ID of the lead’s owner.
PartnerAccountId
Type
reference
Properties
Filter, Nillable
Description
ID of the partner account for the partner user that owns this lead. Available if Partner Relationship Management is enabled or if Communities is enabled and you have partner portal licenses.
Note

Note

If you are uploading leads using API version 15.0 or earlier, and one of the leads in the batch has a partner user as the owner, the Partner Account field on all leads in the batch is set to that partner user’s account regardless of whether the partner user is the owner. In version 16.0, the Partner Account field is set to the appropriate account for the partner user that owns the lead. If the owner of the lead is not a partner user, this field remains empty.

Phone
Type
phone
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The lead’s phone number.
PhotoUrl
Type
url
Properties
Filter, Group, Sort
Description

Path to be combined with the URL of a Salesforce instance (Example: https://yourInstance.salesforce.com/) to generate a URL to request the social network profile image associated with the lead. Generated URL returns an HTTP redirect (code 302) to the social network profile image for the lead.

Empty if Social Accounts and Contacts isn't enabled or if Social Accounts and Contacts has been disabled for the requesting user.

PostalCode
Type
string
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
Postal code for the address of the lead. Label is Zip/Postal Code.
Rating
Type
picklist
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
Rating of the lead.
RecordTypeId
Type
reference
Properties
Create, Filter, Nillable, Update
Description
ID of the record type assigned to this object.
Salutation
Type
picklist
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
Salutation for the lead.
ScoreIntelligenceId
Type
reference
Properties
Filter, Group, Nillable, Sort
Description
The ID of the intelligent field record that contains lead score.
State
Type
string
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
State for the address of the lead.
StateCode
Type
picklist
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The ISO state code for the lead’s address.
Status
Type
picklist
Properties
Create, Defaulted on create, Filter, Group, Sort, Update
Description
Status code for this converted lead. Status codes are defined in Status and represented in the API by the LeadStatus object.
Street
Type
textarea
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
Street number and name for the address of the lead.
Suffix
Type
string
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The lead’s name suffix up to 40 characters. To enable this field, ask Salesforce Customer Support for help.
Title
Type
string
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
Title for the lead, such as CFO or CEO.
Website
Type
url
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
Website for the lead.
Note

Note

If you import lead data and need to set the value for an audit field, such as CreatedDate, contact Salesforce. Audit fields are automatically updated during API operations unless you request to set these fields yourself..

Converted Leads

Leads have a special state to indicate that they have 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 is read-only. 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.

Note

Note

If person account record types have been enabled, and if the value of Company is null, the lead converts to a person account.

Unread Leads

Leads have a special state to indicate that they have not been viewed or edited by the lead owner. In Salesforce, 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(), 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 the following options (but not both) in the AssignmentRuleHeader used in create or update:

Field Field Type Details
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, query the AssignmentRule object (specifying RuleType="leadAssignment"), iterate through the returned AssignmentRule records, find the one you want to use, retrieve its ID, and then specify its ID in this field in the AssignmentRuleHeader.

useDefaultRule boolean Specifies whether to use the default rule for rule-based assignment (true) or not (false). Default rules are assigned in the user interface.

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);
                }
            }
        }
    }
}

See Also