SOAP API Developer Guide
jNewer Version Available
Introducing SOAP API
Salesforce provides programmatic access to your org’s information using simple, powerful, and secure application programming interfaces. To use this document, you should have a basic familiarity with software development, web services, and the Salesforce user interface.
Any functionality described in this guide is available if your org has the API feature enabled. This feature is enabled by default for Performance, Unlimited, Enterprise, and Developer Editions. Some Professional Edition orgs have the API enabled. If you can’t access the features you see in this guide, contact Salesforce.
When to Use the SOAP API
The Salesforce prebuilt applications provide powerful CRM functionality. In addition, Salesforce provides the ability to customize the prebuilt applications to fit your organization. However, your organization may have complex business processes that are unsupported by the existing functionality. In this case, Lightning Platform provides various ways for advanced administrators and developers to build custom functionality. These include SOAP API, Apex, and Visualforce.
SOAP API
Use SOAP API to create, retrieve, update or delete records, such as accounts, leads, and custom objects. With more than 20 different calls, SOAP API also allows you to maintain passwords, perform searches, and much more. Use SOAP API in any language that supports web services.
REST API
REST API provides a powerful, convenient, and simple REST-based web services interface for interacting with Salesforce. Its advantages include ease of integration and development, and it’s an excellent choice of technology for use with mobile applications and web projects. For certain projects, you may want to use REST API with other Salesforce REST APIs. To build UI for creating, reading, updating, and deleting records, including building UI for list views, actions, and dependent picklists, use User Interface API. To build UI for B2B Commerce on Lightning, CMS managed content, Experience Cloud sites, or Chatter, use Connect REST API. If you have many records to process, consider using Bulk API, which is based on REST principles and optimized for large sets of data.
Bulk API
Use Bulk API 2.0 to query, queryAll, insert, update, upsert, or delete a large number of records asynchronously. Bulk API 2.0 is designed on the Salesforce REST framework.
Other Salesforce Platform APIs, such as SOAP API or REST API, are optimized for synchronous client applications that update a few records at a time. You can use SOAP API for processing many records, but when the data sets contain hundreds of thousands of records, synchronous operations are less practical. Bulk API 2.0 is designed to make it simple to process data from a few thousand to millions of records.
Metadata API
Use Metadata API to retrieve, deploy, create, update, or delete customizations for your org. The most common use is to migrate changes from a sandbox or testing org to your production environment. Metadata API is intended for managing customizations and for building tools that can manage the metadata model, not the data itself.
The easiest way to access the functionality in Metadata API is to use the Salesforce Extensions for Visual Studio Code or Salesforce CLI. Both tools are built on top of Metadata API and use the standard tools to simplify working with Metadata API.
- The Salesforce Extensions for Visual Studio Code includes tools for developing on the Salesforce platform in the lightweight, extensible VS Code editor. These tools provide features for working with development orgs (scratch orgs, sandboxes, and DE orgs), Apex, Aura components, and Visualforce.
- Salesforce CLI is ideal if you use scripting or the command line for moving metadata between a local directory and a Salesforce org.
Apex
- Create Web services.
- Create email services.
- Perform complex validation over multiple objects.
- Create complex business processes that are not supported by workflow.
- Create custom transactional logic (logic that occurs over the entire transaction, not just with a single record or object).
- Attach custom logic to another operation, such as saving a record, so that it occurs whenever the operation is executed, regardless of whether it originates in the user interface, a Visualforce page, or from SOAP API.
For more information, see the Apex Developer Guide.
Visualforce
- Build wizards and other multistep processes.
- Create your own custom flow control through an application.
- Define navigation patterns and data-specific rules for optimal, efficient application interaction.
For more information, see the Visualforce Developer's Guide.
Customize, Integrate, and Extend Your Salesforce Solutions
The Lightning Platform allows you to customize, integrate, and extend your Salesforce organization using the language and platform of your choice:
- Customize Salesforce with custom fields, links, objects, page layouts, buttons, record types, s-controls, and tabs to meet specific business requirements.
- Integrate Salesforce with your org’s ERP and finance systems. Deliver real-time sales and support information to company portals and populate critical business systems with customer information.
- Extend Salesforce in presentation, business logic, and data services with new functionality that reflects the business requirements of your org.
For more information about Lightning Platform solutionsand developer resources, go to Salesforce Developers.
Supported Salesforce Editions
To use SOAP API, your org must use Enterprise Edition, Performance Edition, Unlimited Edition, or Developer Edition. If you’re an existing Salesforce customer and want to upgrade to Enterprise, Unlimited, or Performance Edition, contact your account representative.
It is recommended that you use Developer Sandbox to develop Web service client applications. Developer Sandbox is an exact replica of your Salesforce deployment, including all customization and data. For more information, see Deploy Enhancements from Sandboxes.
Developer Edition provides access to all features available with Enterprise Edition. Developer Edition is constrained only by the number of users and the amount of storage space. Developer Edition provides a development context that allows you to build and test your solutions without affecting your org’s live data. Developer Edition accounts are available for free at developer.salesforce.com/gettingstarted.
Standards Compliance
SOAP API is implemented to comply with the following specifications:
| Standard Name | Website |
|---|---|
| Simple Object Access Protocol (SOAP) 1.1 | https://www.w3.org/TR/2000/NOTE-SOAP-20000508/ |
| Web Service Description Language (WSDL) 1.1 | http://www.w3.org/TR/2001/NOTE-wsdl-20010315 |
| WS-I Basic Profile 1.1 | http://www.ws-i.org/Profiles/BasicProfile-1.1-2004-08-24.html |
Development Platforms
SOAP API works with current SOAP development environments, including, but not limited to, Visual Studio .NET 2005. In this document, we provide examples in Java and C# (.NET). The Java examples are based on WSC 20.0 (WSC) and JDK 6 (Java Platform Standard Edition Development Kit 6). Other versions of WSC are available at https://github.com/forcedotcom/wsc and http://mvnrepository.com/artifact/com.force.api/force-wsc. To see a complete list of compatible development platforms and more sample code, go to developer.salesforce.com.
SOAP API Support Policy
Salesforce recommends that your new client applications use the most recent version of the Lightning Platform WSDL file to fully exploit the benefits of richer features and greater efficiency. You can navigate to the most recent WSDL for your organization from Setup by entering API in the Quick Find box, then selecting API. When a new version is released, use the following steps in Quick Start to update your WSDL:
- Regenerate the WSDL file (see Step 2: Generate or Obtain the Web Service WSDL)
- Import it into your environment (see Step 3: Import the WSDL File Into Your Development Platform)
Backward Compatibility
Salesforce strives to make backward compatibility easy when using the Lightning platform.
Each new Salesforce release consists of two components:
- A new release of platform software that resides on Salesforce systems
- A new version of SOAP API
For example, the Winter ’07 release included SOAP API version 9.0 and the Summer ’07 release included SOAP API version 10.0.
We maintain support for each SOAP API version across releases of the platform software. SOAP API is backward compatible in that an application created to work with a given SOAP API version will continue to work with that same SOAP API version in future platform software releases.
Salesforce does not guarantee that an application written against one SOAP API version will work with future SOAP API versions: Changes in method signatures and data representations are often required as we continue to enhance SOAP API. However, we strive to keep SOAP API consistent from version to version with minimal, if any, changes required to port applications to newer SOAP API versions.
For example, an application written using SOAP API version 9.0 which shipped with the Winter ’07 release will continue to work with SOAP API version 9.0 on the Summer ’07 release and on future releases beyond that. However, that same application may not work with SOAP API version 10 without modifications to the application.
API End-of-Life
Salesforce is committed to supporting each API version for a minimum of three years from the date of first release. In order to mature and improve the quality and performance of the API, versions that are more than three years old might cease to be supported.
When an API version is to be deprecated, advance notice is given at least one year before support ends. Salesforce will directly notify customers using API versions planned for deprecation.
Choosing a WSDL
There are two Lightning Platform Web services for which you can obtain WSDL files for API access:
-
Lightning Platform Enterprise WSDL—This API is for most enterprise users who
are developing client applications for their org. The enterprise WSDL file is a strongly
typed representation of your org’s data. It provides information about your schema,
data types, and fields to your development environment, allowing for a tighter integration
between it and the Lightning Platform Web service. This WSDL changes if custom fields or
custom objects are added to, renamed, or removed from, your org’s Salesforce
configuration. If you are downloading an enterprise
WSDL and you have managed packages installed in your organization, you need to take an extra
step to select the version of each installed package to include in the generated WSDL.Note the following when generating the enterprise WSDL:
- If new custom fields or objects are added to, renamed, or removed from your org’s information, you must regenerate the WSDL file to access them.
- The generated WSDL contains the objects and fields in your org, including those available in the selected versions of each installed package. If a field or object is added in a later package version, you must generate the enterprise WSDL with that package version to work with the object or field in your API integration.
- Lightning Platform Partner WSDL—This API is for Salesforce partners who are developing client applications for multiple orgs. As a loosely-typed representation of the Salesforce object model, the partner WSDL can be used to access data within any org.