Beta — the platform and this API are in beta. The rules on this page are binding; we may add features and tighten validation without notice.

Versioning

The API follows semantic versioning:

  • The major is in the URL. /v1/ is major version 1. A change that could break a working integration never ships inside v1; it ships as /v2/.
  • The full version is MAJOR.MINOR.PATCH, for example 1.6.0: info.version in /openapi.yaml, the heading of each changelog entry and the X-API-Version header of every answer. Log it with your requests.
  • The numbers continue after 1.3.0, the last version of the retired partner endpoint POST /api/partner/v1/leads: this API started at 1.4.0. That endpoint's history is at the end of the changelog.

What changes the version

Change Version
Clearer docs; a fix that makes the API do what the docs already said PATCH (1.6.0 → 1.6.1)
Something added: an optional request field, a response field, an endpoint, a scope, an error code for a new situation MINOR (1.6.0 → 1.7.0)
Stricter validation within v1 (below) MINOR with a Tightened entry
Anything that can break a working integration new major (/v2/)

Breaking: removing or renaming a field, a new required request field, accepting fewer values for a field, removing an error code or status, a different code for an existing situation, a changed type, authentication or base URL.

Read answers tolerantly: ignore fields, headers and enum values you do not know, and treat an unknown error.code by its HTTP status. That is what lets us add things within v1.

Beta

The platform and the API are in beta. The rules on these pages are binding, and the contract check below still blocks breaking changes inside /v1/. What beta means: features arrive often, and validation can be tightened without notice.

Stricter validation within v1

Sometimes the API accepts input it cannot handle well. Rejecting it is stricter, but it protects your data rather than changing what a correct integration sends. Such a change ships as a MINOR release and is effective at release. Its changelog entry under Tightened says exactly what is now rejected and with which error; there is no separate email.

The same applies, rarely, to data protection on the answer side: a response field may become null in situations where we may no longer show it (for example creator_name on offers before payment, 1.11.0). The field stays in every answer; the spec marks it with x-nullable-since and the Tightened entry says when it is null.

API Terms of Use

The legal rules for using the API are the API Terms of Use, a versioned agreement of its own (api_terms), separate from this contract versioning. A new version is announced with the event agreement.published and in the changelog. A material change that is worse for you takes effect 30 days after we publish it; a change required by law, or needed for security or to stop abuse, takes effect on publication. Accepting the terms is described under Authentication → API Terms.

Retiring a major

When /v2/ goes live, /v1/ stops on the same day: every request answers 410 version_sunset, with Deprecation, Sunset and Link headers pointing to the migration guide. There is no notice period, so watch the changelog.

How we keep to this

The published contract is checked automatically before every release against the last recorded version: an addition needs a MINOR version, stricter validation needs a Tightened entry, and a breaking change cannot be released under /v1/ at all.