Identity and Stored Data

Before valuing an existing property, the API verifies its identity. This ensures that the request refers to the correct address and that any eligible stored data belongs to that property.

Identity Resolution for Existing Properties

1. The request must include the building name or number, street and postcode.
2. A supplied UPRN is verified against that address.
3. If the UPRN is omitted, the API attempts to resolve the address to one UPRN.
4. Only a single exact match in England or Wales is accepted.
5. Partial, ambiguous, multiple, mismatched and unsupported-location results are rejected before valuation.

Development endpoints bypass identity resolution because the subject may not yet exist in the property register.

Supplied UPRN Path

{
  "uprn": "100012345678",
  "building_number_or_name": "14",
  "street": "Station Road",
  "postcode": "OX1 1AA"
}

The UPRN is not accepted in isolation. A previously verified address and UPRN pair returns identity_source=verified_identity_store; otherwise, the pair is verified before valuation. A mismatch is rejected as uprn_address_mismatch.

Address-Only Requests

{
  "uprn": null,
  "building_number_or_name": "14",
  "street": "Station Road",
  "postcode": "OX1 1AA"
}

An exact match obtained through address resolution returns identity_source=address_resolved. Reuse of a previously verified address returns verified_identity_store, even when you did not supply a UPRN. The API does not select a “closest” result when several properties could match.

Identity Failures in Batch Requests

Identity failures affect only the relevant rows. A 100-row request containing three ambiguous addresses can return HTTP 200 with 97 valued rows, three rejected rows and an overall status=partial. Input order is preserved.

Stored Data

options.use_stored_data defaults to false and requires the corresponding API scope when enabled. It applies only to:

land.plot_area_m2
energy.current_efficiency_score
energy.potential_efficiency_score
energy.consumption_kwh_m2_year
energy.construction_age_band
energy.extension_count
energy.solar_pv_supply_percent
fabric.roof_insulation
fabric.wall_insulation
fabric.floor_insulation
fabric.glazing
fabric.lighting

It does not apply to property type, subtype, title tenure, floor area, room counts, storeys, occupancy or lease details.

Input Precedence

explicit valid customer value
    > matched stored property value
    > no customer override

Stored values never overwrite explicit values. The documented conditional rules still take precedence: for example, a flat's plot is ignored and a new build uses the newest construction-age band. Fabric presets supply defaults for omitted components; explicit component choices take precedence.

With use_stored_data=true, an eligible blank field may be populated. With false, it remains unspecified. This option controls only the twelve customer fields listed above; it does not disable other information used to provide the valuation service.

Input-Resolution Record

{
  "input_resolution": {
    "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 section lists stored values applied to the request, supplied values ignored as inapplicable and public fields derived by the API. It is not a complete property record. Enabling stored data does not guarantee that every eligible field is available.

Coverage Metadata

curl --silent --show-error \
  --header "Authorization: Bearer $VALTAIC_API_KEY" \
  "https://api.valtaic.io/v3/coverage?postcode=OX1%201AA&uprn=100012345678" | jq

The endpoint checks whether the postcode and, if supplied, UPRN are represented in the active release. These are separate presence checks: it does not verify that the UPRN belongs to the postcode or the submitted address.

supported means the requested presence checks succeeded. unsupported means at least one returned a negative result; unknown means coverage could not be confirmed. Read postcode_present_in_release and uprn_present_in_release alongside the status. Coverage does not guarantee an automated valuation, so automated_valuation_guaranteed is always false.