Versioning

The API and its webhook events carry their version in their names. Every call starts with /api/v1, and every event ends with its version, such as transfer.status_changed.v3.

Changes that keep the version

These changes can come at any time without a new version, so your integration should ignore what it does not know. A value it does not recognize, such as a new status, should not make it fail.

Change	Example
A new call	A new endpoint under `/api/v1`.
A new optional field in a request	A field you can send, and leave out.
A new field in an answer or an event	An extra property in a transfer or in a webhook payload.
A new value in a list of values	A new status, requirement type or error code.
A new event	A new webhook event that you subscribe to only if you want it.

Change	Example
A new call	A new endpoint under `/api/v1`.
A new optional field in a request	A field you can send, and leave out.
A new field in an answer or an event	An extra property in a transfer or in a webhook payload.
A new value in a list of values	A new status, requirement type or error code.
A new event	A new webhook event that you subscribe to only if you want it.

Changes that need a new version

A change that could break a working integration comes with a new version, which means a new path for the API or a new version of the event.

Change	Example
Removing or renaming	A call, a field or a value of a field.
A new required field	A field a request must now include.
A new type or meaning	A field that changes its format or what it means.
A new order of events	An event sent at a different point of the transfer.

Change	Example
Removing or renaming	A call, a field or a value of a field.
A new required field	A field a request must now include.
A new type or meaning	A field that changes its format or what it means.
A new order of events	An event sent at a different point of the transfer.

Both versions then run side by side, so you move when you are ready. The notice period is still to be published. (placeholder) How long an old version keeps working is still to be published. (placeholder)

How you hear about changes

The Changelog lists every change with its date and marks the breaking ones. Whether it is also announced by email to your technical contacts is still to be confirmed. (placeholder)