Data API Versioning

When a new major version is released (e.g., v4 in the future), it will have a new base path. Your existing integrations will not automatically switch to it – you would have to point to the new URL. Major versions may deprecate or change behavior of endpoints.

IDC typically provides a transition period for older API versions. According to internal policy, once a new version is live, the previous version will be supported concurrently for 6 months. During this window, clients are expected to migrate to the new version. After the overlap period, the old version may be shut off (requests to it will fail). For example, when v3 was introduced, v2 continued working for several months but was eventually discontinued. Always refer to IDC’s announcements or the Changelog for exact dates.

Minor updates or additions within the same version (v3.x) aim to be backward-compatible. IDC might add new optional request parameters or new fields in response JSON. Your code should ideally ignore fields it doesn’t expect in JSON to be forward-compatible. Breaking changes will only come with a version bump.

If IDC offers a test environment or sandbox for new API versions, use it to verify your integration before switching production over. For example, IDC sometimes provides a QA base URL (the SAML documentation mentioned a test environment, and similarly there may be one for API, though not always public). Check with IDC if you’re unsure.

IDC will notify registered technical contacts about upcoming deprecations (usually via email). Ensure your team’s contact info is up to date with IDC (see Support section) so you receive these notices. If you need assistance migrating to a new API version, IDC support can help clarify changes.

To stay informed about new releases and plan your migration within the provided timeline to avoid disruptions make sure you are signed up for notifications (Staying up to Date with Recent Changes).