# API Versioning and Deprecation Policy

The DIDWW API v3 uses versioning to ensure backward compatibility while enabling new features and enhancements.
Versioning is based on the date of your first request using API v3.

- Each customer is assigned a fixed API version when they first use the API.
- The version will not change automatically. You are responsible for upgrading via the DIDWW User Panel when ready.
- New versions may introduce changes to existing behavior or add new parameters and resources.

The `/v3` URL path identifies the major API version. Dated versions, such as
`2026-04-16`, identify the API behavior selected by your account's default
version or the `X-DIDWW-API-Version` request header. A dated version is a
release identifier, not a deprecation or retirement date.

This page applies to DIDWW REST API v3. It does not define versioning or
retirement rules for the separate OTP Verification API.

You can view your current API version in the response metadata field: `meta.api_version`.

To review or change your current version, visit the [API page in the User Panel](https://my.didww.com/#/api).

## Version Support Policy

All released dated DIDWW API v3 versions remain available and maintained
after newer versions are introduced. Released versions are not removed or
retired, and their existing API behavior and contract remain unchanged.
New features and changes, including breaking changes, are introduced in
new dated versions rather than changing a previously released version.

An existing integration does not need to upgrade simply because a newer
version is released. Your account's default version does not change
automatically. You can continue using that version and test a newer
version with `X-DIDWW-API-Version` before deciding whether to upgrade
the default.

Version availability and account version selection are separate: the
version-selection restrictions below still apply when using the request
header or changing your account's default version.

---

## Upgrading Your API Version

You may test or adopt a newer API version by including the `X-DIDWW-API-Version` header in your requests. This header
overrides the default version for the current request only.

The following read-only example selects `2026-04-16`. Before using it,
check your current version; an older-than-default header is ignored.

[[DIDWW-API-EXAMPLE-START]]

http

```
GET /v3/voice_in_trunk_groups HTTP/1.1
Host: api.didww.com
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Api-Key: [API Token]
X-DIDWW-API-Version: 2026-04-16
```

curl

```
curl -i -X GET https://api.didww.com/v3/voice_in_trunk_groups -H "Accept: application/vnd.api+json" -H "Api-Key: [API Token]" -H "Content-Type: application/vnd.api+json" -H "X-Didww-Api-Version: 2026-04-16"
```

response

```
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "id": "12345678-abcd-4321-efgh-9876543210ab",
      "type": "voice_in_trunk_groups",
      "attributes": {
        "created_at": "2023-09-01T08:06:37.162Z",
        "name": "TG test",
        "capacity_limit": null
      },
      "relationships": {
        "voice_in_trunks": {}
      },
      "meta": {
        "trunks_count": 2
      }
    }
  ],
  "meta": {
    "total_records": 1,
    "api_version": "2026-04-16"
  }
}
```

[[DIDWW-API-EXAMPLE-END]]

You can manage your default API version in the [DIDWW User Panel](https://my.didww.com/#/api).

Important

- If the `X-DIDWW-API-Version` header specifies a version **older** than your currently assigned version, it will be **ignored**.
- Downgrading your API version is not supported.
- The `meta.api_version` field in the response reflects the version used for that request.

## Upgrade Checklist

1. Record the default version shown in the User Panel and the
   `meta.api_version` returned by your existing integration.
2. Review the documentation and changelogs for the target version and any
   intervening versions. Check changed endpoint paths, resource types,
   relationships, attributes, filters, and error handling.
3. Test the target version in the [DIDWW API Sandbox](sandbox.html) using a
   separate Sandbox account and API key. Set the version header explicitly
   and confirm `meta.api_version` in responses. Do not assume the Sandbox
   account has the same default version as production.
4. Update and test request payloads, response parsing, and application
   workflows before changing the production default. A successful read-only
   request does not validate every write operation or callback.
5. Change the default version in the User Panel only after completing these
   checks. Verify the effective version and integration behavior afterward.

Warning

Changing the default version is not reversible through a downgrade.
After upgrading, sending an older version header does not restore the
previous API behavior. Plan and test the migration before upgrading.

---

## Deprecation and Sunset

**Deprecation** identifies an API version, endpoint, or field that clients
should migrate away from. Deprecation alone does not establish when that
functionality will stop working. **Sunset** identifies a scheduled end of
availability. These are separate lifecycle events.

For version-specific changes, use the documentation and changelogs below.
For example, [version 2021-04-19](2021-04-19/changelog.html#changelog-2021-04-19) removed the DID
`pending_removal` attribute and replaced it with `billing_cycles_count`.
Integrations upgrading to that version or later must use the replacement.
This change does not, by itself, announce the retirement of an entire older
API version.

The [OpenAPI Reference for version 2026-04-16](2026-04-16/api-reference.html) also identifies deprecated fields with
`deprecated: true`. In `did_order_items` attributes, `setup_price` and
`monthly_price` are deprecated aliases of `nrc` and `mrc` respectively,
retained for backward compatibility in that version. Prefer `nrc` and
`mrc` when implementing against version `2026-04-16`. A deprecated
schema property does not provide a removal date.

### Retirement Timelines

DIDWW does not sunset released dated API v3 versions. There is no
version-retirement deadline or retirement notice period under this policy:
earlier versions remain available when a newer version is introduced.

Deprecating or replacing a field in a newer version does not change or
remove that field from an earlier released version where it was supported.
Use the documentation and changelog for the version your request actually
uses. Publishing a newer version or omitting older versions from the
machine-readable documentation indexes is not a retirement notice.

For questions about a version-specific replacement or migration, contact
[DIDWW Customer Support](mailto:support%40didww.com).

### HTTP Lifecycle Headers

The HTTP standards define a [Deprecation response header](https://www.rfc-editor.org/rfc/rfc9745.html) for signaling
deprecation and
a [Sunset response header](https://www.rfc-editor.org/rfc/rfc8594.html) for
signaling an expected end of availability. These are response headers, not
version-selection request headers.

The version-support policy is documented on this page, this explanation
does not claim that DIDWW API responses emit these headers. Do not infer
a retirement date from a version identifier, a deprecated schema property,
or the absence of a lifecycle header.

---

## Related Changelogs

Review the changelog entries to understand the impact of a version upgrade:

**Version 2021-04-19**

View changes introduced in API version 2021-04-19.

[Changelog](2021-04-19/changelog.html#changelog-2021-04-19)

**Version 2021-12-15**

View changes introduced in API version 2021-12-15.

[Changelog](2021-12-15/changelog.html#changelog-2021-12-15)

**Version 2022-05-10**

View changes introduced in API version 2022-05-10.

[Changelog](2022-05-10/changelog.html#changelog-2022-05-10)

**Version 2026-04-16**

View changes introduced in API version 2026-04-16.

[Changelog](2026-04-16/changelog.html#changelog-2026-04-16)

On this page