Lead

Represents a prospect or potential Opportunity.

Supported Calls

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

Fields

Field Field Type Field Properties Description
AnnualRevenue currency Create

Filter

Nillable

Update

Annual revenue for the company of the lead.
City string Create

Filter

Nillable

Update

City for the address of the lead.
Company string Create

Filter

Nillable

Update

Required. Company of the lead.
Note
If person account record types have been enabled, and if the value of the Company field is null, the lead converts to a person account. See “Notes on Converting Leads” in the Salesforce.com online help.
ConnectionReceivedId reference Filter

Nillable

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

Nillable

ID of the PartnerNetworkConnection that you shared this record with. This field is only available if you have enabled Salesforce to Salesforce. Beginning with API version 15.0, the ConnectionSentId field is no longer supported. The ConnectionSentId field is still visible, but the value is null. You can use the new PartnerNetworkRecordConnection object to forward records to connections.
ConvertedAccountId reference Filter

Nillable

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

Nillable

Object reference ID that points to the Contact into which the Lead has been converted.
ConvertedDate date Filter

Nillable

Date on which this Lead was converted.
ConvertedOpportunityId reference Filter

Nillable

Object reference ID that points to the Opportunity into which the Lead has been converted.
Country string Create

Filter

Nillable

Update

Country for the address of the lead.
Description textarea Create

Nillable

Update

Description of the lead.
Email email Create

Filter

Nillable

idLookup

Update

Email address for the lead.
EmailBouncedDate dateTime Filter

Nillable

Update

If bounce management is activated and an email sent to the lead bounced, the date and time the bounce occurred.
EmailBouncedReason string Filter

Nillable

Update

If bounce management is activated and an email sent to the lead bounced, the reason the bounce occurred.
Fax phone Create

Filter

Nillable

Update

Fax number for the lead.
FirstName string Create

Filter

Nillable

Update

First name of the lead. Limited to 40 characters.
HasOptedOutOfEmail boolean Create

Defaulted on create

Filter

Update

Indicates whether the lead has opted out of email (true) or not (false). Label is Email Opt Out.
Industry picklist Create

Filter

Nillable

Update

Industry the lead works in.
IsConverted boolean Create

Defaulted on create

Filter

Indicates whether the Lead has been converted (true) or not (false). Label is Converted.
IsDeleted boolean Defaulted on create

Filter

Indicates whether the object has been moved to the Recycle Bin (true) or not (false). Label is Deleted.

IsUnreadByOwner boolean Create

Defaulted on create

Filter

Update

If true, lead has been assigned, but not yet viewed. See Unread Leads for more information. Label is Unread By Owner.
LastActivityDate date Filter

Nillable

Value is one of the following, whichever is the most recent:
  • Due date of the most recent event logged against the record.
  • Due date of the most recently closed task associated with the record.
LastName string Create

Filter

Nillable

Required. Last name of the lead. Limited to 80 characters.
LeadSource picklist Create

Filter

Nillable

Update

Source from which the lead was obtained.
masterRecordId reference Filter

Nillable

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

Filter

Nillable

Update

Mobile phone number for the lead.
Name string Filter Concatenation of FirstName and LastName. Limited to 121 characters.
NumberOfEmployees int Create

Filter

Nillable

Update

Number of employees at the lead’s company. Label is Employees.
OwnerId reference Create

Defaulted on create

Filter

Update

ID of the owner of the lead.
PartnerAccountId reference Filter

Nillable

ID of the partner account for the partner user that owns this lead. Available only if Partner Relationship Management is enabled.
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 blank.
Phone phone Create

Filter

Nillable

Update

Phone number for the lead.
PostalCode string Create

Filter

Nillable

Update

Postal code for the address of the lead. Label is Zip/Postal Code.
Rating picklist Create

Filter

Nillable

Update

Rating of the lead.
RecordTypeId reference Create

Filter

Nillable

Update

ID of the record type assigned to this object.
Salutation picklist Create

Filter

Nillable

Update

Salutation for the lead.
State string Create

Filter

Nillable

Update

State for the address of the lead.
Status picklist Create

Defaulted on create

Filter

Update

Status code for this converted lead. Status codes are defined in the lead status picklist and represented in the API by the LeadStatus object.
Street textarea Create

Filter

Nillable

Update

Street number and name for the address of the lead.
Title string Create

Filter

Nillable

Update

Title for the lead, for example CFO or CEO.
Website url Create

Filter

Nillable

Update

Website for the lead.
Note
If you are importing Lead data into Salesforce.com and need to set the value for an audit field, such as CreatedDate, contact salesforce.com. Audit fields are automatically updated during API operations unless you request to set these fields yourself. For more information, see System Fields.

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 alsoconvert leads through the Salesforce.com 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.com user interface. The fields are:

Note
If person account record types have been enabled, and if the value of the Company field is null, the lead converts to a person account. See “Notes on Converting Leads” in the Salesforce.com online help.

Unread Leads

Leads have a special state to indicate that they have not been viewed or edited by the lead owner. In the Salesforce.com 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.

Lead Status Picklist

Each Status value corresponds to either a converted or unconverted status in the lead status picklist, as defined in the Salesforce.com 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 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 call 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 objects based on assignment rules that have been configured in the Salesforce.com 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). Default rules are assigned in the Salesforce.com user interface.

Java Sample

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

package com.doc.samples; 
import java.net.MalformedURLException; 
import java.net.URL; 
import java.rmi.RemoteException; 
import javax.xml.rpc.ServiceException;

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, ServiceException
  { 
    //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_PROPERTY, 
        lr.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); 
 
  }
}

C # Sample

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

using System;
using System.Collections.Generic;
using System.Text;
using LeadAssignment.sforce;

namespace LeadAssignment
{
    class LeadAssignment
    {
        private SforceService binding;

        private static readonly string Username = "ENTERUSERNAME";
        private static readonly string Password = "ENTERPASSWORD";

        /// <summary>
        /// Create the proxy binding and login
        /// </summary>
        private LeadAssignment()
        {
            this.binding = new SforceService();
            LoginResult lr = binding.login(LeadAssignment.Username, LeadAssignment.Password);

            // Reset the binding to use the endpoint returned from login
            this.binding.Url = lr.serverUrl;

            // Create the session ID header and add it to the proxy binding
            this.binding.SessionHeaderValue = new SessionHeader();
            this.binding.SessionHeaderValue.sessionId = lr.sessionId;
        }

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

        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 cannot be used together.
            QueryResult qr = binding.query("Select Id from AssignmentRule where Name = " +
                "'Mass Mail Campaign' and SobjectType = 'lead'");
            if (qr.size == 0)
            {
                arh.useDefaultRule = true;
            }
            else
            {
                arh.assignmentRuleId = qr.records[0].Id;
            }
            binding.AssignmentRuleHeaderValue = arh;

            // Every operation that results in a new or updated lead will use the
            // specified rule until the header is removed from the proxy binding
            SaveResult[] sr = binding.create(new sObject[] { lead });
            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);
                }
            }

            // This call effectively removes the header. The next lead will be assigned
            // to the default lead owner.
            binding.AssignmentRuleHeaderValue = null;
        }
    }
}
© Copyright 2000-2009 salesforce.com, inc. All rights reserved.
Various trademarks held by their respective owners.