Versioning and Releases

Valtaic versions the public API contract separately from the active valuation release.

Two Identifiers

The URL /v3/value can remain stable when a new valuation release is published. Use release discovery rather than assuming that publication occurs on a fixed day or that a new release is available every calendar month.

What the Release ID Represents

The release_id identifies the approved valuation release used to produce a result. Store it with each valuation so that the result can be associated with the correct valuation release.

It is not an identifier for every API software deployment. Request handling, response formatting or service configuration can change without a new valuation release. Retain the original request, response, timestamp and server-generated identifiers; a release ID alone is not a complete reproducibility record.

Discover the Active Release

curl --silent --show-error \
  -H "Authorization: Bearer $VALTAIC_API_KEY" \
  "https://api.valtaic.io/v3/releases/current" | jq

The response tells clients:

• release_id;
• model_effective_date;
• supported countries and broad property types;
• current valuation-date window;
• synchronous and asynchronous row limits;
• available V3 endpoints.

Valuation Date Window

The public contract accepts valuation dates within 12 calendar months before or after the current Europe/London business date, inclusive. The boundary moves daily and respects calendar month length.

Do not hard-code a date range in a long-lived client. Query the release metadata and use it for local validation, while treating the API as authoritative.

The valuation date specifies the date being assessed. It does not select an older release or recreate the information that was available on that date. Requests use the active release and its available information. A past-dated request is therefore not, by itself, an out-of-time accuracy test. A future date within the permitted window is not a guaranteed sale-price forecast.

Behaviour Across Releases

A valid request may produce a different value under a later release as market information, property records and service coverage are updated. This is a valuation-release change; it does not by itself imply a schema change.

Persisting Results

For every valuation store:

request payload
request_reference (when supplied)
execution_id
valuation_id
release_id
valuation date
response payload
request timestamp
X-Valtaic-Request-Id

Never replace an old release ID when refreshing a value. Store the refresh as a new valuation observation.

Job Release Pinning

An asynchronous job is pinned to the release active when it is accepted. A deployment during processing must not move that job to a new model. The job status and result repeat the pinned release ID.

Release Acceptance in Your Integration

For production integrations, maintain a representative set of test requests. After a release changes:

1. confirm response schema remains V3;
2. confirm required endpoints and limits;
3. test representative property forms and tenures;
4. confirm row-status and manual-referral handling;
5. assess valuation changes against appropriate business tolerances rather than requiring exact equality with the previous release;
6. investigate material or unexpected changes before treating normal release movement as a failure.

Client Compatibility

Within V3, additive optional response fields may be introduced. Clients should ignore unknown response fields but must not send unknown request fields.

Use the current request schema and maintain contract tests for your integration. Release metadata describes capabilities and limits, not the full request schema or a software changelog. An unchanged release_id does not establish that every API behaviour is unchanged. Agree any required change-notice or migration commitments as part of your service terms.