Send x-api-version on every request. Versions are dates in YYYY-MM-DD form, and the version you send determines the request and response shapes you get back.
curl --request GET \
--url 'https://api.7shifts.com/v2/company/{COMPANY_ID}/users' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-version: 2026-01-01'The header is optional. Sending it is strongly recommended, because a request without it uses whatever default is attached to your credential, and that default is not necessarily the version whose documentation you are reading.
Available versions
| Version | Status |
|---|---|
2026-01-01 | Current |
2025-03-01 | Supported |
2023-04-01 | Supported |
Build against 2026-01-01. Use the version selector at the top of this portal to read the reference documentation for any supported version, and make sure the selector matches the version your code sends.
How a version gets chosen
graph TD
A[Request arrives] --> B{x-api-version<br/>header present?}
B -->|Yes| C[Use that version]
B -->|No| D[Use the default attached to your<br/>access token or OAuth client]
D --> E{Still supported?}
E -->|Yes| F[Use it]
E -->|No| G[Fall back to the oldest<br/>supported version]
Two things follow from this.
An integration that never sends the header can change behavior without a code change. Your credential's default can be updated, or the version it points at can age out of support, and neither event involves you deploying anything.
More commonly, you read the documentation for one version and your requests run against another. The reference in this portal is version-specific. If your code omits the header and your credential's default differs from the version you had selected while reading, the field names, required parameters, and response shapes you built against may not be the ones you get.
Pinning an explicit version removes both problems.
Your credential's default version
Every access token and OAuth client is assigned a default version when it is created.
That default may be a date that does not appear in the version selector above, and it may be later than the current published version. This is expected and does not indicate a problem with your credential. Published versions are the ones with documentation, and they are the ones to build against.
The practical consequence is the same either way: do not treat your credential's default as a description of the API you are coding against. Send x-api-version with a published version, and your requests match the documentation you read.
To change a default, use the 7shifts administrator portal for an access token, or contact your partner account manager for an OAuth client. Changing the default is a convenience for requests that omit the header. It is not a substitute for pinning.
When new versions appear
A new published version is released only when a breaking change requires one. There is no fixed schedule and new versions are infrequent.
Most improvements to the API are additive and land in the version you are already on, so there is usually nothing to migrate to.
| Breaking — new version | Non-breaking — no new version |
|---|---|
| An optional parameter becomes required | A new optional parameter |
| A new required parameter | A required parameter becomes optional |
| Request body structure changes | New properties on a response |
| Response body structure changes | New endpoints |
| An endpoint is removed | |
| Deprecated functionality is removed | |
| Validation rules change | |
| Error codes change |
Because new properties can appear on a response at any time within your version, parse responses tolerantly. Read the fields you need and ignore the ones you do not. An integration that rejects unfamiliar fields will break on a change that is not breaking for anyone else.
All changes are documented in the changelog.
Support window and retirement
Published versions are supported for a minimum of 12 months from release. Supported versions receive security fixes; new functionality goes into newer versions.
Versions are retired. The v1 API has been removed, and older v2 versions will be retired in future. Retirement is announced in the changelog and notified to the contact on your credential.
Keep the contact email on your access token current. Retirement, breaking-change, and security notices go to that address, and a stale one means you find out from a failing integration instead.
Upgrading
- Read the changelog entries between your current version and the target.
- Send the new version in
x-api-versionin a test environment and confirm your requests and parsers still work. - Roll the header change to production.
- Update the default on your credential so any request that omits the header matches.
If nothing you use changed between versions, upgrading is only the header change in step 2.
Deprecation
Parts of the API can be deprecated when they become outdated, unsafe, or unused. Deprecation is announced with a new version and is never retroactive: the version you are pinned to does not change under you.
Deprecated functionality is supported for a minimum of 12 months after the announcement, then removed in a later version. Because removal only takes effect in a newer version, upgrading is when you encounter it. Read the changelog entries between your current version and your target before you move.
Deprecated endpoints are labeled in this portal and announced in the changelog.
Security fixes
Security issues are fixed across all supported versions. If a fix requires a breaking change, 7shifts notifies registered partners and posts the issue and its impact in the changelog.
Webhooks are not versioned
Webhook payloads do not use x-api-version and are not covered by the guarantees on this page. Write webhook consumers defensively: read the fields you need, ignore the ones you do not, and do not assume payload shapes are frozen.
Questions
Email [email protected], or ask in Discussions. Partners can also reach their account manager.