Request Schema

This page describes Standard and Simple valuation requests. Request objects are strict: unknown or misspelled fields are rejected. Development requests use a dedicated schema: fabric, energy.construction_age_band, property.build_status, property.uprn and options.use_stored_data are not accepted. The API applies the fixed new-build specification internally.

Complete Request

{
  "request_reference": "customer-reference",
  "options": {
    "include_comparables": true,
    "include_context_metrics": true,
    "comparables_limit": 5,
    "use_stored_data": false
  },
  "property": {
    "valuation_date": "2026-09-08",
    "uprn": "100012345678",
    "postcode": "OX1 1AA",
    "type": "D",
    "subtype": "house_detached",
    "title_tenure": "leasehold",
    "build_status": "existing",
    "building_number_or_name": "14",
    "street": "Station Road"
  },
  "occupancy": {"status": "owner_occupied"},
  "size": {
    "floor_area_m2": 180,
    "bedrooms": 4,
    "living_rooms": 3,
    "storeys": 2
  },
  "land": {"plot_area_m2": 450},
  "energy": {
    "current_efficiency_score": 78,
    "potential_efficiency_score": 86,
    "consumption_kwh_m2_year": 115.5,
    "construction_age_band": "1983_1990",
    "extension_count": 2,
    "solar_pv_supply_percent": 20
  },
  "fabric": {
    "preset": "good",
    "roof_insulation": {
      "basis": "estimated",
      "estimated_level": "medium"
    },
    "wall_insulation": "insulated",
    "floor_insulation": "insulated",
    "glazing": "mostly_or_fully_double_glazed",
    "lighting": "efficient"
  },
  "lease": {
    "mode": "detailed",
    "start_date": "2020-01-01",
    "end_date": "2120-01-01"
  }
}

property, occupancy and size are required. Other sections are optional unless one of the conditional rules below applies.

Top-Level Fields

Omitted and Null Values

Submitted values are schema-validated before business rules ignore fields that do not apply. For example, a freehold lease object must still have a valid shape, and a flat's supplied plot area must still be a valid positive number. Omit inapplicable fields rather than sending malformed placeholders.

For a nullable property field, omission and explicit null both mean that the customer has not supplied a value. Neither means zero, false or “unknown”. When stored data is enabled, the API may populate one of twelve eligible fields from the identified property record. A valid customer-supplied value takes precedence over stored values, subject to the documented conditional rules.

This does not apply to members of options: omit an option to use its default or inherited value. Boolean options and comparables_limit do not accept null. The whole options object may be omitted or null.

Options

The schema also accepts include_confidence, include_prediction_interval and include_field_sources as booleans. They are not needed for a v3 integration: confidence, the available prediction range and input_resolution are standard parts of every successful valuation, including simple responses. Setting these options to false does not remove those fields. Setting include_field_sources to true does not add a separate field-source section to the public response.

include_feature_drivers is not an accepted customer API option, even when set to false. Do not include it in single requests, batch options or job options. Feature attribution is not returned by these endpoints.

Options controlling supporting evidence do not change the point estimate. Enabling use_stored_data may do so because it can add property information to the request.

In a batch or job, a property inherits each batch-level option unless it explicitly supplies its own value for that option. Explicit false and 0 are overrides, not missing values. If neither level supplies an option, the default above applies. See "Shared Options and Property Overrides" on the Batch Valuations and Asynchronous Jobs page for examples.

Property

Keep UPRNs as strings to avoid numeric precision loss. Use YYYY-MM-DD for dates and JSON numbers for numeric fields, not formatted strings such as "112 m2". The valuation date does not select an older release; see Versioning and Releases.

Type Matrix

Mismatched type and subtype combinations are rejected.

Occupancy

occupancy.status is required and accepts owner_occupied, private_rented or social_rented. It describes occupation, not legal title.

Size

A flat or maisonette may have zero bedrooms, provided the combined number of bedrooms and living rooms is at least one. Unusual room-to-area combinations may be referred for manual valuation. Bungalows are treated as having one above-ground storey; any other valid supplied value is ignored and reported in the response.

Land

land.plot_area_m2 is optional and accepts a positive number. The automated range is 25..2,500; a valid value outside that range is referred for manual valuation rather than clipped. Enter the total area within the title boundary, including the building footprint, rather than the garden area alone.

Plot is ignored for flats. For a house it cannot be smaller than:

floor_area_m2 / storeys

Bungalows use one storey.

Energy

Age bands:

before_1900        1900_1929       1930_1949
1950_1966          1967_1975       1976_1982
1983_1990          1991_1995       1996_2002
2003_2006          2007_2011       2012_2021
2022_onwards

When property.build_status=new_build, the API applies construction_age_band=2022_onwards. The response records whether this value was added or replaced a submitted value. On existing-property endpoints, this does not force a fabric preset: supply the property's actual fabric attributes. Development endpoints instead apply both the newest construction-age band and their fixed modern specification.

Fabric

If a fabric component is unknown, omit it. unknown is not a valid public enum.

Presets and Overrides

A preset supplies defaults for omitted components. Explicit component values take precedence.

Once the component values have been resolved, the preset does not apply a separate blanket adjustment.

Roof Insulation

No insulation:

{"basis": "none"}

Measured:

{"basis": "measured", "depth_mm": 150}

Allowed depths are 25, 50, 75, 100, 150, 200, 250, 300, 350, 400. Represent zero as basis=none.

Estimated:

{"basis": "estimated", "estimated_level": "medium"}

Mixed:

{"basis": "mixed_or_varied"}

For measured, supply depth_mm only. For estimated, supply estimated_level only. Do not include either detail field when the basis is none or mixed_or_varied.

Lease

Leasehold requires one mode.

Simple:

{"mode": "simple", "years_remaining": 83.5}

Detailed:

{
  "mode": "detailed",
  "start_date": "2020-01-01",
  "end_date": "2120-01-01"
}

• Simple requires years remaining and forbids dates.
• Detailed requires both dates and forbids years remaining.
• Remaining and full term must not exceed 9,999 years.
• Start cannot be after valuation date.
• End must be after valuation and start dates.
• Detailed mode derives remaining and full term.
• A successfully valued detailed-leasehold response returns the calculated lease.years_remaining used for the valuation. Rejection before lease validation may prevent this field from being returned.
• Lease details supplied for a freehold property are ignored and listed in input_resolution.

Detailed remaining years are the number of calendar days from the valuation date to the lease end date divided by 365.2425. The response's lease.years_remaining is rounded to six decimal places. Simple mode uses the supplied number, which may include decimals.

Conditional Rules