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.

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.

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"
  }
}

You can manage your default API version in the DIDWW User Panel.

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 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 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 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.

HTTP Lifecycle Headers#

The HTTP standards define a Deprecation response header for signaling deprecation and a Sunset response header 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.