Versioning Schema

Kompliant Web API uses date-based versioning in the format YYYY-MM-DD. For example, the current API version 2025-03-24 was released on March 24, 2025.

The entire API is versioned as a unit (not individual endpoints). A newer date indicates a newer API version with potential changes or improvements.

To specify an API version, use the X-API-Version header. For example:

X-API-Version: 2025-03-24

Requests without this header default to the latest version. Using a specific version in production is highly recommended for consistency.

Checking Your API Version

You can verify the API version information with the meta.checkVersion endpoint. While this endpoint works without version specification, it's good practice to include the header:

Example Request

curl -X POST \
-H 'X-API-Version: 2025-03-24' \
'https://api.kompliant.com/meta.checkVersion'

Example Response

A successful response will look similar to the following:

{
  "meta": {
    "status": "SUCCESS",
    "trace_id": "trc_8UyVpL6xNm3QrGzY9sKf2T",
    "version": "2025-03-24"
  },
  "data": {
    "current_version": "2025-03-24",
    "latest_version": "2025-03-24"
  }
}

Version Changes

Our API evolves through both breaking and additive changes. Breaking changes always trigger a new API version, while additive changes may be incorporated without version increments. This means that even when using a specific version, your integration should be prepared to handle new fields or capabilities that might appear within that version.

Breaking Changes

Breaking changes are released as a new API version and can potentially disrupt existing integrations. These include:

• removing or renaming a method
• removing or renaming a parameter
• adding a new required parameter
• making a previously optional parameter required
• changing the type for a parameter
• adding a validation rule to an existing parameter
• removing or renaming a response field
• changing the type of a response field
• adding or renaming a required request header
• removing an enum value
• changing the authentication requirements

Additive Changes

Additive changes should not break existing integrations and include:

• adding a method
• adding an optional parameter
• adding an optional request header
• adding a response field
• adding a response header
• adding an enum value

⚠️

Ensure your systems can handle new, optional fields even when using the same API version.

Upgrading to a new API version

When a new version is released, we specify how long previous versions will continue to be supported. To upgrade:

1. Review the changelog for the new API version (found in the corresponding API Versions sub-page)
2. Identify any breaking changes that might affect your integration
3. Update your code to accommodate these changes
4. Update your requests to use the new version in the X-API-Version header
5. Test thoroughly to verify compatibility

This planned approach ensures your integrations remain stable while allowing us to improve the API over time.