WSDL (Web Services Description Language) File
A WSDL (Web Services Description Language) file in Salesforce is an XML document that describes the operations, data types, and endpoints exposed by the SOAP API.
Definition
A WSDL (Web Services Description Language) file in Salesforce is an XML document that describes the operations, data types, and endpoints exposed by the SOAP API. A development tool reads this file and generates strongly typed client code, so your application can call Salesforce without hand-writing raw SOAP envelopes.
Salesforce publishes several WSDLs from Setup. The two you reach for most are the Enterprise WSDL, which mirrors your own org's objects and fields, and the Partner WSDL, which is generic and works against any org. There are also Metadata, Apex, and Tooling WSDLs for those specific SOAP services.
How the WSDL turns SOAP into typed code
What a WSDL actually describes
A WSDL is a contract written in XML. It tells a client three things: which operations the service offers, what the request and response messages look like, and where to send them. For the Salesforce SOAP API, the operations are calls like create, update, upsert, query, and delete. The message definitions spell out every field, its data type, and whether it is required. Because the contract is machine readable, you do not parse it by hand. You feed the WSDL to a code generator such as Apache Axis, wsdl2java, or the WSDL import wizard in Visual Studio. The tool produces classes and method stubs that match the service. Your code then calls a method like create on a typed object, and the library handles the SOAP envelope, headers, and HTTP transport underneath. This is the defining trait of SOAP integration. The schema is fixed up front, so the compiler catches a misspelled field or a wrong type before the call ever runs. That safety is why SOAP still suits older Java and .NET stacks that lean on strong typing.
Enterprise WSDL versus Partner WSDL
Salesforce gives you two general purpose WSDLs, and the choice shapes how your code reads. The Enterprise WSDL is strongly typed and specific to one org. It includes every standard and custom object, plus every custom field, as concrete types. So Account has a real Industry field and your custom Invoice__c object appears by name. This makes code easy to read and the compiler strict. The trade-off is that the Enterprise WSDL is tied to your org's current metadata. Add a custom field or object and the WSDL is now out of date. You regenerate it and recompile your client to pick up the change. That coupling is fine for an integration that targets one known org. The Partner WSDL is loosely typed and generic. It does not name your custom objects. Instead it exposes a flexible sObject type, and you read or write fields by name as key and value pairs. One Partner WSDL works against any Salesforce org and survives schema changes without regeneration. ISV partners and AppExchange apps that must run in many customer orgs use it for exactly that reason.
The other WSDLs Salesforce publishes
Beyond the two data WSDLs, Setup offers several more, each scoped to a different SOAP service. The Metadata WSDL drives the Metadata API. You import it to call deploy and retrieve, the operations that move configuration like objects, fields, and profiles between orgs as file based packages. Build and release tooling leans on it heavily. The Apex WSDL exposes the Apex API, which lets external tools compile and run anonymous Apex and execute test classes from outside the org. The Tooling WSDL backs the Tooling API for IDE-style work against metadata, though many teams now use its REST flavor instead. There are also smaller WSDLs for specific features. The Delegated Authentication and Single Sign-On WSDLs define the callback services your identity provider implements. The Outbound Message WSDL is generated per workflow or flow action, and it describes the SOAP message Salesforce will send to your listener endpoint. Each WSDL is just a description of one service, so you download only the ones your integration touches.
Where the WSDL fits against REST
Most new Salesforce integration today uses the REST API, not SOAP, and REST does not use a WSDL at all. REST is built on plain HTTP verbs like GET, POST, PATCH, and DELETE, and it usually exchanges JSON. You discover resources through the API rather than from a generated contract, and you authenticate with OAuth. That lighter footprint fits mobile apps and modern web services well. SOAP, and therefore the WSDL, still earns its place in specific spots. Legacy middleware and ERP or finance systems often ship rich SOAP tooling, so a typed client is faster to stand up there. Some operations also live only in SOAP services, the Metadata API being the clearest example. Outbound messages, a no-code way to push record changes out of Salesforce, are SOAP based too. A good rule of thumb: reach for REST first for new work, and use a WSDL when you need the Metadata API, outbound messages, or you are extending an established SOAP integration. The two API styles coexist, and many orgs run both.
A worked Enterprise WSDL integration
Picture a finance team that wants their .NET billing app to read Accounts and write a custom Invoice__c record back into Salesforce. Because they target one org and want compile-time checking, they choose the Enterprise WSDL. An admin opens Setup, generates the Enterprise WSDL, and saves the XML file. A developer adds it as a service reference in Visual Studio, which generates a typed proxy. The app calls login with a username, password, and security token to get a session ID and the server URL. From then on, every call passes that session ID in the SOAP header. To create an invoice the code instantiates an Invoice__c object, sets Amount__c and the Account lookup, and calls create. The response returns the new record Id or an array of errors. When the team later adds a Due_Date__c field, the existing client cannot see it. The admin regenerates the Enterprise WSDL, the developer refreshes the service reference, and the new field becomes available. That regenerate-and-recompile loop is the cost of the strong typing they wanted.
Versions, sessions, and common gotchas
Every WSDL is pinned to an API version, shown as a number like 64.0 in the binding. Generate the WSDL at a given release and your client speaks that version until you regenerate at a newer one. Older versions keep working for years, but a feature added in a later release will not appear in an older WSDL. Authentication trips people up most. SOAP API has a built-in login call that returns a session ID, and that ID, not a password, authorizes later calls. The endpoint you log in to should be your My Domain login URL, and the login response hands back the correct server URL to use for the session. Sandbox logins go to the test instance, not production. The other frequent mistake is forgetting to regenerate the Enterprise WSDL after a metadata change, then wondering why a new field is missing in code. Partner WSDL users avoid this because fields are addressed by name at runtime. Whichever you pick, keep the generated client and the WSDL version in sync with what your org actually exposes.
How to download and use a Salesforce WSDL
You do not create a WSDL by hand. You generate and download it from Setup, then import it into your development tool to produce client code. Here is the path for the Enterprise and Partner WSDLs.
- Open the API page in Setup
From Setup, enter API in the Quick Find box, then under Integrations select API. This page lists every downloadable WSDL and the client certificate options.
- Pick the right WSDL
Choose Generate Enterprise WSDL for a strongly typed file tied to your org, or Generate Partner WSDL for a generic file that works across orgs. Metadata, Apex, and Tooling WSDLs are listed here too.
- Generate and save the file
For the Enterprise WSDL, confirm the package version prompt, then click Generate. The browser shows the XML, which you save with a .wsdl extension to a known folder.
- Import it into your tool
Feed the saved file to a code generator such as wsdl2java, Apache Axis, or a Visual Studio service reference. The tool builds typed classes and method stubs you call from your app.
- Regenerate after schema changes
When you add custom objects or fields, regenerate the Enterprise WSDL and refresh your client so the new metadata is available. Partner WSDL clients address fields by name and need no regeneration.
Strongly typed and specific to your org, with custom objects and fields as concrete types. Best when you target one known org and want compile-time checking.
Loosely typed and generic, using a flexible sObject and field name and value pairs. Best for ISV and AppExchange apps that run in many customer orgs.
Backs the Metadata API deploy and retrieve calls for moving configuration between orgs as file based packages. Used by build and release tooling.
An optional certificate you download here to authenticate outbound callbacks like outbound messages or delegated authentication endpoints.
- The Enterprise WSDL goes stale the moment you change metadata. Forgetting to regenerate it is the top reason a new field is missing from your client code.
- Log in to your My Domain login URL and reuse the session ID and server URL from the login response. Pointing later calls at the wrong instance returns INVALID_SESSION_ID errors.
- Each WSDL is pinned to an API version. A feature from a newer release will not appear until you regenerate the WSDL at that version and rebuild.
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on WSDL (Web Services Description Language) File.
Hands-on resources to go deeper on WSDL (Web Services Description Language) File.
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 a WSDL file?
Q2. What are the two main Salesforce WSDLs?
Q3. Is SOAP the modern approach?
Discussion
Loading discussion…