Back in 2021, we announced a plan to retire legacy Platform API versions on a yearly basis, so that our engineering teams could focus their development efforts on enhancing the latest API versions to improve the overall Salesforce experience when building custom functionality via applications. In this post, we’ll share an important update to the legacy API retirement plan, some tips on how to identify legacy API usage, and how to update those API requests.

Important update to the legacy API retirement plan

The latest phase of the legacy API retirement plan was announced in early 2022 and took effect during the Summer ’22 release. With this release, we deprecated SOAP, REST, and Bulk API versions ranging from 21.0 to 30.0. As part of our original plan, these API versions would no longer be supported, but would remain available until we retire them in the Summer ’23 release.

Following consultation with the community and our partners, we decided to delay the upcoming API retirement to the Summer ’25 release to ensure a smooth transition (see knowledge article). Due to this extension, APIs version 21.0 to 30.0 are still unsupported, but they will remain available until the Summer ’25 release.

Since Summer ’21, whenever you issue a call to a legacy API with the REST or Bulk API, you’ll notice a Warning header in the response with a message describing the issue such as this one:

Once legacy API versions are retired in Summer ’25, requests to those versions will fail with the following errors:

• REST API will return HTTP status 410: GONE
• SOAP API will return HTTP status 500: UNSUPPORTED_API_VERSION
• Bulk API will return HTTP status 400: InvalidVersion

Now that you know about the latest plan, let’s look at how you can identify if, and how, you’re impacted.

Identify legacy API usage

You can check for legacy API calls yourself at any time, and there are several ways to do it.

All Salesforce API transactions are recorded in Event Monitoring logs. Event Monitoring normally requires a specific license, but we’ve exposed the API Total Usage (ApiTotalUsage) event to all customers for free, so that you can monitor legacy API consumption and identify clients and integrations that need to be upgraded. API-enabled organizations have free access to the API Total Usage event log files with 1-day data retention. With Event Monitoring enabled, you can access this and all other event log file types with 30-day data retention.

Logs contain key fields which guide your investigations:

• CLIENT_NAME is optionally provided by clients, but it is especially helpful to pinpoint apps and integrations that are performing API calls that require investigation and adjustments. We’ll share more on this field in the last section of this post.
• CONNECTED_APP_ID tells you which connected app is at the origin of API calls.
• USER_ID and CLIENT_IP are helpful to identify the source of legacy API calls, but there’s a chance that these values are shared between several apps in case a technical user/system account (shared user ID) or calls are being made from a physical office location (shared IP address). We’ll share how to use the new Integration User license to address shared user issues in the last section of this post.
• API_FAMILY, API_VERSION, API_RESOURCE, URI and HTTP_METHOD fields give you precious clues about the type of operations that are performed by API clients.

We shared several tools for accessing logs in our previous post, and you can also use third-party tools to automate this task. We’ll share an additional option that may be relevant for users concerned about running third-party code with API access to their org.

Using Postman to identify legacy API usage

You can use the Salesforce Platform APIs Postman collection to inspect your Salesforce logs with these steps:

• Set up the Postman collection and authenticate to your org.
• List the log files that track API access:
  1. Select the REST > Query request.
  2. Replace the value of the q query parameter with the following SOQL query: SELECT LogFile, EventType, CreatedDate FROM EventLogFile WHERE EventType IN ('API', 'RestApi', 'BulkApi', 'ApiTotalUsage')
  3. Click Send.
  4. Retrieve the log file IDs from the response.

• For every log file returned in the previous step, retrieve and scan the log content:
  1. Select the REST > Logs > Get event log file request.
  2. Set the log file ID in the id path variable value.
  3. Click Send.
  4. Read the log file’s content in the response. You can either move to the Raw response tab and save it as a CSV file or use the Visualize tab to preview the content directly in Postman.
  5. Look at the URI or API_VERSION column and check for legacy API versions (versions 30.0 and below).

After identifying that you are calling legacy API versions, the next step is to update these dependencies to legacy API versions.

Update dependencies to legacy API versions

The upgrade procedure depends on the type of API that you’re using, but here’s a short overview of what’s required:

• For SOAP-based API calls, generate a new WSDL and incorporate it into the impacted integration
• For REST endpoints, update the version number in the URI to the current major release
• Though you can similarly update URIs for /async endpoints in the case of Bulk API, the most rewarding way to upgrade legacy calls is to adopt Bulk API 2.0 and enjoy the simpler workflow and improved limits!

Keep in mind that applications (e.g., Data Loader) and packages may also be making legacy API calls because of outdated libraries (Web Services connectors, AJAX Toolkit, SForceOfficeToolkit COM interface, or Force.com Toolkit for PHP, just to name a few). Make sure to upgrade those as well.

And remember: no matter the change, be sure to perform regression tests to ensure everything is working as expected.

Preparing for the future

Whether you were impacted by the legacy retirement plan or not, you should plan for future API version retirement. We’ll leave you with some best practices for API governance.

Leverage Salesforce Integration user licenses

In Spring ‘23, we introduced a new license type dedicated to integrations: the Salesforce Integration user license. This new license is based on the principle of least privilege access and allows you to create API-only users for system-to-system integrations with specific access rights. The main advantage of this new license type is security, but it also allows for better tracking of integration actions since you’ll be able to assign distinct API-only users to integration and relate integration API calls with specific user IDs in your logs.

Five Salesforce Integration user licenses are included in each Enterprise, Unlimited, and Performance Edition org. You can also reach out to your Account Executive should you need more.

Specify a client name when building REST API integrations

When building new integrations with the REST API, make sure to specify a client name using the Sforce-Call-Options request header like so:

Sforce-Call-Options: client=myClientName

The client name that you specify in the header will be visible in the logs under the CLIENT_NAME field. This helps you to debug and audit integration API calls.

Closing words

We hope that this additional delay to our legacy API retirement plan will allow for a smooth transition, and we encourage you to get started today regardless of the new deadline. Migrating to newer API versions is always a safe bet for getting access to new capabilities and improved performance and security.

About the author

Philippe Ozil is a Principal Developer Advocate at Salesforce where he focuses on the Salesforce Platform. He writes technical content and speaks frequently at conferences. He is a full-stack developer and enjoys working on DevOps, robotics, and VR projects. Follow him on Twitter @PhilippeOzil or check his GitHub projects @pozil.