The HOUSING-iQ API
Read and write homes, tenants, repairs, complaints, appointments and rent from your own systems, and hear about every change as it happens.
Quickstart
- An organisation admin signs in to the staff console and opens More, then API and webhooks.
- Create a test key. It works on your API sandbox: a separate copy of HOUSING-iQ with made-up homes, tenants, repairs and rent, created for you with your first test key.
- Make your first request:
curl https://api.housing-iq.com/v1/organisation \
-H "Authorization: Bearer hiq_test_your_key"
{
"object": "organisation",
"id": "6f1c2b4e-8a3d-4c55-9e21-3b7d0a9f4c12",
"name": "Millbrook District Council (API sandbox)",
"slug": "millbrook-sandbox",
"kind": "council",
"livemode": false,
"sign_in_url": "https://cloud.housing-iq.com/millbrook-sandbox"
}
Then list repairs, report one and book the visit:
curl "https://api.housing-iq.com/v1/repairs?status=new,triaged&limit=10" \
-H "Authorization: Bearer hiq_test_your_key"
curl -X POST https://api.housing-iq.com/v1/repairs \
-H "Authorization: Bearer hiq_test_your_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 8b0c6a0e-1f7e-4d35-9b56-2b1c4f6e9d10" \
-d '{"tenant_id":"2d9e7a10-5b4c-4f8e-a1d3-7c6b5e4f3a21","category":"damp_mould","title":"Black mould in the bedroom","priority":"urgent","is_damp":true}'
curl -X PATCH https://api.housing-iq.com/v1/repairs/REPAIR_ID \
-H "Authorization: Bearer hiq_test_your_key" \
-H "Content-Type: application/json" \
-d '{"status":"scheduled","scheduled_for":"2026-11-27T10:00:00Z","contractor_company":"Alder Builders"}'
HOUSING-iQ gives the new repair its reference, works out its Awaab's Law deadlines and repair target, and tells the tenant when the visit is booked, exactly as if staff had done it in the app.
Keys and the sandbox
| Key | Works on | Use it for |
|---|---|---|
hiq_test_... | Your API sandbox, made-up data | Building and testing. Nobody real is told anything; sandbox email addresses are never sent to. |
hiq_live_... | Your organisation's real records | Your connected systems, once they work in the sandbox. |
Keys are shown once, when they are created. HOUSING-iQ keeps only a fingerprint of each key, so it cannot show a key again: create a new one and revoke the old one. Keep keys on your servers, never in a browser or an app. Every key can be revoked at once from the staff console, and every request is listed there with its status and request id.
Scopes
| Scope | Allows |
|---|---|
read | Reading every resource except the sensitive ones, events and export. |
write | Creating, updating and removing records. |
sensitive | Casework, anti-social behaviour reports and wellbeing check-ins. Give it only to systems that need it. |
The same rules as the app
Each request acts as the organisation admin who created the key. Everything that applies in the app applies to the API: each organisation's records are kept apart by the database, rent statement lines can never be edited or deleted, Awaab's Law and complaint deadlines are worked out for you, tenants are told about changes, and every change is written to the audit log. If the admin who created a key loses access, the key stops working.
Requests and responses
- Base URL
https://api.housing-iq.com/v1, HTTPS only. - Send JSON with
Content-Type: application/json; responses are JSON. - Each record has an
objectfield naming its kind, and uses the same field names everywhere. - Dates are
YYYY-MM-DD; times are ISO 8601 in UTC, for example2026-11-24T10:30:00Z. Money is in pounds. PATCHchanges only the fields you send. Unknown fields, and fields that cannot be written, are refused rather than ignored.- Housing records are kept:
DELETEexists only for properties, tenancies and notices, and setsdeleted_at. - Every response has a
request-idheader. Quote it if you contact us.
Lists and pagination
Lists return the newest first, 25 at a time (up to 100 with limit). Pass next_cursor back as starting_after for the next page. Filter by the fields marked as filters in the reference; separate several values with commas. created_after, created_before and updated_since narrow by time.
{
"object": "list",
"url": "/v1/repairs",
"data": [
"..."
],
"has_more": true,
"next_cursor": "eyJjIjoiMjAyNi0xMS0yMlQyMTo1..."
}
Safe retries
Send an Idempotency-Key header with any unique value on a POST. If the network fails and you send the same request again with the same key within 24 hours, you get the first response back (with idempotent-replayed: true) instead of a second record. Reusing a key for a different request is refused.
Errors
Errors use the usual HTTP status codes and a body you can show to a person:
{
"error": {
"type": "invalid_request_error",
"code": "invalid_value",
"message": "A statement line cannot be dated in the future",
"param": "occurred_on",
"request_id": "req_7f3a9c1e2b4d4e8f9a0b1c2d"
}
}
| Status | Type | Meaning |
|---|---|---|
| 400 | invalid_request_error | A field is missing, unknown or not valid; param names it. |
| 401 | authentication_error | No key, or the key is revoked, expired or its admin no longer has access. |
| 403 | permission_error | The key lacks a scope, or HOUSING-iQ's rules do not allow the change. |
| 404 | invalid_request_error | No such record in your organisation, or no such route. |
| 405 | invalid_request_error | That resource cannot be created, changed or removed through the API. |
| 409 | invalid_request_error or idempotency_error | The record already exists, or an Idempotency-Key was reused. |
| 429 | rate_limit_error | Too many requests; wait and try again. |
| 500 | api_error | Something went wrong on our side. |
Rate limits
Each key can make 300 requests a minute. Responses carry ratelimit-limit and ratelimit-remaining. Use webhooks or the event feed rather than asking again and again whether something changed.
Keeping your systems in step
Webhooks
Each change is sent to your endpoint as it happens, signed with your secret. How webhooks work.
Event feed
GET /v1/events?after=evt_... returns every change since the last one you read, oldest first, for 30 days. Store the last id and carry on from it.
Export
GET /v1/export/repairs returns every record as newline-delimited JSON, ready to load into a data warehouse, with the same filters as lists.
A dependable pattern: load everything once with export, then keep up with webhooks, and read the event feed after any outage on your side to catch anything you missed.
Resources
| Resource | Path | What you can do |
|---|---|---|
| Properties | /v1/properties | read, create, update, remove |
| Tenants | /v1/tenants | read, create |
| Tenancies | /v1/tenancies | read, create, update, remove |
| Repairs | /v1/repairs | read, create, update |
| Repair events | /v1/repair_events | read |
| Complaints | /v1/complaints | read, create, update |
| Cases | /v1/cases | read |
| Appointments | /v1/appointments | read, create, update |
| Rent accounts | /v1/rent_accounts | read, create, update |
| Rent transactions | /v1/rent_transactions | read, create |
| Anti-social behaviour reports | /v1/asb_reports | read |
| Inspections | /v1/inspections | read, create, update |
| Empty homes | /v1/voids | read, create, update |
| Compliance certificates | /v1/compliance_certificates | read, create, update |
| Documents | /v1/documents | read |
| Notices | /v1/notices | read, create, update, remove |
| Wellbeing check-ins | /v1/checkins | read |
Versions
This is version 2026-11-22, shown in the housing-iq-version header. We add fields and resources without notice, so ignore fields you do not know. Anything that would break an integration comes as a new version, announced in advance.
The OpenAPI 3.1 document is at https://api.housing-iq.com/v1/openapi.json, for generating a client in any language or importing into Postman.