Skip to main content
The Contractors Cloud API is designed so that an integration you build today keeps working without changes. This page is the compatibility contract behind that: what we promise never to change, what we may add at any time, and how we retire functionality in the rare case we must.

​
Where the version lives

The version is a fixed segment of the base URL — there is no version header or query parameter to send:
v1 is the current version of the API, and every path in this reference is relative to that base URL. New capabilities ship into v1 continuously; the version itself only changes if we ever have to break the promises below.

​
What never changes in v1

We treat the documented API surface as frozen against breaking changes. Within v1 we will not:
  • Remove or rename a documented endpoint, response field, or request parameter.
  • Change a documented field’s type, format, or the meaning of its values.
  • Change the success status code or response envelope of a documented endpoint.
  • Make an optional request parameter required, or reject requests that were previously valid.
  • Remove a webhook event type or remove fields from its payload.

​
What may be added at any time

The API evolves additively, without prior notice. Expect us to:
  • Add new endpoints, and new optional parameters to existing endpoints.
  • Add new fields to existing response objects and webhook payloads.
  • Add new values to enumerated fields — for example, a new status or type value.
  • Add new webhook event types.

​
Write a tolerant client

Additive evolution is only safe if your integration tolerates additions. Follow these rules and new capabilities will never break you:
  • Ignore fields you don’t recognize in responses and webhook payloads instead of treating them as errors.
  • Handle unrecognized enumerated values with a sensible fallback instead of matching exhaustively.
  • Rely on field names, never on the order of keys in a JSON object.

​
Deprecations

In the rare case we retire a capability, removal never comes first:
  1. The capability is marked as deprecated in this reference, with a recommended replacement.
  2. Responses that use it include Deprecation and Sunset headers, so you can detect affected calls in your own logs.
  3. Where we can identify the integrations using it, we contact the account owners directly.
A deprecated capability keeps working for at least one month after it is announced — in practice usually much longer, especially for heavily used functionality.
Nothing in the API is currently deprecated.

​
Bug fixes

This documentation defines the API’s intended behavior. When the API behaves differently from what is documented, we treat that as a bug and may fix it, even where the fix changes responses. If integrations plausibly depend on the incorrect behavior, we handle the fix like a deprecation and give notice first.

​
If a v2 ever ships

A change that cannot be made compatibly within v1 would ship under a new base URL segment (/api/v2) — most likely for a small set of endpoints rather than the whole API. v1 would keep working and follow the deprecation process above, with a migration window measured in months, not weeks.
Webhook payloads follow the same compatibility rules as API responses — see Webhooks for how event notifications work.