Using the API

API versioning

The current version of the Truework API is 2023-10-30.

The API version you specify controls the API and webhook behavior, request schemas, and response schemas. When a breaking change is introduced to the Truework API, a new dated version is released. To avoid breaking your code, we don’t change your version until you’re ready to upgrade.

All Truework API keys are provisioned with a “pinned” API version, which is set to the latest version available at the time the API key was created. This becomes your default API version. To override, provide an HTTP Accept header with a another valid API version.

$curl 'https://api.truework.com/orders/ \
>  -X GET \
>  -H 'Accept: application/json; version=2023-10-30'

The version passed via the Accept header must be greater than or equal to your API key version. Downgrading is not permitted, and will result in an HTTP 406 response.

Adjusting pinned API key version

To view or upgrade the pinned versions of your API key, head to your developer settings page and look for Production and Sandbox API keys.

Once an API key’s pinned version has been upgraded, it cannot be downgraded. If a downgrade is essential, please contact implementations@truework.com.

Backwards-compatible changes

Truework will not make a backwards incompatible change on an existing version, but will often make backwards compatible changes. All clients should be ready to handle backwards compatible changes. Truework considers the following changes to be backwards-compatible:

  • Adding new API resources.
  • Adding new optional request parameters to existing API methods.
  • Adding new properties to existing API responses.
  • Changing the order of properties in existing API responses.
  • Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings.
  • This includes adding or removing fixed prefixes.
  • You can safely assume object IDs we generate will never exceed 255 characters, but you should be able to handle IDs of up to that length. If for example you’re using MySQL, you should store IDs in a VARCHAR(255) COLLATE utf8_bin column (the COLLATE configuration ensures case-sensitivity in lookups).
  • Adding new event types. Your webhook listener should gracefully handle unfamiliar event types.