SOAP API
The Salesforce SOAP API is the original programmatic interface to the Salesforce platform, released in 2003 and still in active use today.
Definition
The Salesforce SOAP API is the original programmatic interface to the Salesforce platform, released in 2003 and still in active use today. It exposes Salesforce data and metadata through XML-based SOAP envelopes and is described by a WSDL document that admins download from Setup. Most enterprise integration platforms (MuleSoft, Informatica, Boomi, IBM Integration Bus) consume the SOAP WSDL and generate strongly-typed client code that calls into Salesforce.
SOAP API splits into two WSDLs. The Enterprise WSDL is strongly typed to the connected org's schema (objects, fields, relationships are specific to that org) and is appropriate for client code that targets one Salesforce environment. The Partner WSDL is loosely typed (uses generic sObject references) and is appropriate for ISV tools that need to work across many customer orgs without recompiling. Both authenticate via OAuth (recommended) or username/password (legacy). The newer REST API is the modern default for most integrations, but SOAP remains in production for legacy patterns and for tools that prefer its strongly-typed model.
How SOAP API supports enterprise integration with Salesforce
Enterprise versus Partner WSDL
The Enterprise WSDL is strongly typed to the schema of the connected org. The Account object exposes specific custom fields with their types, the API client generated from the WSDL knows about them at compile time, and IDE autocomplete works against the real object structure. The Partner WSDL is generic. It uses generic sObject references that hold field name and value pairs as strings, so the same client code works against any Salesforce org. ISV tools that ship to many customers use Partner WSDL; bespoke integrations for one org use Enterprise.
XML envelopes and the request/response model
SOAP API requests are XML envelopes wrapping a method call with strongly-typed parameters. Responses are XML envelopes wrapping return values. Compared to REST's JSON, SOAP is verbose but explicit about types and structure. Integration platforms parse SOAP fluently because the WSDL fully describes every operation, every type, and every fault condition. Hand-rolled SOAP client code is uncommon today; almost everyone uses a generated client library that hides the XML layer.
Core operations: create, update, delete, query
The SOAP API exposes operations that map naturally to CRUD: create() inserts records, update() modifies, upsert() inserts or updates based on an external ID, delete() removes, query() runs SOQL, search() runs SOSL, retrieve() fetches by ID. Each operation accepts a batch of records (up to 200 per call) and returns a SaveResult or DeleteResult per record indicating success or failure. The batch shape is helpful for bulk-style integrations but caps out fast; for high volume, Bulk API 2.0 is the modern alternative.
Authentication: OAuth versus username-password
SOAP API supports the same OAuth flows REST does (Web Server, JWT Bearer, Client Credentials) and additionally the legacy login() operation with username and password. The login() method is deprecated as of Spring 2024 and is being phased out; new integrations should use OAuth. For existing integrations relying on login(), migrate to OAuth before the end-of-life date. Username-password authentication is also blocked when MFA enforcement reaches the integration user, which most orgs have either configured or will soon.
Session management and headers
After authentication, every SOAP call includes a SessionHeader containing the session ID. The session ID stays valid for the configured session timeout (typically 2 hours of inactivity). Optional SOAP headers control behavior: AssignmentRuleHeader to fire lead/case assignment rules, EmailHeader to send notification emails, AllowFieldTruncationHeader to allow string truncation instead of errors, DisableFeedTrackingHeader to skip feed event creation. These headers are how SOAP API exposes runtime behaviors that REST API parameterizes differently.
Errors, fault responses, and partial-batch semantics
Each SOAP operation returns per-record results, so a batch of 200 inserts can have a mix of successes and failures. The AllOrNone setting controls whether one failure rolls back the whole batch (true) or only the failing records (false). Most integrations want AllOrNone=false with per-record error logging because rejecting an entire batch over one bad record is operationally painful. Network-level errors return SOAP faults, which clients handle differently from per-record errors. Robust SOAP integrations distinguish the two and retry appropriately.
Where SOAP API still shines and where REST wins
SOAP retains a place in enterprise integration where the strongly-typed contract, WSDL-driven code generation, and explicit fault definitions match existing tooling. MuleSoft, Informatica, and IBM Integration Bus all consume SOAP cleanly. REST API wins for newer patterns: lighter payloads, easier testing with curl, modern OAuth flows, composite requests, faster iteration. The pragmatic guideline today: new integrations should use REST unless the consuming platform's tooling pushes you to SOAP. Legacy SOAP integrations work fine and do not need migration unless they require feature REST has and SOAP lacks.
How to call the Salesforce SOAP API
Calling the SOAP API rarely involves writing raw XML these days. Modern integrations consume the WSDL into their integration platform or generate client code in their language of choice. The work is in choosing the right WSDL, configuring authentication, handling per-record results, and migrating off deprecated username-password flows where applicable.
- Decide between Enterprise and Partner WSDL
Enterprise for bespoke integration with one specific org. Partner for ISV tools that ship to many customers. Most internal IT projects use Enterprise; tools sold on AppExchange or built for multi-tenant use cases use Partner.
- Download the WSDL from Setup
Setup > API > Generate Enterprise WSDL or Generate Partner WSDL. Save the XML to your project. Re-download after schema changes (custom fields added) to keep the strongly-typed Enterprise WSDL in sync with the org.
- Generate client code from the WSDL
Use your integration platform''s WSDL consumption tooling, or generate language-specific client code. MuleSoft, Informatica, and similar platforms handle this with a few clicks. For custom code, use wsdl2java for Java, dotnet-wsdl for .NET, or zeep for Python.
- Configure OAuth authentication
Create a Connected App with OAuth scopes (api, refresh_token at minimum). Configure your client with the OAuth credentials. Use JWT Bearer flow for server integrations or Web Server flow for user-facing integrations.
- Make a test call to verify connectivity
Call a simple operation like getUserInfo() or describeGlobal() to confirm authentication and connectivity. The response tells you which org and user you are connected as. This is the integration smoke test.
- Build the integration logic with batch operations
Use create(), update(), upsert(), delete() with batches up to 200 records. Set AllOrNone=false for fault tolerance. Process the per-record SaveResult to log failures separately from successes.
- Implement retry and error handling
Per-record errors are returned in SaveResults. SOAP faults indicate network or authentication failures. Build retry with exponential backoff for transient faults; log per-record errors to a tracking system for manual review.
- Migrate any login() calls to OAuth
Setup > Connected App > switch authentication from username-password to OAuth. The login() operation is deprecated and being phased out. New integrations should not use it; legacy integrations should be migrated during planned maintenance.
Enterprise for one-org strongly-typed integration. Partner for multi-org generic integration used by ISVs.
OAuth is the modern standard. The login() username-password operation is deprecated and being phased out.
Controls whether one record failure rolls back the whole batch (true) or only the failing record (false). Most integrations want false.
- The login() operation is deprecated and will be retired. New integrations must use OAuth; existing integrations should plan migration before the end-of-life date.
- Enterprise WSDL is org-specific. After custom fields are added or relationships change, re-download the WSDL or the strongly-typed client code falls out of sync.
- Each SOAP operation caps at 200 records per call. For higher volume, use Bulk API 2.0 instead of looping SOAP calls.
- Multi-Factor Authentication enforcement blocks username-password integrations for impacted users. Confirm the integration user is exempted (rare and discouraged) or migrate to OAuth.
- SOAP API call counts against the daily API limit just like REST. Combined with REST traffic, monitor total consumption to avoid blowing the cap.
Trust & references
Cross-checked against the following references.
- SOAP API Developer GuideSalesforce Developer
- SOAP API Quick StartSalesforce Developer
- Generate the SOAP WSDLSalesforce Help
Straight from the source - Salesforce's reference material on SOAP API.
- SOAP API DocumentationSalesforce Developer
- SOAP API CallsSalesforce Developer
- Login OperationSalesforce Developer
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 Salesforce SOAP API?
Q2. What WSDLs are available?
Q3. When use Enterprise vs Partner WSDL?
Discussion
Loading discussion…