API Versioning & Deprecation

We know your product depends on ours. This page explains how we evolve the Avaya Infinity APIs, what we consider a breaking change, how much notice you'll get before something goes away, and what we need from you to keep your integration healthy.

Summary — Breaking changes only land in a new API version. Our goal is to run both versions side by side for at least 180 days from the day we announce the deprecation, so you can migrate on your own schedule. After that we retire the old version on a single published sunset date — the same date for everyone. We'll always point you to a replacement. Beta and Preview APIs can change anytime; for security or legal reasons we may move faster.

---

API lifecycle stages

Every API surface is in one of these stages. Only GA carries our deprecation-notice target.

How we version

• Breaking changes go into a new API version only — identified in the path (e.g. /v2/). The version you integrated against keeps behaving the same way.
• We aim to run both versions side by side for at least 180 days (dual-path), so you upgrade on your schedule, not ours.
• The clock runs from the deprecation announcement. We publish one sunset date that applies to all customers, and aim to set it at least 180 days out.
• SDKs follow semantic versioning (MAJOR.MINOR.PATCH). A major bump (e.g. 3.x → 4.x) means breaking changes to the library; minor and patch are safe to take.

What we consider a breaking change

We only bump the version — and only start the deprecation clock — for breaking changes.

Non-breaking (ships anytime, no version bump, no notice):

• ✅ A new endpoint, resource, or method
• ✅ A new optional request parameter or header
• ✅ A new field added to a response
• ✅ A new value in an existing enum, or a new event/webhook type
• ✅ Relaxing a validation rule
• ✅ A change to the format of a value we document as opaque (IDs, tokens, error strings)

Breaking (new version + deprecation of the old one):

• ⚠️ Removing or renaming an endpoint, field, parameter, or enum value
• ⚠️ Changing a field's data type, units, or meaning
• ⚠️ Adding a required parameter, or making an optional one required
• ⚠️ Stricter validation on input we used to accept
• ⚠️ Changing a default behavior, a response status code, or how auth works
• ⚠️ Dropping support for a protocol version

Write a tolerant integration

A few habits keep your integration from breaking on changes that shouldn't break it. We classify the changes above as non-breaking assuming your client does this:

1. Ignore fields you don't recognize in responses — don't fail on them.
2. Tolerate new enum values and event types you haven't seen before.
3. Don't depend on field order, undocumented behavior, or the internal format of opaque values.
4. Use documented, GA endpoints for production traffic.

How much notice you'll get

For GA APIs, when we ship a replacement we aim to keep the old version running alongside it for at least 180 days before retiring it — measured from the deprecation announcement. (These are targets we work hard to hit, not contractual guarantees — see when we may move faster.) Every deprecation notice tells you:

• what's being deprecated,
• the retirement date (sometimes written as "not sooner than [date]" and confirmed as it gets closer),
• the recommended replacement, and
• a migration guide.

Preview and Beta APIs don't carry this target — they can change or be withdrawn at any time.

When the old version gets turned off

When we deprecate a version, we publish a single retirement (sunset) date — the same date for every customer — which we aim to set at least 180 days after the announcement. On that date the old version is retired and calls to it return an error (e.g. 410 Gone).

We monitor traffic to deprecated versions, and where it makes sense we may reach out before the date — but the published sunset date is the date to plan around, and we aren't obligated to keep a version running past it.

On the way there, the old version passes through End of Support — it still runs, but we stop shipping fixes and updates for it, so that's your cue to finish migrating.

When we may move faster {#when-we-may-move-faster}

Sometimes we can't wait 180 days. We reserve the right to deprecate or retire an API immediately, or on shortened notice — giving you as much warning as we practically can — when it's necessary to:

• fix or contain a security vulnerability or incident,
• comply with a law, regulation, or court/regulatory order,
• react to a change from an upstream or third-party dependency outside our control,
• stop fraud, abuse, or unlawful use, or
• protect platform stability and other customers.

APIs with little or no measured usage may also be retired on shorter notice.

How we'll tell you

Watch these channels — and make sure the right people on your team do too:

• 📋 The API changelog and deprecation list on this portal
• ✉️ Email to your account's technical/admin contacts
• 🔔 In-product / dashboard notifications
• 🏷️ Machine-readable Deprecation and Sunset HTTP response headers on affected endpoints (RFC 9745 and RFC 8594) — so you can detect deprecations right from your own monitoring

Your side of the deal

To stay ahead of changes:

• Keep integrations on a supported API version.
• Build a tolerant client (see above).
• Subscribe to the changelog and keep your contact info current.
• Migrate before the retirement date — that's the one deadline we can't move for you.

---

Questions about a specific deprecation or migration? Contact [developer support / link].