Metadata WSDL
The Metadata WSDL is the SOAP-based interface definition for the Salesforce Metadata API.
Definition
The Metadata WSDL is the SOAP-based interface definition for the Salesforce Metadata API. The Web Service Description Language (WSDL) file is downloaded from Salesforce Setup and imported into developer tools (Java, .NET, or anywhere SOAP clients run) to generate stub code for calling the Metadata API operations: retrieve, deploy, list, and describe. The Metadata WSDL was the original primary interface for metadata operations before Salesforce launched the REST-based Metadata API and the modern Salesforce CLI workflow.
The Metadata WSDL is still supported today and powers many enterprise CI/CD tools (Copado, AutoRabit, Gearset) under the covers. Modern developers rarely interact with the WSDL directly; instead, they use the Salesforce CLI, which wraps both the SOAP and REST Metadata APIs and exposes a consistent command-line interface. The WSDL remains relevant for legacy integration patterns, for tools that prefer SOAP, and for Apex code that wants to call the Metadata API programmatically via WSDL2Apex-generated classes.
How the Metadata WSDL fits the modern Salesforce deployment story
Download from Setup
The Metadata WSDL is available under Setup, API. Click Generate Metadata WSDL to download the XML file. The WSDL is versioned per Salesforce release; download the version matching your target org''s API version. Tools that consume the WSDL import it once and generate Java, C#, or other-language stub code.
SOAP vs. REST Metadata APIs
Salesforce ships two Metadata API implementations: the original SOAP-based API (Metadata WSDL) and the newer REST-based API. Both expose the same operations and the same metadata types; the choice between them is mostly about client-tool preference. Java enterprise tools historically used SOAP; modern Salesforce CLI and Node.js tools use REST.
Key WSDL operations
The Metadata API exposes a small set of operations. retrieve and retrieveStatus pull metadata XML from an org. deploy and deployStatus push metadata to an org. list returns components of a chosen type. describeMetadata returns the schema of supported metadata types. The WSDL declares these operations; client tools call them via SOAP requests.
Apex and the Metadata WSDL
Apex code can call the Metadata API by importing the Metadata WSDL via Setup, Apex Classes, Generate from WSDL. The generated classes provide strongly-typed Apex access to the Metadata API operations. This pattern is rare but valuable: Apex code can deploy metadata changes from within Salesforce, useful for self-service admin workflows.
Tools that consume the WSDL
Many CI/CD tools and integration platforms use the Metadata WSDL under the covers. Copado, AutoRabit, Gearset, ANT-based Force.com Migration Tool, and third-party deployment platforms all generate Java client code from the WSDL and call the Metadata API. Modern Salesforce CLI users rarely see the WSDL directly because the CLI handles the integration.
Authentication
Metadata WSDL clients authenticate via SOAP with SessionId-based authentication. The client logs in via the Partner WSDL''s login operation, retrieves a session ID, then includes the session ID in every Metadata WSDL call''s SOAP header. The session-based authentication is older than modern OAuth flows but still works.
Version compatibility
The Metadata WSDL is versioned. WSDLs downloaded at API version 50 work against orgs at that version or higher; calling features only available in version 55 from a version-50 WSDL fails. Always download the WSDL at the version you target; tools that ship with bundled WSDLs need periodic refresh as Salesforce releases progress.
Use the Metadata WSDL in a custom integration
Most modern Salesforce deployment work doesn''t require touching the Metadata WSDL directly. Use it when building custom integration tools or extending Apex with metadata operations.
- Download the Metadata WSDL
Setup, API, Generate Metadata WSDL. Save the XML file locally.
- Generate client code from the WSDL
Use wsimport (Java), svcutil (C#), or Apex''s WSDL2Apex (in Salesforce) to generate stub code from the WSDL.
- Authenticate against the org
Use the Partner WSDL''s login operation to get a session ID. Include the session ID in the Metadata WSDL SOAP header.
- Call Metadata API operations
Call retrieve, deploy, list, or describeMetadata via the generated client. Handle the async-status pattern for retrieve and deploy.
- Or use the Salesforce CLI
For most use cases, the Salesforce CLI is the simpler choice. It wraps both the SOAP and REST Metadata APIs and handles authentication automatically.
- Refresh the WSDL per release
Salesforce ships new metadata types each release. Re-download the WSDL periodically to pick up the new types in your generated client code.
- The Metadata WSDL is versioned. Mixing WSDL versions with target org API versions causes silent failures or missing types.
- Authentication uses SessionId, not OAuth. The Partner WSDL provides login; the session works for both Partner and Metadata operations.
- Most modern work uses the Salesforce CLI instead of direct WSDL integration. The CLI handles authentication and async-status patterns automatically.
- Apex WSDL2Apex is heap-intensive for large WSDLs. The Metadata WSDL imports into Apex but the generated class is hundreds of KB; test the import before relying on it in production.
Trust & references
Cross-checked against the following references.
- Metadata API Developer GuideSalesforce Developers
- Partner WSDLSalesforce Developers
Straight from the source - Salesforce's reference material on Metadata WSDL.
- Use a WSDLSalesforce Help
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 the Metadata WSDL?
Q2. Where do you download the Metadata WSDL?
Q3. What's the modern alternative?
Discussion
Loading discussion…