LeadConfigSettings Metadata Type in SFDX

Architectural Overview#

The LeadConfigSettings metadata type controls organizational configuration for inbound lead intake, Web-to-Lead anti-spam defenses, and sales lead intelligence in Salesforce Sales Cloud. For sales and marketing architectures, maintaining pristine lead data hygiene and guarding against automated web form spam submissions is critical for pipeline velocity.

Architecturally, LeadConfigSettings enforces security policies at the Salesforce edge layer for Web-to-Lead submissions—specifically requiring reCAPTCHA API verification before any external HTTP POST request can generate a Lead record. Furthermore, it manages switches governing lead assignment rules and automated notification behavior when leads enter the CRM.

Directory and File Conventions#

In Salesforce DX source format, LeadConfigSettings is represented as a single XML file located within the settings directory:

Key Metadata Fields#

The XML schema for LeadConfigSettings includes security toggles and lead capture controls:

Declarative XML and Package Manifest Examples#

Source XML (LeadConfig.settings-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<LeadConfigSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <doesRequireRecaptcha>true</doesRequireRecaptcha>
    <enableLeadIntelligence>true</enableLeadIntelligence>
    <enableWebToLead>true</enableWebToLead>
</LeadConfigSettings>

Package Manifest (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>LeadConfig</members>
        <name>Settings</name>
    </types>
    <version>68.0</version>
</Package>

Retrieval and Deployment#

To retrieve LeadConfigSettings using the Salesforce CLI:

# Retrieve settings directly
sf project retrieve start --metadata Settings:LeadConfig

# Retrieve using manifest
sf project retrieve start --manifest manifest/package.xml

To deploy LeadConfigSettings to a target sandbox:

# Deploy to designated org
sf project deploy start \
  --metadata Settings:LeadConfig \
  --target-org uat \
  --wait 10

Senior Architect Deployment Best Practices and Gotchas#

Production Rollout of reCAPTCHA Verification#

Enabling doesRequireRecaptcha in production without prior coordination with website engineering teams is a common cause of lead generation outages. Web forms submitting directly to webtolead endpoints without generating reCAPTCHA responses will receive HTTP errors and fail silently.

Scratch Org Settings Alignment#

Ensure testing scratch orgs reflect your security settings by including leadConfigSettings in project-scratch-def.json:

{
  "orgName": "Lead Management Scratch Org",
  "edition": "Enterprise",
  "settings": {
    "leadConfigSettings": {
      "doesRequireRecaptcha": true,
      "enableWebToLead": true
    }
  }
}

Frequently asked questions

What is LeadConfigSettings in Salesforce?

It configures lead management features, including web-to-lead reCAPTCHA requirements and lead scoring configurations.

Where is LeadConfigSettings stored in an SFDX project?

It is stored under force-app/main/default/settings as LeadConfig.settings-meta.xml and retrieved as Settings:LeadConfig.

How does LeadConfigSettings impact Web-to-Lead forms?

It enforces security checks such as requiring reCAPTCHA verification on incoming Web-to-Lead submissions to prevent spam.

Can LeadConfigSettings be deployed with the Salesforce CLI?

Yes, using sf project retrieve start or deploy start with the metadata parameter set to Settings:LeadConfig.