How to migrate integrations away from Legacy API Version 3.0
If you have existing integrations built against our Legacy API Version 3.0, you will need to migrate away from those endpoints
before April 18, 2025. The migration process is the following:
- Make a list of all
/v3 API endpoints that are consumed by your existing integrations.
- For each endpoint that you currently consume, update your integration to use one of our new API endpoints.
The legacy endpoints all start with
/v3 and the new endpoints all start with services/.
For example, if your integration uses our legacy List Events endpoint at /v3/events,
you should now start using the replacement List Events endpoint at /services/events/v1/events.
- If you were using pagination for our Legacy API Version 3.0, this behavior has changed for all paginated endpoints.
Paginated endpoints will no longer wrap around to the start of the collection if you follow the next page link
from the last results page.
- Some other small formatting changes to your integrations may also be required to use our new versioned API services.
To determine if any such changes are required in your case, please read the published Changelog for the associated service.
For example, if you were migrating the List Events endpoint mentioned above, you would want to read the
Changelog for the Events service.
The Changelogs are all linked from the API Documentation section of this page.
This migration process is a technical task. As API integrations with external customer systems
belong to our customers, we would recommend engaging your own IT
support staff in the event that you need technical assistance.
Our versioning policy
Our APIs have a major and a minor version number. Version numbers begin with 1.0.
A breaking change is a change in an API behavior or schema that may require an
update in an application consuming our API. For example, removing an attribute
from an object or returning a new HTTP status code is a breaking change.
When we make a significant non-breaking addition to a service, we will release it
as a new minor version of that service.
For example, Version 1.1 would be the first minor version after the initial Version 1.0.
When we make a breaking change to a service, we will release it as a new major version of that service.
For example, the first major version after Version 1.x would be Version 2.0.
When we make small, non-breaking changes and bugfixes to a service outside of a minor release,
we will simply note them in the changelog without incrementing the version number.
Suggestions for API uptake
When you begin a new project, use the most recent available version of the API service you need.
When we release a new minor version of a service that you are already using, you will not need to do anything to update your integrations.
You may choose to uptake any newly added features as you wish.
Each major version of a service will be supported for at least 18 months at a time.
Deprecations will be announced in advance through normal customer communication channels.
At the end of the deprecation period for a major version, you would need to update your integrations to use a more recent version of the service.
API Frequently Asked Questions
-
Q: I lost my Strategic Sourcing Personal API Tokens, is there a way to retrieve them?
-
A: API token information is only displayed once in Strategic Sourcing.
If you no longer have access to your token information, we recommend generating
a new token in your User Profile by selecting Personal API Tokens under Integrations.
-
Q: When using the APIs, how can I view more than 10 records at a time?
-
A: You can add a query to control the pagination on a request,
though the maximum pagination size is 100 results per request.
Further detail can be found in the Pagination section of the documentation for each API service.
-
Q: I am receiving a value of null when attempting an API call. What might cause this?
-
A: Confirm that the user whose API keys being used have access to the data
they are trying to pull in WSS. We recommend adding the user to a Full Access
team with visibility into all Projects and Contracts.
-
Q: Are we able to update or pull stakeholder lists via WSS APIs?
-
A: No. Customers can use APIs to get or update the project owner, creator and
requester but not to list all stakeholders on an event, project, or contract.
-
Q: The user whose API keys are being used is leaving our organization.
What steps can we take to ensure there is no interruption to our API calls?
-
A: Customer should generate new API tokens with a user that has full access to data
within Strategic Sourcing and replace the existing API keys. As a second step, we
recommend disabling the user that is leaving the organization in the
Strategic Sourcing User List.
-
Q: Does the attachments API allow us to pull/update attachments in File Type custom fields?
-
A: No, the attachments API only allows you to access documents via API that are
in the Attachments section of a record. Customers can also use the Contracts API
to access attachments in the Signed Documents section of a Contract.
-
Q: Can I use the API to update a field on a supplier’s profile with data?
-
A: Yes, if you create a Custom Field on the supplier profile in WSS to house this
information, you are able to use the Strategic Sourcing Supplier API to update custom fields.
-
Q: Can I use an API to push additional WSS onboarding data into Workday?
-
A: In some cases, this may be possible, but it is not an officially supported solution.
The Supplier Connector allows you to sync supplier data in both directions but
the connectors do not synchronize every supplier attribute between systems.
In general, it is preferable to use the Workday REST APIs if you wish to
update records inside a Workday tenant.
-
Q: Can I use a WSS API to trigger a WSS workflow?
(ex: Re-Run supplier forms that are about to expire)
-
A: APIs may be used to create certain records in Strategic Sourcing like events,
projects, contracts, suppliers, and more, which can then be further actioned upon
in Strategic Sourcing. APIs cannot be used to kick off a workflow in Strategic
Sourcing such as automatically publishing an event, supplier form, or approval workflow.