Skip to main content

API Versioning

We want you to be confident that your Fleetio API integration will continue to work even as we make changes to our API. In order to do this, we maintain multiple versions of our API endpoints. This allows us to make breaking changes without breaking your integration. Allowing you to upgrade to the latest version of our API at your own pace, and separately for each endpoint you use.

Date Based Versions​

Fleetio has introduced a new way to version its public API, based on release dates. You do not need to make any changes to your integration to begin using date versioning, as we have automatically locked your existing API key(s) to the current date version. When any breaking change is introduced, the change will be contained in a subsequent version. Since newly created API keys will default to the latest current API version at the time they are created, you should take care to choose the same version as your existing API key when rotating API keys. To assist with upgrading, you can override your API key's locked version by sending along the X-Api-Version header with a valid version string with any API request. It is recommended that you ensure full compatibility by testing your integration in this way before configuring a new default version for your API key(s).

Endpoint Versions​

Endpoint versions have been deprecated as of 2023-03-01. Different endpoints will continue to exist at the respective v1, v2, and v3 paths, but breaking changes will be released as date-versions using the latest endpoint-versioned path.

tip

If a change would break existing integrations, we will introduce a new version.

Breaking Changes and Backwards Compatibility​

The following table includes examples of the types of changes we might make to an endpoint and whether we consider those changes to be backwards-compatible.

Breaking ChangesBackwards-Compatible Changes
New Version Required
  • Yes

    We will introduce a new API version when we make changes like this.

  • No

    We will not introduce a new version for changes like this.

Examples
  • Removing properties from an endpoint's response payload.
  • Adding a new required parameter to an endpoint's request payload.
  • Changing the type or meaning of a property in an endpoint's response payload.

  • Adding new properties to an endpoint's response payload.
  • Adding new optional parameters to an endpoint's request payload.
  • Changing the order of properties in an endpoint's response payload.
  • Changing the length or format of opaque strings or numbers. This could include things like IDs, error messages, labels, and other human-readable strings.
  • Adding new types of webhook events. Your webhook integration should expect to
    • see unfamilar event types.