Lead

Represents a prospect or lead.

Supported Calls

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

Fields

Field	Details
ActionCadenceAssigneeId	Type reference Properties Filter, Group, Nillable, Sort Description The ID of the sales rep designated to work the lead through their assigned sales cadence. This field is available in API version 48.0 if you enabled High Velocity Sales.
ActionCadenceId	Type reference Properties Filter, Group, Nillable, Sort Description The ID of the lead’s assigned sales cadence. This field is available in API version 48.0 if you enabled High Velocity Sales.
ActivityMetricId	Type reference Properties Filter, Group, Nillable, Sort Description The ID of the related activity metric. This field is available in API version 48.0 if you enabled High Velocity Sales.
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. If person account record types have been enabled, and if the value of Company is null, the lead converts to a person account. Note
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. This field is only available to organizations that use Data.com Prospector or Data.com Clean. Note
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 Create, Defaulted on create, Filter, Group, Restricted picklist, Sort, Update 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, idLookup, 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.
FirstCallDateTime	Type datetime Properties Filter, Nillable, Sort Description The date and time of the first call placed to the lead. This field is available in API version 48.0 if you enabled High Velocity Sales.
FirstEmailDateTime	Type datetime Properties Filter, Nillable, Sort Description The date and time of the first email sent to the lead. This field is available in API version 48.0 if you enabled High Velocity Sales.
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 doesn’t want to receive email from Salesforce (`true`) or does (`false`). Label is Email Opt Out.
GeocodeAccuracy	Type picklist Properties Create, Filter, Group, Retrieve, Query, Restricted picklist, Nillable, Sort, Update 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. 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. Important
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 datetime Properties Filter, Nillable, Sort Description The timestamp when the current user last accessed this record, a record related to this record, or a list view.
LastViewedDate	Type datetime Properties Filter, Nillable, Sort Description The timestamp when the current user last viewed this record or list view. If this value is null, the user might have only accessed this record or list view (LastReferencedDate) but not viewed it.
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`. 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`. Note
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 203 characters, including whitespaces.
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, Group, Nillable, Sort 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. 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. Note
Phone	Type phone Properties Create, Filter, Group, Nillable, Sort, Update Description The lead’s phone number.
PhotoUrl	Type url Properties Filter, Group, Nillable, 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.

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..

Note

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. 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

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

Note

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.

C# Sample

The following C# sample shows how to automatically assign a newly created lead.

Associated Objects

This object has the following associated objects. Unless noted, they are available in the same API version as this 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.

Object Reference for Salesforce and Lightning Platform