# Compatibility and deprecation

> What we promise about /v1, and the parts of that promise the code itself checks on every change.

Page: https://payerworks.com/docs/compatibility · Markdown: https://payerworks.com/docs/compatibility.md

> Payerworks writes and explains files; it sends nothing to a payer. Every file a route writes says `transmitted: false`, and is yours to send on your own connection. A test key is for invented data only, never a real patient.

Every route is under `/v1`. Within it, we change the API only in ways an integration written against it keeps working with, and when that cannot hold for a route, we say so in advance and give you at least 180 days.

## Changes that never break an integration

- A new route.
- A new optional field in a request, or a new value an optional field may take.
- A new field in an answer, or a new value in a list of values an answer may hold (a new event type, a new state, a new verdict).
- A new error code, for a refusal that had none.
- A sentence in an answer’s words, a message or a note, worded better. Read the codes and fields, never the sentences.

Build for these: ignore an answer field you do not know, treat an error code you do not know by its HTTP status, and treat an unknown value in a list as unknown rather than failing.

## What counts as breaking

- A route removed or its path changed.
- A field removed from an answer, renamed, or given another type or meaning.
- A request field that was optional made required, or a value it took refused.
- An error code answered with another HTTP status, or used for another meaning.
- A refusal for a request that was answered before, when the request was right.

A refusal of a request that was never right (a claim that breaks a published rule a check did not run before) is a correction, said in the changelog with what changed, never quietly. A refusal an account chooses for itself is its own setting, never a change to the API: since 10/20/2026 an organization’s owner may choose that only signed-in members make, rotate and revoke the account’s keys, and then those three key routes refuse the account’s keys with keys_managed_by_members, until an owner switches it back.

## How a deprecation is announced

- A route to be removed is first listed as deprecated: in [/openapi.json](https://payerworks.com/openapi.json) its operation says `deprecated: true` with the day it ends, and the changelog says why and what to use instead.
- From that day, every answer of the route carries the Deprecation header (RFC 9745), the Sunset header with the day it stops (RFC 8594), and a Link to this page.
- The route keeps answering for at least 180 days after its deprecation is announced.
- A change that cannot be made by adding ships under a new prefix, beside `/v1`, never in place.

## What the code checks

What the code checks on every change: every route `/v1` served on 10/20/2026 is still served unless it was deprecated and its day has passed, and every error code it answered on that day keeps its HTTP status. Nothing is deprecated today.

## Deprecated now

Nothing is deprecated.

Every change, breaking or not, is on the [Changelog](https://payerworks.com/docs/changelog).