Developers

Everything technical lives here — your compliance and housing teams never need it, your integration team never needs anything else. Keys, webhooks and EDI are configured self-serve in themanagement portal (Integrations, org-admin role, Platform plan and above).

Interactive API reference (Swagger)OpenAPI 3.0 spec

REST API v1

Base URL https://europe-west2-housingsurvey-pro.cloudfunctions.net/apiV1/v1 · auth Authorization: Bearer hsp_live_…(scoped, revocable, hash-stored). Every read is written to your append-only audit log — integration access is itself evidence.

GET /surveys

HACT-aligned evidence list. Filters status, updatedSince; cursor pagination.

GET /surveys/:id

One record + its chain block (recordHash, prevRecordHash, chainSeq, finalizedAt).

GET /properties

UPRN-keyed stock register with last-survey rollups.

POST /work-orders

Push a case to the field. Link the property by uprn (preferred), propertyId, or free-text address — unknown UPRNs 404 rather than creating unlinked orders. Statutory Awaab's Law deadlines stamp server-side.

GET / POST /contractors

Sync your supply chain: rich contractor records with insurance/accreditation expiry; POST returns an invite code that binds the contractor's organisation when redeemed.

« create a work order against a registered property »
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"uprn":"100012345678","externalRef":"CASE-48211","hazardSeverity":"significant",
       "description":"Tenant reports black mould in child's bedroom"}' \
  https://europe-west2-housingsurvey-pro.cloudfunctions.net/apiV1/v1/work-orders

Webhooks — verify the signature

survey.finalized and statutory-deadline events POST to your endpoint, HMAC-SHA256 signed. Compute the HMAC of the raw body with your signing secret and compare tox-hsp-signature. Failed deliveries retry for an hour.

// Node.js
const crypto = require('crypto');
function verify(rawBody, header, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

EDI flat-file (CSV)

For CMSs that ingest files rather than webhooks: nightly drops (02:00 UK) or on-demand exports. UTF-8, CRLF line endings, RFC 4180 quoting, one row per room reading.Download a sample file →

Column (in order)	Meaning
record_id	Evidence record id
uprn_or_property_id	UPRN when resolved, else internal property id
property_address	Denormalised address
inspection_date	ISO 8601, device-recorded
finalized_at	ISO 8601, server-set at sealing
inspector_ref	Surveyor identifier
performing_org	Org that captured (landlord or contractor)
work_order_ref	Our work-order id
external_ref	YOUR CMS case/job id, echoed back
room	Room the reading belongs to
damp_type	e.g. Condensation, Rising, Penetrating
rh_pct	Relative humidity %
temp_c	Air temperature °C
surface_temp_c	Surface temperature °C
wme_pct	Wood moisture equivalent %
dew_point_c	Dew point °C
observations	Surveyor notes (quoted CSV)
photo_hashes	Semicolon-separated SHA-256 capture hashes
record_hash	The sealed record hash — verify against the API chain block
chain_seq	Position in that property’s evidence chain

Import formats (sample files)

Every import in the portal documents its layout inline and validates row-by-row against it. Prepare your data before you ever sign in:

properties-example.csv — uprn, addressLine1/2, postcode, localAuthority, tenureType, archetype (UPRN keys the evidence chain; rows without one import flagged for review)
team-invites-example.csv — email, name, role (surveyor / manager / org-admin, mixed freely per row)
contractors-example.csv — full supply-chain records incl. trades, regions, insurance and expiry dates

All parsers are BOM/CRLF/quoting tolerant and match columns by header name in any order; required fields are strict, with per-row errors that cite the documented layout.

SCIM 2.0 provisioning

Enterprise plan: point Entra ID (or Okta) provisioning at your per-org SCIM endpoint (minted in the portal with a bearer token shown once). Joiners arrive as surveyors with seats enforced; deactivations disable access instantly — evidence is never deleted.

Calendar feeds (iCal)

Per-surveyor read-only iCal URLs: scheduled visits with one-hour alarms plus statutory deadlines as all-day events. Subscribe in Outlook/Google/Apple Calendar from the portal's app-linking step.

Power Automate

The OpenAPI definition imports directly as a custom connector — wire finalized evidence into Dynamics, SharePoint or Teams without code.

Non-technical documentation lives in the help centre. Stuck? [email protected] — you'll never have to talk to us, but you can.