Endpoint Reference

This reference summarises the public valuation endpoints, their required permissions, response formats and request limits.

Base URL:

https://api.valtaic.io

All operations require an API key. POST bodies are JSON. See Limits and Safeguards for request controls and Latency and Throughput for measured response times.

Choose an Endpoint

Simple Value

POST /v3/simple-value returns a concise valuation for one existing property, including the point estimate, range, confidence and input-resolution record. It does not return comparables or context. Use it for latency-sensitive interactive requests.

curl --silent --show-error \
  -X POST "https://api.valtaic.io/v3/simple-value" \
  -H "Authorization: Bearer $VALTAIC_API_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json | jq

A structurally valid but out-of-domain property returns a referred response without a point estimate. Invalid or unresolved input is rejected with HTTP 422 on a single endpoint. A temporary identity-provider failure may instead return 503; inspect the error code and retryable field.

Standard Value

POST /v3/value returns a valuation for one existing property and can include supporting evidence selected through the request options.

Place these settings inside the top-level options object, alongside the required property, occupancy and size sections:

{
  "include_comparables": true,
  "comparables_limit": 5,
  "include_context_metrics": true
}

comparables_limit controls the number of records returned; it does not alter the valuation.

Simple Batch

POST /v3/simple-batch-value accepts between 1 and 2,500 existing-property requests. Each row uses the same property schema as the single endpoint.

{
  "options": {"use_stored_data": false},
  "requests": [
    {
      "request_reference": "row-1",
      "property": {
        "valuation_date": "2026-10-01",
        "postcode": "OX1 1AA",
        "building_number_or_name": "14",
        "street": "Station Road",
        "type": "S",
        "subtype": "house_semi_detached",
        "title_tenure": "freehold"
      },
      "occupancy": {"status": "owner_occupied"},
      "size": {"floor_area_m2": 112, "bedrooms": 3, "living_rooms": 2, "storeys": 2}
    }
  ]
}

Results preserve input order and include a separate status for every row. This address is illustrative, not a verified property. Replace it with the real address and an allowed valuation date. If you omit the UPRN, address resolution must succeed before the property can be valued. Empty property sections are not valid inputs.

Standard Batch

POST /v3/batch-value accepts between 1 and 2,500 rows and returns the requested supporting evidence. Use the simple batch endpoint when those sections are not required.

Check limits.synchronous_batch_rows for the active limit. Use valuation jobs for work that must survive a disconnected client, subject to your plan limits.

Development Value

POST /v3/development-value returns an as-complete new-build valuation for one proposed or unregistered property. Its schema excludes the UPRN, build_status, fabric, energy.construction_age_band and options.use_stored_data. The endpoint does not perform address resolution or inherit stored subject-property data; new-build status and the current construction-age band are applied automatically, together with typical modern fabric. Site latitude and longitude are required for comparable retrieval. See Development Valuations.

Development Batch

POST /v3/development-batch-value accepts between 1 and 2,500 proposed units under the same rules. Each unit must include the required property and location fields because no registered subject record is used.

Use a development valuation job for durable processing of unit schedules, subject to your access and published job limits.

Create Valuation Job

POST /v3/valuation-jobs creates an asynchronous valuation job. Submit at least one property and stay within limits.asynchronous_job_rows from the current release metadata, your plan limit and the maximum request-body size:

Use the complete job request example. It contains mode, idempotency_key, optional shared options and a non-empty requests array. Replace its illustrative property details and valuation dates before submission. An empty requests array is rejected.

mode accepts simple, standard or development. Development jobs use the development-property request schema and require both avm:value and avm:development. HTTP 202 confirms that the request has been accepted and queued; it does not indicate completion. The effective size is limited by the API contract, customer plan and maximum request-body size.

This endpoint is capability-gated. Call it only when it appears in the endpoints returned by GET /v3/releases/current; otherwise use a synchronous batch.

Read Job Status

GET /v3/valuation-jobs/{job_id} returns:

queued -> running -> completed
                  -> failed

Jobs are tenant-isolated.

Read Job Results

GET /v3/valuation-jobs/{job_id}/results returns the completed batch envelope. Before completion it returns HTTP 202, Retry-After: 5, and the current job document.

Current Release

GET /v3/releases/current returns the active release ID, effective date, supported countries and property types, permitted valuation-date window, limits and available endpoints. Query it at startup and cache the response briefly rather than hard-coding date boundaries.

Coverage

GET /v3/coverage?postcode=OX1%201AA&uprn=100012345678 checks representation in the active release without requesting a valuation. postcode is required and uprn is optional. Postcode and UPRN presence are checked separately; this does not verify that they belong together or resolve an address. Coverage does not guarantee that an automated valuation will be returned.