Skip to content
SMBcrmSMBcrm Developers

Versioning & Stability

The SMBcrm REST API is designed to stay stable. Pin one header, parse responses tolerantly, and an integration you write today needs few changes as the product grows.

Pin the Version header

Section titled “Pin the Version header”

Every request carries a Version header:

Version: v3

v3 is the current API version, and it’s what this documentation targets. Send Version: v3 on every request. Later named versions (v4 and beyond) use the same header, but only v3 is documented here.

The API also recognizes older date-based versions (for example 2021-07-28) so existing integrations keep working, but new endpoints and enhancements are added to v3 only. Build new work against v3. See Base URL & Headers for the full header list and a complete request example.

When the header is wrong

Section titled “When the header is wrong”

The API checks the Version header before it checks your token, so a bad value fails right away. The value is case-sensitive: send v3 in lowercase.

What you sent Response
No Version header, or an empty one 401 with version header was not found.
A malformed value, such as V3 or 3 401 with version header is invalid
A value that isn’t a supported version, such as v9 or legacy 400 with an error message, for example Unsupported API version: v9. Supported versions: ...

The 401 bodies carry statusCode and message. The 400 body carries a single error string.

Version lifecycle

Section titled “Version lifecycle”

Date-based versions came first. From v3 on, versions have a name (v3, v4, and so on). Both kinds go in the same Version header.

When a new version ships, the previous one enters a maintenance window: it still receives critical bug fixes and security patches, but no new features. Once a version is retired, requests that send it are rejected, so move to the current version before its retirement date. No retirement date is published for any version today.

Version Released Retirement
v3 June 11, 2026 Not announced
2023-02-21 February 21, 2023 Not announced
2021-07-28 July 28, 2021 Not announced
2021-04-15 April 15, 2021 Not announced

What changes, and what doesn’t

Section titled “What changes, and what doesn’t”

Most changes are additive: new endpoints, new optional fields, and new enum values. Occasionally a release tightens a contract, for example by removing an unused query parameter, restricting a field to a fixed list of values, or making an optional field required.

  • New fields and values get added. Response objects may gain fields, and enums may gain values, that aren’t shown here yet. Read the fields you need by name and ignore the rest, rather than validating against a closed schema.
  • Reference pages are the current contract for v3. The paths, methods, and payloads on each reference page describe the API as it stands today. Re-check the pages you depend on when you upgrade or revisit an integration.
  • Some renames ship with a transition period. The Knowledge Base endpoints, for example, moved from /knowledge-base to /knowledge-bases. Both prefixes work, and new code should use /knowledge-bases.
  • Individual endpoints can be deprecated before a version is retired. A deprecated endpoint keeps working in v3, but move to its replacement when one is listed. Reference pages mark deprecated endpoints and fields and name the replacement.
  • Test against the documented shapes, not against undocumented behavior you happen to observe.
Section titled “Related”