Versioning

The version is in the path

Every route is under /api/integrations/v1. A change that could break a working integration is never made to v1: it goes into a new version (/v2), which runs beside v1 for the notice period below.

What can change within v1

These changes are made without notice, so build your integration to accept them:

• New endpoints.
• New optional request fields and query parameters.
• New fields in responses, in error bodies and in webhook data.
• New values in fields that list states or types (for example a new status, milestoneType or document category), and new error codes.
• New webhook event types (a subscription only receives the types it names).
• Clearer descriptions in the OpenAPI document.

In practice: ignore fields you do not know, treat an unknown value as “other”, and handle an unknown error code by its HTTP status.

What is breaking

• Removing or renaming an endpoint, a field, an event type or a value.
• Changing a field’s type or meaning, or making an optional request field required.
• Changing authentication, the signature scheme or the error format.

Notice

A breaking change, and the end of a version, is announced at least 6 months ahead:

• by e-mail to the Owner and Admins of every company with an active integration;
• in the changelog;
• on the affected routes, with a Deprecation header (RFC 9745) from the announcement and a Sunset header (RFC 8594) giving the date the route stops.

Security fixes are the one exception: when a change is needed to protect customers’ data, it can be made sooner, and it is announced as early as possible.