Skip to main content

SOAP Headers

SOAP API operations support optional headers that control Salesforce behavior during data operations. Headers are specified using the @soap_options parameter

Salesforce has official documentation on the SOAP Headers at Salesforce SOAP API Developer Guide - Headers

Format Specification​

Format: HeaderName,property,value;HeaderName,property,value

  • Semicolon (;) separates multiple header specifications
  • Comma (,) separates header name, property name, and value within each specification
  • Property names must match Salesforce API exactly (camelCase, case-sensitive)
  • Boolean values must be exactly true or false (lowercase)

Supported Headers​

EmailHeader​

Controls email sending for cases, leads, and events.

Properties:

  • triggerAutoResponseEmail (boolean) - Trigger auto-response rules for leads/cases
  • triggerOtherEmail (boolean) - Send emails outside the organization
  • triggerUserEmail (boolean) - Send emails to users within organization

Default Values (when property omitted):

triggerAutoResponseEmail: false
triggerOtherEmail: false
triggerUserEmail: false

Examples:

-- Trigger user emails only
@soap_options = 'EmailHeader,triggerUserEmail,true'

-- Trigger multiple email types
@soap_options = 'EmailHeader,triggerUserEmail,true;EmailHeader,triggerOtherEmail,true'

-- Explicitly set all properties
@soap_options = 'EmailHeader,triggerAutoResponseEmail,false;EmailHeader,triggerOtherEmail,true;EmailHeader,triggerUserEmail,false'

DuplicateRuleHeader​

Controls duplicate detection rule behavior.

Properties:

  • allowSave (boolean) - Bypass duplicate rule alerts and save records anyway
  • includeRecordDetails (boolean) - Return field values for detected duplicates
  • runAsCurrentUser (boolean) - Enforce current user's sharing rules during duplicate checks

Default Values (when property omitted):

allowSave: false
includeRecordDetails: false
runAsCurrentUser: true

Examples:

-- Allow saving duplicates but use current user context
@soap_options = 'DuplicateRuleHeader,allowSave,true'

AssignmentRuleHeader​

Specifies which assignment rule to use for Cases, Leads, or Accounts.

Properties:

  • assignmentRuleId (string, optional) - Salesforce ID of specific assignment rule
  • useDefaultRule (boolean, optional) - Use the default active assignment rule

Default Values: None (both properties are optional)

Important: assignmentRuleId and useDefaultRule are mutually exclusive - specify one OR the other, not both.

Examples:

-- Use default assignment rule
@soap_options = 'AssignmentRuleHeader,useDefaultRule,true'

-- Use specific assignment rule
@soap_options = 'AssignmentRuleHeader,assignmentRuleId,01Q5e000000EXAMPLE'

AllOrNoneHeader​

Roll back all changes if any record fails.

Properties:

  • allOrNone (boolean, required) - If true, all changes rolled back on any error

Examples:

-- All-or-nothing processing
@soap_options = 'AllOrNoneHeader,allOrNone,true'

AllowFieldTruncationHeader​

Allow field value truncation for string fields in API version 15.0+.

Properties:

  • allowFieldTruncation (boolean, required) - If true, truncate field values that exceed max length

Examples:

-- Allow truncation
@soap_options = 'AllowFieldTruncationHeader,allowFieldTruncation,true'

DisableFeedTrackingHeader​

Disable feed tracking for changes made in this operation.

Properties:

  • disableFeedTracking (boolean, required) - If true, don't track changes in Chatter feeds

Examples:

-- Disable feed tracking
@soap_options = 'DisableFeedTrackingHeader,disableFeedTracking,true'

MruHeader​

Control whether to update Most Recently Used (MRU) lists.

Properties:

  • updateMru (boolean, required) - If true, update MRU lists for affected records

Examples:

-- Don't update MRU
@soap_options = 'MruHeader,updateMru,false'

Multiple Headers​

Combine multiple headers by separating them with semicolons:

@soap_options = 'EmailHeader,triggerUserEmail,true;AllOrNoneHeader,allOrNone,true;MruHeader,updateMru,false'

Error Messages​

Speediful provides helpful error messages for common issues:

Invalid format:

ERROR: Invalid SOAP header format: 'EmailHeader,triggerUserEmail'
Tip: Expected format: 'HeaderName,property,value'
Tip: Example: 'EmailHeader,triggerUserEmail,true'

Unknown header:

ERROR: Unknown SOAP header: 'EmalHeader'
Tip: Available headers: AllOrNoneHeader, AllowFieldTruncationHeader, AssignmentRuleHeader, DisableFeedTrackingHeader, DuplicateRuleHeader, EmailHeader, MruHeader
Tip: Header names are case-sensitive and must match Salesforce API exactly

Invalid boolean value:

ERROR: Invalid boolean value 'yes' for EmailHeader.triggerUserEmail
Tip: Boolean values must be exactly 'true' or 'false' (lowercase)
Tip: Example: 'EmailHeader,triggerUserEmail,true'

Mutual exclusivity:

ERROR: AssignmentRuleHeader properties assignmentRuleId and useDefaultRule are mutually exclusive
Tip: Specify either assignmentRuleId OR useDefaultRule, not both
Tip: Example: 'AssignmentRuleHeader,useDefaultRule,true'

Best Practices​

  1. Specify only what you need - Omitted properties get sensible defaults
  2. Use exact property names - Names are case-sensitive (camelCase)
  3. Boolean values are strict - Must be true or false exactly
  4. Check error messages - They provide examples and suggestions
  5. Test in development - Verify header behavior before production use