Salesforce API Version Deprecation: How to Find and Update Legacy Integrations

Salesforce periodically retires older API versions, which can leave integrations relying on outdated endpoints, authentication methods, or generated client code. When a version becomes unavailable, affected REST, SOAP, and bulk API requests can fail, potentially interrupting data synchronization, scheduled jobs, and other business-critical workflows.

The challenge is identifying every integration that still depends on an outdated version. For example, legacy API calls can hide in middleware configurations, hardcoded applications, Enterprise WSDL files, or metadata that hasn't been reviewed in years. Preventing disruptions therefore requires more than just updating an API endpoint. Teams also need to verify authentication, test compatibility with supported versions, and confirm that connected business processes still complete successfully.

In this guide, we will explain how Salesforce API version deprecation and retirement work, where to find legacy API callers, and how to migrate integrations safely. We'll also cover SOAP authentication changes, metadata audits, and the testing steps needed to maintain reliable connections across enterprise systems.

Key Takeaways

• Salesforce periodically deprecates and retires older API versions, requiring integrations that use unsupported endpoints to migrate to supported versions.
• External integrations are particularly vulnerable because middleware, desktop applications, SOAP clients, and Bulk API jobs may continue using outdated endpoint versions.
• SOAP login() has a separate retirement schedule, so authentication methods need their own review alongside API version compatibility.
• "Event Monitoring", metadata scans, and Enterprise WSDL checks help identify legacy API callers before they disrupt business processes.
• Engini provides one execution layer for agent-facing connectivity across enterprise systems, helping teams manage connections, governance, and cross-system execution through a shared layer.

Understanding the Salesforce API Deprecation and Retirement Lifecycle

Salesforce API versions follow a lifecycle in which older versions are eventually deprecated and retired. Deprecation indicates that a version is approaching the end of its supported lifecycle, while retirement means requests to that version are no longer available through the affected API.

Salesforce generally supports each API version for at least three years and provides advance notice before ending support. Integrations should therefore be reviewed regularly to identify dependencies on older versions and plan migrations before compatibility problems can interrupt production workflows.

Note: An API version is often embedded in more than one place. A REST endpoint can include "/services/data/vXX.X/", a SOAP client can rely on an Enterprise WSDL generated from an older version, and a bulk API job can come from middleware that nobody opens during normal Salesforce admin work.

A clean plan separates discovery from remediation:

1. First, identify every caller.
2. Then, update the version.
3. Finally, test the business process that depends on the call.

Impact on Custom Code and External Integrations

Salesforce API retirements can disrupt external integrations because those systems often depend on versioned API endpoints. Hardcoded API endpoints, generated SOAP clients, middleware connectors, AppExchange Packages, and older custom applications can keep using legacy API versions.

That can happen even after the Salesforce organization itself has moved forward, while the issues tend to accumulate in a few specific areas. The table below shows where to look and what can break.

A hardcoded endpoint such as "/services/data/vXX.X/query/" isn't automatically upgraded just because your organization runs on a newer Salesforce release. Internal Apex classes and Visualforce pages need a more careful reading, since their configured API version can affect available language features, metadata behavior, and component behavior.

That doesn't mean every internal component breaks the same way an external REST or SOAP call does, but you should still inventory and test them, especially when obsolete metadata API version settings appear in source control.

A Note on Managed and Unmanaged Packages

Managed and unmanaged packages deserve a separate review:

• For managed packages, check the vendor's release notes or support guidance.
• For unmanaged packages, treat the code as your responsibility as it may contain old Apex, Visualforce, or metadata XML that still references legacy API versions.

A common mistake here is updating obvious external endpoint URLs while leaving metadata behind. In doing so, a team may update middleware to a supported API version, then miss an older "apiVersion" tag in a Visualforce page or Apex metadata file. This can then leave hidden behavior differences in production, even after the main integration appears healthy.

Reviewing SOAP Authentication During API Migration

SOAP authentication deserves a separate review during API migration because updating an endpoint version doesn't necessarily address an outdated login method. Salesforce is also retiring the legacy SOAP "login()" operation, making it important to identify integrations that still depend on this authentication flow.

SOAP API clients often start with a "login()" call, then use the returned session details for later operations. A legacy integration may therefore depend on a retired "login()" behavior or an old versioned SOAP endpoint. In that case, the issue can appear before any query, create, update, or delete operation runs.

To prevent this, make sure to review these areas for SOAP authentication risk:

• Enterprise WSDL clients generated from old API versions.
• Partner WSDL clients are stored in older middleware projects.
• Custom desktop applications that still authenticate through SOAP "login()".
• Batch jobs that use a username, password, and security token flow.
• Code that points to an old login host instead of the current My Domain Login URL pattern your organization expects.

A SOAP endpoint update is only part of the work, though. Authentication also involves connected user access, profile and permission set coverage, IP restrictions, token handling, and the login URL used by the client. Just to be sure, you can confirm the current method behavior within Salesforce's SOAP API login() documentation while you update callers.

Tip: Keep the authentication review separate in your remediation tracker. Mark one item for the API endpoint version, one item for the WSDL or generated client, and one item for the login flow. This approach prevents a common false positive where the endpoint version looks fixed, but the first authentication call still depends on legacy behavior.

Locating Legacy Callers in Your System

Legacy callers usually hide in places that sit outside of normal release work. Old middleware scripts, custom desktop applications, unmanaged packages, batch jobs, and generated SOAP clients can all keep calling legacy API versions for years.

We recommend using three discovery paths before you start changing versions:

1. Runtime logs show who is calling Salesforce.
2. Source metadata shows which internal components still carry old "apiVersion" values.
3. WSDL checks show whether SOAP clients were generated from retired versions.

Keep these three paths separate, because API version deprecations aren't always visible from "Setup" alone. For instance, a connected user and client IP may point to middleware, while a local XML tag may lead to custom code and components.

Checking API Total Usage via "Event Monitoring"

"Event Monitoring" is the first place to look for live legacy callers, because it shows runtime activity rather than only source configuration. This is because its event log files capture the real API calls hitting your organization.

For best results, make sure to start in the organization you need to audit and follow this path:

"Salesforce Setup" → "Event Monitoring" → "Event Log File Browser" → "API Total Usage".

From there, pull the right log by:

1. Setting the date range to cover normal business cycles, including nightly and weekly jobs.
2. Downloading or inspecting the log output.
3. Filtering for API versions that Salesforce has deprecated, retired, or scheduled for retirement.
4. Reviewing the connected user, client IP, user agent, request URI, and application context where those fields are present.

Here, you are really after the who and what: which connected user made the call, which client IP it came from, and which application likely owns the endpoint. A single integration user can stand in for separate batch, middleware, and reporting jobs, so don't stop at the username alone.

Once you find an old version, trace it back to its owner. The table below shows what each log clue usually tells you and where to check next.

Tip: If your organization doesn't expose the browser the way your team expects, query or export EventLogFile data through supported Salesforce tooling. Either way, make sure to work from observed runtime calls instead of only from a source code search.

Auditing Component Metadata and XML Tags

Runtime logs catch active external callers, while metadata scans – internal configuration and code that may not run during your log window. So, make sure to pull your Salesforce metadata into a local workspace or IDE from a sandbox environment, then search for the XML tag "apiVersion".

Next, compare the API versions found in your metadata against Salesforce's current support policy and prioritize components using deprecated or retired versions, particularly those involved in business-critical integrations.

Check these areas first:

• Apex classes.
• Apex triggers.
• Visualforce pages.
• Visualforce components.
• Aura components.
• Lightning Web Components (LWC), where metadata files define an API version.
• Flows and other metadata types that carry version settings.
• Unmanaged packages stored in source control.
• Older deployment manifests and build scripts.

Tip: Use a sandbox environment for the first pass. Update the "apiVersion" value, deploy to the sandbox, run unit tests, and test the actual user path, because compile success alone isn't enough when older components may behave differently after a version jump.

Generating Enterprise WSDLs for Version Checks

SOAP integrations need a WSDL review because a generated client can carry old assumptions even when the endpoint string looks current. The Enterprise WSDL is strongly typed to your organization's schema, so it deserves separate handling from REST endpoint searches.

For best results, use this click path:

"Setup" → "API" → "Generate Enterprise WSDL"

Generate the current Enterprise WSDL from a sandbox environment first. Then, compare it with the WSDL file stored in your middleware repository, desktop application, or SOAP client project.

And while you’re at it, we recommend also checking for the following:

• The API version in the WSDL endpoint or metadata.
• Generated client code that still references old SOAP bindings.
• Hardcoded login URLs or service URLs.
• Regeneration steps in the build process.
• Custom objects and fields that changed since the old WSDL was generated.

Note: SOAP clients often need more than a find and replace as regenerating the client can change classes, bindings, namespaces, or object definitions. That's expected work, and it should happen before production release pressure makes testing harder.

How to Update Your Legacy API Callers

Remediation starts after you identify the caller and the owning workflow. We advise against updating every string directly in production – instead, move one caller at a time through sandbox testing, owner review, and production cutover.

A safe remediation sequence looks like this:

1. Inventory each caller by owner, system, endpoint, API type, and business process.
2. Confirm whether the caller uses REST API, SOAP API, Bulk API, Tooling API, or metadata operations.
3. Replace deprecated or retired endpoint versions with a currently supported version.
4. Choose a target API version compatible with your application's dependencies, client libraries, and Salesforce environment.
5. Regenerate SOAP WSDL clients where needed.
6. Update Apex classes, triggers, Visualforce pages, and metadata XML "apiVersion" values in a sandbox environment.
7. Run automated tests and business process tests.
8. Validate authentication separately, especially for SOAP "login()".
9. Promote the change through your normal release process.
10. Monitor your "API Total Usage" stat after deployment to confirm old versions are no longer active.

Test the Business Outcome and Not Just the Call

"Endpoint-not-found" errors are only one kind of problem you’ll likely face. You may also see authentication errors, object or field errors, changed response handling, or stalled batch jobs. That's why the test should cover the business outcome beyond the HTTP status.

A newer supported API version can include changed behavior, stricter validation, or bug fixes that affect older client assumptions. So, make sure to test the full workflow after the version change. For example, a CRM to ERP flow should test the full handoff. While testing, also confirm that the Salesforce event fires and the integration reads the expected Salesforce data.

Then, verify that the destination system accepts the write and the audit record shows the outcome – after all, a successful API call alone does not prove the full workflow works.

Cover Scheduled, Outbound, and Tooling Jobs

Treat bulk API jobs with care. Large extract or load jobs often run outside normal working hours, so a short daytime test may miss the job that matters. We therefore recommend that you include nightly, weekly, and month-end jobs in your validation window.

If your system uses outbound messages, also include "Outbound Message Timeout" handling in the validation plan. Then, confirm what happens when the receiving system is slow, unavailable, or returns an error.

Finally, tooling API usage also deserves a look as build tools, deployment scripts, and internal admin utilities may call Salesforce APIs directly. They're easy to miss because they don't look like customer-facing revenue workflows, but they can still block releases or operational work.

How Engini Can Help

Managing API compatibility becomes more demanding when AI agents need to work across Salesforce, NetSuite, and other enterprise applications. This is because each connection introduces authentication requirements, API changes, permissions, and ongoing maintenance responsibilities.

Engini provides one managed execution layer for AI agents across enterprise systems. Our managed connectors help you reduce the burden of maintaining agent-facing connections, while the Agent Gateway and Agent Policy tools provide you with centralized connectivity, scoped permissions, and clear visibility into cross-system actions.

Keeping Salesforce Integrations Compatible Over Time

Salesforce API version retirement is an ongoing maintenance concern for organizations that depend on external integrations. Even when an API upgrade appears straightforward, outdated endpoints, generated clients, authentication methods, and metadata can introduce failures that aren't immediately visible.

The safest approach is to maintain an inventory of API consumers, monitor version usage, and test integrations against supported versions before retiring existing connections. Ideally, your validation should cover the complete business process, including authentication, data synchronization, destination-system writes, and error handling.

For organizations managing multiple enterprise integrations, connector maintenance also needs clear ownership. Native APIs and established integration tools can handle many of these requirements, while AI-driven workflows spanning several systems may benefit from centralized connectivity, permissions, and execution monitoring.

At the end of the day, regular compatibility reviews and controlled migrations are the things that will help you prevent outdated API dependencies from becoming unexpected production issues.

Frequently Asked Questions

How can I check which Salesforce API versions are still supported?

Consult Salesforce's official API end-of-life documentation for the REST, SOAP, or Bulk API you're using. The documentation identifies supported versions, deprecated versions, and versions that are no longer available.

You can then compare those versions with the endpoints, generated clients, and configuration files used by your integrations. Here, "API Total Usage" event logs can also help identify the versions external applications are actively calling.

Do Salesforce API version retirements affect Apex classes and Visualforce pages?

External API version retirements and internal component API versions don't necessarily have the same impact. Apex classes and Visualforce pages use configured API versions that can influence available features and runtime behavior.

Make sure to review outdated component versions as part of your broader compatibility audit, but avoid changing them solely because an external REST or SOAP API version has retired. Also test proposed upgrades in a Salesforce sandbox to identify behavioral changes before deploying them to production.