The Salesforce SOAP API is the older, XML-based way for systems to talk to Salesforce, and many large companies still depend on it. SOAP uses a strict contract file called a WSDL, which describes every operation and data type. As a developer, you will meet SOAP in three places: other systems calling Salesforce, Apex calling SOAP services, and Apex exposing its own SOAP methods.
In this post, you will learn Enterprise and Partner WSDLs, generate Apex from a WSDL, make a SOAP callout, expose a webservice method and test it all. It builds on the Salesforce REST API, Apex REST callouts and Apex test class basics.
What is the Salesforce SOAP API?
The Salesforce SOAP API is a web service interface that exchanges XML messages, called SOAP envelopes, over HTTPS. Each operation, such as create, query or update, is defined in a WSDL file. Client tools read the WSDL and generate typed code, so calls are checked before they run.
Think of a formal government form. Every box has a fixed name and type, and the office rejects forms that do not match. REST is more like a friendly note, while SOAP is that strict form, slower to fill in but very predictable.
Why the Salesforce SOAP API Matters
SOAP is not the first choice for new work, yet it is still everywhere. Here is why the Salesforce SOAP API matters at Bright Path Tutors.
- First, the old finance system only talks SOAP.
- Also, PayQuick’s refund service exposes a SOAP WSDL.
- Next, some ETL and middleware tools use the SOAP API for metadata and data.
- Interviews often ask how SOAP differs from REST.
- Finally, legacy Apex code may already contain webservice methods you must maintain.
So knowing the Salesforce SOAP API keeps you useful on real, mixed projects.
How the Salesforce SOAP API Works
Work with the Salesforce SOAP API follows a clear flow. First, you get the WSDL, either from Salesforce for inbound calls or from the other system for outbound calls. Next, a tool generates typed classes from it, such as WSDL2Apex inside Salesforce. Then the client builds a request object and calls an operation. After that, the stub wraps it in a SOAP envelope and sends XML over HTTPS. Finally, the reply XML is turned back into typed objects or a SOAP fault.

Enterprise WSDL
The Enterprise WSDL is strongly typed for one org, with real objects like Course__c. So it is easy to use, but you must regenerate it when fields change.
Partner WSDL
The Partner WSDL is loosely typed and works for any org. Because of this, tools that serve many customers use it.
WSDL2Apex
In Setup, Apex Classes has a Generate from WSDL button. It turns an external WSDL into Apex stub classes for callouts.
Apex webservice Methods
A global class can expose webservice static methods. Salesforce then generates a WSDL for that class for outside callers.
SOAP Faults
When a call fails, SOAP returns a fault with a code and message. In Apex, a failed callout throws a CalloutException.
Salesforce WSDL Types at a Glance
The table below lists the main WSDL files and their uses.
| WSDL | Typing | Typical user |
|---|---|---|
| Enterprise WSDL | Strong, one org | In-house integrations |
| Partner WSDL | Loose, any org | Vendors and ETL tools |
| Metadata WSDL | Metadata types | Deployment tools |
| Apex class WSDL | Your webservice methods | Systems calling custom Apex |
| External WSDL | The other system’s operations | WSDL2Apex callouts |
SOAP API vs REST API
The table below compares the two styles.
| Feature | SOAP API | REST API |
|---|---|---|
| Format | XML envelopes | JSON, also XML |
| Contract | WSDL, strict | Docs, flexible |
| Generated code | Yes, typed stubs | Usually not needed |
| Message size | Larger | Smaller |
| Best for | Legacy enterprise systems | New web and mobile apps |
When to use which is practical. Choose REST for new integrations. Use SOAP when the other system only offers SOAP or needs a strict contract.

A Real Salesforce SOAP API Example
Let’s use the Salesforce SOAP API features at Bright Path Tutors. Apex calls PayQuick’s SOAP refund service, and the finance system calls a custom Apex SOAP method.
Step 1: Call PayQuick with Generated Stubs
public with sharing class RefundService {
public static String requestRefund(String paymentRef, Decimal amount) {
// Classes generated by Setup > Apex Classes > Generate from WSDL
PayQuickSoap.RefundPort port = new PayQuickSoap.RefundPort();
port.endpoint_x = 'callout:PayQuick_SOAP/refunds';
port.timeout_x = 15000; // milliseconds
PayQuickSoap.RefundResult result = port.createRefund(paymentRef, amount);
return result.status; // for example 'ACCEPTED'
}
}
The generated port class hides all XML work. Also, endpoint_x points at a Named Credential, so the URL and login stay out of code.
Step 2: Expose an Apex SOAP Method
global with sharing class FinanceSoapService {
webservice static Decimal getPaidTotal(Id courseId) {
AggregateResult ar = [SELECT SUM(Amount__c) total FROM Payment__c
WHERE Course__c = :courseId AND Status__c = 'Paid'
WITH USER_MODE];
Decimal total = (Decimal) ar.get('total');
return total == null ? 0 : total;
}
}
The class is global, and the method uses the webservice keyword. Then the Generate WSDL button on the class page gives finance a WSDL for this operation.
Step 3: Test the Callout with WebServiceMock
@IsTest
private class RefundServiceTest {
private class RefundMock implements WebServiceMock {
public void doInvoke(Object stub, Object request, Map<String, Object> response,
String endpoint, String soapAction, String requestName,
String responseNS, String responseName, String responseType) {
PayQuickSoap.createRefundResponse_element r = new PayQuickSoap.createRefundResponse_element();
r.result = new PayQuickSoap.RefundResult();
r.result.status = 'ACCEPTED';
response.put('response_x', r);
}
}
@IsTest
static void refundAccepted() {
Test.setMock(WebServiceMock.class, new RefundMock());
Assert.areEqual('ACCEPTED', RefundService.requestRefund('PAY-778', 1500));
}
}
SOAP callouts use WebServiceMock instead of HttpCalloutMock. The mock puts a fake response element in the response map under response_x. The element names follow your generated classes.
Here is the test run result.
RefundServiceTest.refundAccepted Pass (41 ms)
Salesforce SOAP API and Authentication
Older tools log in with the SOAP login() call and a username and password. However, Salesforce recommends OAuth for all new integrations. So send an OAuth access token as the session ID in the SOAP header instead.
Common Mistakes with the Salesforce SOAP API
- Using the Enterprise WSDL for a product sold to many orgs.
- Forgetting to regenerate the Enterprise WSDL after field changes.
- Hard-coding endpoint_x URLs instead of Named Credentials.
- Testing SOAP callouts with HttpCalloutMock instead of WebServiceMock.
- Choosing SOAP for a new integration when REST would be simpler.
Best Practices for the Salesforce SOAP API
- Prefer REST for new work, and keep SOAP for systems that need it.
- Use the Partner WSDL for multi-org tools.
- Point generated stubs at Named Credentials.
- Wrap generated classes in your own service class.
- Use OAuth tokens instead of password logins.
Practice Task
Add a webservice method that returns the number of open enrolments for a course. Hint: use COUNT() in SOQL and regenerate the class WSDL afterwards.
Most Asked Interview Questions on the Salesforce SOAP API
SOAP still shows up in enterprise interviews. Here are the 22 questions asked most about the Salesforce SOAP API.
Basic Questions on the Salesforce SOAP API
Q1: What is SOAP?
A protocol that sends structured XML messages, defined by a WSDL contract.
Q2: What is a WSDL?
An XML file that describes a service’s operations, inputs and outputs.
Q3: What is the difference between Enterprise and Partner WSDL?
Enterprise is strongly typed for one org, while Partner is loosely typed for any org.
Q4: Where do you download Salesforce WSDLs?
In Setup, open API to generate the Enterprise, Partner and Metadata WSDLs.
Q5: What is WSDL2Apex?
The Generate from WSDL feature that creates Apex stub classes from a WSDL.
Q6: How do you expose Apex as a SOAP service?
Use a global class with webservice static methods.
Q7: Which format does SOAP use?
XML only, wrapped in a SOAP envelope.
Code and Scenario Questions on the Salesforce SOAP API
Q8: How do you set a timeout on a SOAP stub?
Set the stub’s timeout_x property in milliseconds.
Q9: How do you use a Named Credential with a stub?
Set endpoint_x to callout:Name plus any path.
Q10: How do you test a SOAP callout?
Implement WebServiceMock and register it with Test.setMock.
Q11: What happens if a WSDL feature is not supported by WSDL2Apex?
Generation fails, so you edit the WSDL or build the XML with HttpRequest.
Q12: How does an outside system call your webservice method?
It uses the WSDL generated from the Apex class page.
Q13: Do webservice methods respect sharing?
Yes, when the class uses with sharing and queries use user mode.
Q14: What error do you get if the SOAP service fails?
A CalloutException that includes the SOAP fault message.
Advanced Questions on the Salesforce SOAP API
Q15: Why is SOAP still used?
Because many enterprise systems were built on it and rely on strict contracts.
Q16: When must you regenerate the Enterprise WSDL?
After adding or changing objects and fields the integration uses.
Q17: How do you authenticate SOAP calls without passwords?
Get an OAuth access token and send it as the session ID in the header.
Q18: What are the downsides of SOAP?
Larger messages, more setup and generated code to maintain.
Q19: Can one stub call different endpoints per org?
Yes, because each org’s Named Credential holds its own URL.
Q20: How do you keep generated classes maintainable?
Wrap them in a service class, so the rest of the code never uses them directly.
Q21: Which governor limits apply to SOAP callouts?
The same callout limits as REST, including 100 callouts and 120 seconds per transaction.
Q22: How do you migrate a SOAP integration to REST?
Add REST endpoints alongside SOAP, move callers one by one, then retire the SOAP methods.
Official Resources
- About SOAP API (SOAP API Developer Guide)
- SOAP Services: Defining a Class from a WSDL Document (Apex Developer Guide)
Quick Recap
- The Salesforce SOAP API uses XML envelopes and WSDL contracts.
- Enterprise WSDL suits one org, and Partner WSDL suits many.
- WSDL2Apex creates stubs for SOAP callouts.
- webservice methods expose Apex as SOAP.
- Test SOAP callouts with WebServiceMock.
What’s Next?
Loading thousands of records needs a different API. Next, read our guide to Salesforce Bulk API 2.0.


