What can change within v3, and how changes are announced.
The major version is part of the URL: https://api.join.com/v3.
Compatibility
Changes within v3 are additive. JOIN may add, without notice:
- New endpoints and resources.
- New optional request fields and parameters.
- New response fields.
- New enum values.
- New error codes.
- New response headers.
Build your integration to tolerate these: ignore unknown fields, and handle an unknown enum value or error code without failing.
Breaking changes, such as removing or renaming a field, are not made within v3.
Deprecation
A deprecated endpoint or field keeps working until its sunset date. Responses from it carry these headers (RFC 8594):
| Header | Description |
|---|---|
Deprecation | The date it was deprecated. |
Sunset | The date it stops working. |
Link | A link to the changelog entry, with rel="sunset". |
Monitor these headers in your integration to detect a deprecation without tracking the changelog by hand.
Dated revisions
Requests may select a dated revision of the v3 schema with the optional Join-Version header, in MM.YYYY format:
curl https://api.join.com/v3/offices \
-H "Authorization: Bearer $JOIN_API_TOKEN" \
-H "Join-Version: 08.2026"Without the header, the current default revision is used (08.2026). An unsupported value returns 400 unsupported_api_version.
Changelog
Every customer-visible change is recorded with its date in the Changelog.