For Developers

Build applications on the Property Data Trust Framework. Open standards, REST APIs, and JSON Schema — everything you need to integrate.

Get Started View on GitHub
🚀

Getting Started
📡

API Reference
📋

Schemas
🔐

v2.0 (VCs)

Getting Started

Core Concepts

Claims

Data in PDTF is represented as claims — statements about a property with attached provenance. Claims are immutable; updates are made by adding new claims.

Transactions

The central entity in PDTF. A transaction is created for a property and tracks all claims, state, and participants. Transactions are identified by transactionId and can be searched by UPRN or status.

Provenance

Every claim carries provenance metadata: who made the claim, when, with what evidence, and at what trust level. This is based on the OpenID Connect 'verified claims' standard.

Subscriptions

Subscribe to a transaction by POSTing a callbackUrl to receive webhook notifications when new claims are added. DELETE to unsubscribe.

Quick Start

# Create a new transaction
curl -X POST \
  https://api.example.com/pdtfService/transactions \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"
# Get current state of a transaction
curl -X GET \
  https://api.example.com/pdtfService/transactions/{transactionId}/state \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
# Post claims to a transaction
curl -X POST \
  https://api.example.com/pdtfService/transactions/{transactionId}/claims \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '[{
    "claims": {
      "/propertyPack/energyEfficiency/currentEnergyRating": {
        "value": "B"
      }
    },
    "verification": {
      "trustFramework": "pdtf",
      "evidence": [{
        "type": "electronic_record",
        "record": {
          "source": { "name": "EPC Register" }
        }
      }]
    }
  }]'
View full API examples on GitHub

API Reference

The PDTF API follows REST conventions with OpenAPI specification. All data is exchanged as JSON.

Authentication: All endpoints require a Bearer token (JWT) via the Authorization: Bearer {token} header.

POST /pdtfService/transactions

Create Transaction

Create a new property transaction. Returns a transactionId and schema reference.

GET /pdtfService/transactions/search

Search Transactions

Search for transactions by UPRN or status. Returns a list of matching transactions.

GET /pdtfService/transactions/{transactionId}/state

Get State

Get the computed current state of a transaction formatted as a PDTF property pack schema.

GET /pdtfService/transactions/{transactionId}/claims

Get Claims

Retrieve all claims for a transaction, including full verification metadata.

POST /pdtfService/transactions/{transactionId}/claims

Create Claims

Submit an array of verified claims for a transaction. Claims are validated against the PDTF schema.

POST /pdtfService/transactions/{transactionId}/subscribe

Subscribe

Subscribe to webhook notifications when new claims are added. Body: {callbackUrl}

DELETE /pdtfService/transactions/{transactionId}/subscribe

Unsubscribe

Cancel an existing webhook subscription for this transaction.

Full OpenAPI Specification →

Transaction Schema

All property data follows the PDTF Transaction Schema — a JSON Schema defining the complete data structure for a property transaction in England and Wales. It supports mapping to BASPI, Law Society TA forms, and RICS data standards.

View full schema (v3) ↗

pdtf-transaction.json

object
├─ transactionId string — UUID
├─ status enum — active | For sale | Under offer | Sold STC | …
├─ externalIds object
├─ participants array
├─ name object
├─ role string
├─ email, phone, organisation, address …
├─ propertyPack object — the core data structure
├─ address, uprn, location, localAuthority
├─ priceInformation, marketingTenure, media
├─ buildInformation, residentialPropertyFeatures
├─ ownership, parking, councilTax, energyEfficiency
├─ listingAndConservation, typeOfConstruction
├─ electricity, waterAndDrainage, heating, connectivity
├─ disputesAndComplaints, alterationsAndChanges, notices
├─ insurance, rightsAndInformalArrangements, environmentalIssues
├─ legalOwners, legalBoundaries, occupiers
├─ guaranteesWarrantiesAndIndemnityInsurances
├─ completionAndMoving, fixturesAndFittings
├─ titlesToBeSold array — HMLR title records
├─ searches array — search enquiries
├─ localSearches, documents, saleReadyDeclarations …
└─ valuationComparisonData object
├─ propertyDetails array
└─ propertyPricing object

The propertyPack object contains 40+ sub-schemas covering BASPI material facts, TA6/TA7 form fields, title data, searches, and conveyancing declarations.

View Full Schema (JSON) Browse Schemas on GitHub

PDTF v2.0

Preview

The next generation of PDTF uses W3C Verifiable Credentials and Decentralised Identifiers for cryptographic trust.

What's New in v2.0

Verifiable Credentials

W3C standard credentials with cryptographic proofs. No need to verify back with the source.

Decentralised Identifiers (DIDs)

Stable identifiers for participants with public-key binding. Example: did:web:moverly.com:users:abc

Entity Graph

Property → Title → Transaction relationships with participation credentials linking parties.

Per-Credential Access Control

termsOfUse field with confidentiality levels and role-based presentation policies.

Trust Registry

{
  "rootIssuers": {
    "HMLR": {
      "did": "did:web:hmlr.gov.uk",
      "claimPaths": ["/propertyPack/titles"]
    },
    "VoA": {
      "did": "did:web:voa.gov.uk",
      "claimPaths": ["/councilTaxBand"]
    }
  },
  "trustedProxies": {
    "tmGroup": {
      "did": "did:web:api.tmgroup.co.uk",
      "claimPaths": ["/searches"]
    },
    "moverly": {
      "did": "did:web:trust.moveready.com",
      "claimPaths": ["/propertyPack"]
    }
  }
}

The trust registry at trust.propdata.org.uk maintains the list of root issuers and trusted proxies.

Two-Phase Implementation

Phase 1 - Now

Trusted Proxies

Existing API providers (tmGroup, Moverly) wrap responses in PDTF-compliant VCs, signing with their trusted proxy keys. "Map-and-wrap" adaptors require minimal infrastructure changes.

Phase 2 - Future

Root Issuers

Primary sources (HMLR, VoA) issue PDTF-compliant VCs directly. Highest level of achievable trust with no intermediary signatures required.

Integration Guides

Joining the Framework

Step-by-step guide to becoming a PDTF participant, including DID setup and agent configuration.

Legacy Integration

Patterns for connecting existing systems to PDTF using legacy gateways and bidirectional mapping.

Reference Implementation

Example code and SDK references for building PDTF-compliant applications.

Ready to Build?

Join the developer community, explore the code, and start building on PDTF.

Explore on GitHub Join the Community