Versioning

The API is versioned by date. Pin a version and your responses do not change shape until you choose to move.

Pinning a version

OH-Version: 2026-05-16

• The header is optional. Without it you get the oldest version that is not deprecated.
• 2026-05-16 is the only version today. Pin it anyway, so a future version never changes your integration without a deploy on your side.
• A malformed value, or a date that is not a version, is a 400 (errors.integrations.unsupported_version). The API key is checked first, so an unauthenticated request gets 401 whatever the header says.

What changes without a new version

Additive changes are not breaking and can ship at any time:

• new endpoints, new optional request fields, new query parameters;
• new fields in responses and webhook payloads;
• new event types (you only receive the types you subscribe to);
• new values for problem detail_keys on new failure cases.

Write your client to ignore fields it does not know.

Removing or renaming a field, changing a type or meaning, or making something required needs a new dated version.

Deprecation and sunset

When a version is deprecated, responses to requests pinned to it carry:

Deprecation: true
Sunset: Wed, 16 Jun 2027 00:00:00 GMT
Link: <https://developers.officehero.io/docs/versioning>; rel="deprecation"

Sunset is an HTTP date. After it, requests pinned to that version get 410 Gone (errors.integrations.version_sunset). A deprecated version stays available for at least six months, and deprecations are announced in the changelog.

Webhooks

Each webhook endpoint has a pinned_version (set when you create it, defaulting to the oldest supported version) and every delivery carries it as the OH-Version header. While 2026-05-16 is the only version the payload shape is the same for every endpoint; when a second version ships, the changelog will say how webhook bodies follow pinned_version.