SOAP (Simple Object Access Protocol)
SOAP (Simple Object Access Protocol) is the XML-based messaging protocol that powers the Salesforce SOAP API, the platform's original integration channel.
Definition
SOAP (Simple Object Access Protocol) is the XML-based messaging protocol that powers the Salesforce SOAP API, the platform's original integration channel. SOAP defines how clients send strongly-typed XML requests to a service and receive XML responses, with the contract described by a WSDL (Web Services Description Language) file. Salesforce publishes two WSDLs: the Enterprise WSDL (typed to the org's exact schema) and the Partner WSDL (generic across all orgs).
Salesforce's SOAP API offers the same core capabilities as the REST API (create, read, update, delete, query, search) but in a verbose XML format that older middleware platforms still expect. SOAP was the only Salesforce API until REST API launched in 2010; many integration platforms standardised on SOAP long before REST became the default. SOAP remains fully supported in 2026 and is the right choice when the integrating tool only speaks SOAP or when the org needs the strict type checking that WSDL contracts provide.
How the Salesforce SOAP API works and when to use it
How a Salesforce SOAP request is structured
A SOAP request is a POST to the org's SOAP endpoint (login.salesforce.com/services/Soap/u/XX.X for production, with a versioned URL). The body is an XML envelope containing a header (the Session ID for authentication) and a body (the actual operation: create, update, query, search). Each operation has a strict structure defined in the WSDL. The response is also an XML envelope: a header with the original session, a body with the operation result (created Ids, updated rows, queried records), and a fault element if anything failed during processing. The fault element includes a fault code, fault string, and any structured detail the operation provides, which the client parses to decide whether to retry, log, or surface to the user.
Enterprise WSDL vs Partner WSDL
Salesforce publishes two WSDL files. The Enterprise WSDL is generated for a specific org's schema; it includes typed elements for every standard and custom object, every field, every relationship. An integration built against the Enterprise WSDL gets compile-time validation that the right field names exist. The Partner WSDL is generic across all orgs; it uses untyped elements that work against any Salesforce org but offer no compile-time field validation. The Partner WSDL is the right choice for AppExchange apps that target many orgs; the Enterprise WSDL is right for org-specific integrations.
SOAP vs REST and when each is the right choice
REST API is the default for new integrations. It is faster (no XML parsing), more JSON-native, and easier to debug with curl. SOAP API still wins in three scenarios: when the middleware tool is older and only speaks SOAP (Informatica PowerCenter, IBM DataPower, older MuleSoft connectors); when the integration needs the strongly-typed contract that WSDL provides for compile-time validation; and when the operation is unavailable in REST (a small set of metadata operations and Apex test control endpoints still require SOAP). For everything else, REST is the right pick in modern integrations.
Authentication: login() call vs Session ID
SOAP authentication begins with a login() call: the client sends username, password, and optionally a security token to the SOAP endpoint and receives a Session ID back. Every subsequent SOAP call must include the Session ID in the SOAP header. This differs from REST, which uses OAuth bearer tokens in the HTTP Authorization header. Old SOAP clients still authenticate this way; modern clients can also use OAuth to obtain a Session ID and then pass it to SOAP, which is the recommended pattern when both protocols are involved in the same integration.
Limits, batching, and the 200-record cap
SOAP API operations are subject to the org's API request limit (the same allowance that applies to REST). Most CRUD operations cap at 200 records per call: create() accepts up to 200 sObjects per request, update() accepts up to 200. Bulk operations beyond that scope need the Bulk API, which is a parallel REST-based API designed for higher-volume work. SOAP query() returns up to 2,000 records per call with a QueryLocator for paging; queryMore() continues paging until the result set is exhausted.
Tooling: WSDL2Java, WSDL2Apex, generated stubs
Most languages have a tool to generate strongly-typed client code from a WSDL: Java's wsdl2java, .NET's wsdl.exe, Apex's WSDL2Apex (for org-to-org SOAP calls). These tools parse the WSDL and emit classes representing each SOAP operation and message type. The generated code is faster to write against than hand-rolling XML, and it catches type mismatches at compile time. The cost is brittleness: regenerating the client when the WSDL changes is a workflow step that REST-based integrations do not need.
Operational considerations: logging, monitoring, error handling
SOAP responses with SOAP faults look different from REST 4xx responses. A SOAP fault is an XML element inside the response body, not an HTTP status code, so generic HTTP-based monitoring tools may report SOAP calls as 200 OK even when they contain faults. SOAP-aware monitoring needs to parse the response body to detect faults. Error handling in client code typically wraps each SOAP call in a try-catch that checks both the HTTP layer (timeout, network failure) and the SOAP layer (fault element in the body), with retry policies tuned for the specific error class. Salesforce's SOAP API returns specific fault codes for limit-related errors (REQUEST_LIMIT_EXCEEDED), authentication failures (INVALID_SESSION_ID), and validation issues (FIELD_CUSTOM_VALIDATION_EXCEPTION); good integrations branch on the code and choose retry, refresh-session, or surface-to-user as appropriate.
Call the Salesforce SOAP API from a middleware integration
A SOAP integration with Salesforce starts with downloading the right WSDL, generating client stubs, authenticating, and calling the operations you need. The steps below cover a typical end-to-end integration.
- Download the right WSDL
In Setup, go to API. Download the Enterprise WSDL for org-specific integrations or the Partner WSDL for generic ones. The Enterprise WSDL includes the org's exact schema; regenerate it after schema changes.
- Generate client stubs
Use your language's WSDL tooling: wsdl2java for Java, wsdl.exe for .NET, WSDL2Apex for Salesforce-to-Salesforce calls. The tool produces typed classes for each SOAP operation and message type.
- Authenticate with login()
Call the login() method with username, password (with security token appended if accessing from an untrusted IP), and the SOAP endpoint URL. The response includes a Session ID and the per-org SOAP endpoint to use for subsequent calls.
- Make CRUD calls within governor limits
Use the generated client to call create, update, query, search, or delete. Batch up to 200 records per call. For larger volumes, switch to the Bulk API or chunk the work into multiple SOAP calls.
- Handle SOAP faults and retry policies
Wrap each call in error handling that catches both HTTP-layer errors (timeout, network) and SOAP-layer faults (fault element in the response body). Implement exponential backoff for retryable errors like REQUEST_LIMIT_EXCEEDED.
Org-specific WSDL with typed elements for every field. Use for org-specific integrations that benefit from compile-time validation.
Generic WSDL that works against any Salesforce org. Use for AppExchange apps and tools that target multiple orgs.
Apex-side SOAP client generator for calling external SOAP services from inside Apex. The reverse of the typical SOAP API consumption pattern.
- SOAP CRUD operations cap at 200 records per call. Larger volumes need either multiple SOAP calls (slow) or the Bulk API (designed for volume). The cap is per-call; the total daily allowance is separate.
- The Enterprise WSDL is org-specific. Schema changes (new field, renamed field) require regenerating the WSDL and the client stubs in every consumer integration, or the integration will silently use stale type definitions.
- SOAP faults are inside the response body, not in the HTTP status code. Generic HTTP monitoring will report a faulting SOAP call as 200 OK; SOAP-aware monitoring must parse the body to detect the fault element.
Trust & references
Cross-checked against the following references.
- SOAP API Developer GuideSalesforce Developers
- Obtain a WSDLSalesforce Developers
- SOAP login() CallSalesforce Developers
- Bulk APISalesforce Developers
Straight from the source - Salesforce's reference material on SOAP (Simple Object Access Protocol).
- SOAP API DocumentationSalesforce Developers
- WSDL2ApexSalesforce Developers
Hands-on resources to go deeper on SOAP (Simple Object Access Protocol).
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is SOAP?
Q2. What's the modern alternative?
Q3. Why might SOAP still be used?
Discussion
Loading discussion…