The REST API

The REST API is HousingSurvey Pro’s on-demand door into your organisation’s data — read evidence and work orders, or write new work orders in, from your own system.

What it is

Every request is served from https://api.housingsurvey.pro/v1 and authenticated with an org-scoped key in the Authorization: Bearer hsp_live_… header. The API covers five resources: surveys (finalized evidence records), properties, tenancies, contractors and work-orders. Everything is JSON, and every list endpoint is cursor-paginated — pass the nextCursor value from one response as the cursor query parameter on the next. The full endpoint-by-endpoint specification lives at /developers/ and /api/docs/, generated from the same OpenAPI document your team can import into Postman, Swagger UI or a Power Automate custom connector.

Before you start

Calling the API needs an org API key with the right scopes — see API keys and scopes — which is itself a Platform-plan feature.

How to do it

1. Mint a key with the scopes your integration needs (see API keys and scopes).
2. Send requests with Authorization: Bearer <your key> on every call.
3. For a list endpoint, start with no cursor and a limit (default 50, maximum 200 on most resources). Read nextCursor off the response; when it’s null, you’ve reached the end.
4. Filter where the endpoint supports it — for example GET /v1/surveys?status=Complete&updatedSince=<ISO date>, or GET /v1/work-orders?statutory_state=approaching.
5. To create a work order from your own system, POST /v1/work-orders with the scope work-orders:write — the same action the MCP server’s raise_work_order tool performs.
6. Use the “Quick start” curl examples and sample HACT payload viewer next to the API key section in the portal to prove out your first call before writing any integration code — see Testing a connection.

How it integrates

Every finalized survey carries lineageId, versionNo and supersedes, so a revised report never overwrites what your system already stored — key your own records by lineageId and treat the highest versionNo you’ve seen as current. Every API call — successful or not — is written to your organisation’s audit log, exactly like a human action in the portal. Reads and writes share one per-organisation rate budget with the MCP server (240 requests per minute), so traffic through either surface draws down the same allowance; a 429 response carries X-RateLimit-* headers and a Retry-After value telling you exactly when to try again.

Common problems

• A request returns 401. The Authorization: Bearer header is missing, malformed, or the key has been revoked.
• A request returns 403 “missing scope”. The key wasn’t minted with the scope that endpoint needs — mint a new key with the right scopes rather than trying to widen an existing one.
• I’m getting 429s. You’ve exceeded the shared per-organisation rate budget — back off using the Retry-After value. This is a generous, abuse-containment limit, not a per-feature throttle, so a well-behaved integration should never come close to it in normal use.
• A list response seems to stop partway through. Keep following nextCursor until it’s null — a response the same size as your limit almost always means there’s more to fetch.