Salesforce SOAP API and WSDL: Enterprise vs Partner, and When to Use It

Hey friends,

The Salesforce SOAP API is a WSDL-based web service for reading and writing your org's data and metadata, and you pick the strongly typed Enterprise WSDL for one org or the loosely typed Partner WSDL for many orgs. Salesforce still supports it fully, but it recommends REST for new development, so the real question is when a legacy tool or contract makes SOAP the right call.

You'll see SOAP in the Design and Build sections of the Salesforce Certified Platform Integration Architect exam, usually inside a scenario about an older enterprise system. One section of this post is about a deadline you should know: SOAP login() is being retired in Summer '27, and some of the changes land before then. For choosing among all the APIs, see Salesforce API types.

What is the Salesforce SOAP API?

It's a web service built on open standards. Per the About SOAP API page, it complies with SOAP 1.1, WSDL 1.1 and the WS-I Basic Profile 1.1. A WSDL (Web Services Description Language) file describes the operations and data types, and your development platform generates client code from it.

Salesforce's own API guidance sums up where SOAP fits: it's well suited to older system integrations, integrations that need a well-defined interface described by a WSDL, and operations on 200 or fewer records. It also says that while it's fully supported, SOAP API is no longer being enhanced, and that REST is the recommendation for new development.

• Availability: SOAP API needs Enterprise, Unlimited, Performance or Developer Edition.
• Permission: a user needs the API Enabled permission. The Salesforce Integration user license gives system users API-only access.
• Core calls: create(), update(), upsert(), delete(), undelete(), merge(), convertLead(), retrieve(), query(), queryMore(), queryAll(), search(), getUpdated() and getDeleted(), plus describe calls such as describeGlobal().
• Shared limits: SOAP calls count toward the same daily API allocation as REST.

What is the difference between the Enterprise and Partner WSDL?

The Enterprise WSDL is strongly typed and specific to your org, while the Partner WSDL is loosely typed and works for any org. The Using the Partner WSDL page lays it out:

The docs put the trade-off in one line: the Enterprise WSDL is more straightforward to use, and the Partner WSDL is more flexible, letting you write one application for many orgs. Enterprise also has a wrinkle: if the org has managed packages installed, you choose which version of each package goes into the generated WSDL, as the About SOAP API page explains.

Partner WSDL clients have to name their XML namespaces explicitly, for example urn:partner.soap.sforce.com for calls and urn:sobject.partner.soap.sforce.com for sObjects and fields, per the namespaces page. They also set the object type before assigning field values, as the objects and fields page says.

My rule of thumb: one org and a known schema means Enterprise. A product, tool or integration platform that has to run against many different orgs, or discover fields at runtime, means Partner.

How do I generate the WSDL and call the SOAP API?

Any user with the Modify All Data permission can download the WSDL. From Setup, enter API in the Quick Find box, select API, and generate the Enterprise or Partner WSDL. The generate WSDL page notes that the file is dynamically generated, so it lists the standard and custom objects and fields available to your org.

Then you import it into your platform, which generates client classes, authenticate, and call. With the Enterprise WSDL, generated classes mean a query result is typed. With the Partner WSDL, you read fields by name. This is the Java version of the same query, using Salesforce's Web Service Connector (WSC), adapted from the docs:

1// Enterprise WSDL: generated Contact class
2QueryResult qr = connection.query("SELECT FirstName, LastName FROM Contact");
3boolean done = false;
4while (!done) {
5    for (SObject rec : qr.getRecords()) {
6        Contact c = (Contact) rec;
7        System.out.println(c.getFirstName() + " " + c.getLastName());
8    }
9    if (qr.isDone()) { done = true; }
10    else { qr = connection.queryMore(qr.getQueryLocator()); }
11}

1// Partner WSDL: generic SObject, fields read by name
2QueryResult qr = connection.query("SELECT FirstName, LastName FROM Contact");
3for (SObject rec : qr.getRecords()) {
4    System.out.println(rec.getField("FirstName") + " " + rec.getField("LastName"));
5}

A few behaviors from the docs worth knowing for the exam:

• create() takes up to 200 records. If a request has more, the entire operation fails, per the create() page.
• query() returns up to 2,000 rows per batch, and you call queryMore() for the rest, per the query() page.
• By default, records without errors are committed and failed ones are marked in the results. To roll everything back on any failure, send the AllOrNoneHeader with allOrNone set to true, and still check the success field on each result.
• Your session ID goes in the SessionHeader, and you send calls to the server URL that login returns, not to the login server.
• A SOAP fault comes back for badly formed messages or failed authentication. If a session expires, you get INVALID_SESSION_ID, per the error handling page.

If you learn best by testing yourself, the Platform Integration Architect Cert Lab has quick practice questions on choosing between SOAP and REST, with every option explained.

How does SOAP API authenticate, and what is happening to login()?

Historically it was the login() call: you send a username and password, and get back a session ID and a server URL. That call is going away. Salesforce's login() retirement article gives the timeline, and I'd put it on a sticky note if you own any older SOAP integration:

The replacement is OAuth 2.0 with an external client app. Per the same article, use the JWT bearer or client credentials flow for server-to-server integrations, and the web server flow for user-driven ones. The migration article adds that both flows return an access token that replaces the SOAP session ID, and that the SOAP calls themselves don't change, only the authentication step. The SOAP API OAuth page covers setup, and I walk through the flows in the Salesforce REST API post.

Two older rules still apply to login-based clients and are good to know. Salesforce limits login() to 3,600 calls per user per hour, and per the login() page, logins from unknown IP addresses are blocked unless the user adds a security token to the password or the IP is trusted. Sessions expire after two hours of inactivity by default, per the error handling page.

When should I use the SOAP API instead of REST?

Use SOAP when something outside your control needs it, and use REST for everything you're building new. In practice these are the cases that justify SOAP:

• A legacy ESB, ERP connector or commercial tool that only speaks SOAP and imports a WSDL.
• A governance requirement for a formal, versioned service contract.
• An ISV or integration product that has to work against many customer orgs with different schemas, where the Partner WSDL fits.
• A small-record, synchronous integration that a SOAP client already handles, with no business reason to migrate.

And these are the cases where it's the wrong tool. More than about 2,000 records means Bulk API 2.0, which I cover in Bulk API 2.0. Several dependent operations in one trip means the REST composite resources in Composite API. Events mean platform events. A new build with no WSDL requirement should use the REST API.

What other SOAP features does Salesforce have?

Exam questions blur these, so keep them apart. They're four different things, and only the first is the SOAP API itself:

Outbound messages are built for delivery. If the endpoint is down, Salesforce retries with an interval that grows exponentially up to two hours, and drops the message after 24 hours. Design the receiver to handle duplicates and keep it idempotent, since messages are retried independent of their order.

How does the SOAP API show up on the Platform Integration Architect exam?

When two answers both work, the exam usually rewards the one that matches the stated constraint, not the newest one. A WSDL requirement is a constraint. A preference for JSON isn't.

What mistakes do people make with the SOAP API?

• Using the Enterprise WSDL in a product meant for many orgs, then regenerating client code for every customer.
• Forgetting to regenerate the Enterprise WSDL after adding a custom field, and wondering why the field is missing.
• Sending more than 200 records in one create() and having the whole call fail.
• Building new login() based integrations today, when the call is being removed.
• Assuming a failed record rolls back the others. Without the AllOrNoneHeader, the good records commit.
• Mixing up Apex SOAP web services (inbound) with WSDL callouts (outbound).

I'll be honest about how I learned this stuff. I loved Focus on Force and used it through 17 Salesforce certifications. Reading the study guide first was slow for me; taking practice tests rapid-fire and studying every wrong answer was fast. So when I built Cert Lab, I built it around that: test yourself quickly, see why each option is right or wrong.

FAQ

What is the Salesforce SOAP API?

A WSDL-based web service for creating, reading, updating, deleting and querying Salesforce data and metadata. It's fully supported but no longer enhanced, and Salesforce recommends REST for new development.

What is the difference between the Enterprise and Partner WSDL?

The Enterprise WSDL is strongly typed and specific to one org, and must be regenerated when custom fields or objects change. The Partner WSDL is loosely typed, works with any org and is downloaded once per API version.

Where do I download the Salesforce WSDL?

From Setup, enter API in the Quick Find box and select API. You need the Modify All Data permission.

How many records can SOAP API process in one call?

Up to 200 records for create and the other write calls. A query returns up to 2,000 rows per batch, and you use queryMore for the rest.

Is SOAP API login() being retired?

Yes. It is scheduled for removal in Summer '27 for API versions 31.0 through 64.0, with tighter rules starting December 1, 2026, and again on December 15, 2026 in sandboxes and January 31, 2027 in production. Migrate to OAuth 2.0 with an external client app.

When should I use SOAP API instead of REST API?

When a legacy tool or contract requires a WSDL, or when an ISV needs one client for many orgs. For new builds with no WSDL requirement, use REST.

What is the difference between SOAP API and an Apex SOAP web service?

SOAP API is Salesforce's standard interface for objects. An Apex SOAP web service is your own Apex method marked webservice, exposed as a custom SOAP call with its own WSDL.

Where should you go next?

• Salesforce API types for the full comparison of Salesforce APIs.
• Salesforce REST API for OAuth flows, upsert and Apex REST.
• Salesforce Bulk API 2.0 for large loads.
• Salesforce integration patterns for how these APIs map to the six patterns.
• Platform Integration Architect study plan for the full exam.

Nick Frates, a senior Salesforce developer with 17 certifications, built the Platform Integration Architect Cert Lab at nickfrates.com: rapid-fire practice questions for every exam section, each answer explained.

Hope this helps!

Best,

Nick