Responses and Evidence

This page defines the response fields returned by the simple, standard, development and batch endpoints.

Single Response

json

{
  "api_version": "v3",
  "release_id": "<immutable-release-id>",
  "execution_id": "<server-generated-uuid>",
  "valuation_id": "<server-generated-uuid>",
  "request_reference": "valuation-001",
  "status": "valued",
  "property": {
    "uprn": "100012345678",
    "postcode": "OX1 1AA",
    "identity_source": "verified_identity_store"
  },
  "valuation": {
    "date": "2026-09-08",
    "estimated_value_gbp": 612000,
    "range": {
      "lower_value_gbp": 560000,
      "upper_value_gbp": 675000,
      "nominal_coverage": 0.8
    }
  },
  "confidence": {"score": 0.81, "band": "high"},
  "input_resolution": {
    "stored_data_used": [],
    "ignored_inputs": [],
    "derived_inputs": []
  }
}

Example values are illustrative.

Optional evidence sections may be omitted or null when not requested or unavailable, including in saved job results. Feature attribution is not part of the customer valuation response. Confidence, the available prediction range and input_resolution remain part of the core successful response.

Response Fields

Field	Meaning
`api_version`	Public response contract.
`release_id`	Valuation release used; persist it with the original response. It is not an API software-build identifier.
`execution_id`	Server-generated identifier for the valuation execution; saved job results retain theirs when retrieved again.
`valuation_id`	Server-generated identifier for this property valuation.
`request_reference`	Optional customer-defined reference; duplicate values do not affect server-generated identifiers.
`status`	`valued`, `referred`, `rejected`, or `valuation_failed`.
`property`	Resolved identifier, postcode and method of identity resolution.
`valuation`	Valuation date, estimated value and prediction range.
`confidence`	Evidence-strength score and band.
`lease`	For a valued leasehold property, the input mode and remaining years used. Detailed mode returns the calculated value.
`input_resolution`	Stored values applied, submitted values ignored and public values derived.
`comparables`	Optional comparable transactions returned as supporting evidence.
`context`	Optional spatial observations.

Estimated Value

estimated_value_gbp is the estimated market value, rounded to the nearest pound. It is not a guaranteed sale price, mortgage offer, survey, legal opinion or instruction to transact.

Range

The lower and upper bounds are calculated for the valuation and are not a fixed percentage around the estimate. nominal_coverage describes the intended portfolio-level coverage of the range; it is not an exact probability for an individual property. Do not hard-code 0.8; use the returned value. The range may be null when it is unavailable.

Confidence

Band	Score
`high`	`>= 0.70`
`medium`	`>= 0.40`, `< 0.70`
`low`	`>= 0.15`, `< 0.40`
`none`	`< 0.15`, or no usable evidence score.
`unavailable`	No confidence band was returned; the score may be null.

Confidence describes evidence strength. A score of 0.81 must not be displayed as “81% accurate”. Show confidence and range separately.

Input Resolution

json

{
  "stored_data_used": [
    {
      "field": "energy.current_efficiency_score",
      "value": 74,
      "source": "internal_property_data"
    }
  ],
  "ignored_inputs": [
    {
      "field": "land.plot_area_m2",
      "reason": "not_applicable_to_flat"
    }
  ],
  "derived_inputs": [
    {
      "field": "lease.years_remaining",
      "value": 93.306502,
      "reason": "calculated_from_detailed_lease_dates"
    }
  ]
}

This is a customer-facing record of input resolution, not a complete internal data record.

Comparables

Set include_comparables=true and comparables_limit=0..10.

Field	Meaning
`rank`	Position in the returned list.
`address`	Formatted transaction address.
`property_type`	Public comparable classification.
`sale_date`	Recorded transaction date.
`sale_price_gbp`	Recorded price.
`time_adjusted_price_gbp`	Price adjusted to valuation date.
`floor_area_m2`	Known floor area.
`price_per_m2_gbp`	Recorded price/floor area.
`distance_m`	Distance from subject.
`similarity_score`	Approximate similarity from zero to one.

The fields above are returned as null when their underlying value is unavailable. Comparable records provide supporting context and should not be treated as identical to the subject property. The number returned does not change the valuation.

A valued response can contain an empty comparable list when no suitable transactions are available for display. Read status to determine the outcome; an empty list is not an error code. Referred responses do not return comparables.

Each returned record represents a distinct sale. The same address can appear more than once if it sold on different dates. The requested limit is applied after duplicate sales are removed. similarity_score describes how closely a comparable resembles the subject; it is not the sale's percentage contribution to the valuation. Neither ranks nor similarity scores are valuation weights.

Context

The context object may include distances and counts for green space, rail, other public transport and major roads. These fields describe the property's surroundings; they are not standalone adjustments. An unavailable value is returned as null.

Batch Envelope

json

{
  "api_version": "v3",
  "release_id": "<immutable-release-id>",
  "execution_id": "<server-generated-uuid>",
  "status": "partial",
  "summary": {
    "requested": 3,
    "valued": 2,
    "referred": 0,
    "rejected": 1,
    "valuation_failed": 0
  },
  "results": []
}

Results preserve input order. complete means every row was valued; otherwise the batch is partial.

In a batch, release_id and execution_id belong to the envelope. Each row has its own valuation_id; do not require the envelope identifiers to be repeated inside every row. Validation, authentication and transport errors may use a different envelope, as described in Errors and Retries.

Response Boundaries

Only fields documented for the selected endpoint are part of the public response contract. Do not depend on undocumented fields.