Quickstart · ~5 minutes

Make your first call

By the end of this guide you will have made an authenticated request to your own HomeDash data, in a safe sandbox, without writing any application code. Then we will switch to live and try a write.

Open the Developer Dashboard

Sign in to HomeDash and head to Dashboard → Developer. If you do not see this entry in the sidebar, your plan does not include API access yet — upgrade to Portfolio (reads + webhooks) or Enterprise (reads + writes + webhooks).

Generate a sandbox API key

On the API keys tab, click Generate key and choose:

Mode: sandbox — reads return your real data, writes return mocks.
Scope: read_write so we can try a write later.
Name: something memorable like "Quickstart".

The full key is shown once. Copy it somewhere safe before closing the dialog. After that, only the prefix (e.g. hd_sandbox_a8c1d3e5) is visible.

Make your first read call

Paste this in your terminal, replacing YOUR_KEY:

BASH

curl https://app.homedash.co.uk/api/public/v1/properties \
  -H "Authorization: Bearer YOUR_KEY"

You should get something like:

JSON

{
  "data": [
    {
      "id": "5b1e07e0-1cb9-4f8c-a3e1-6b6f0a72e9f1",
      "address": "12 Test Street, London, SW1A 1AA",
      "status": "Occupied",
      "rentAmount": 1200,
      "tenantName": "A. Tenant"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 42, "hasNextPage": true }
}

List endpoints return meta.page, meta.limit, meta.total, and meta.hasNextPage. Use ?page=2&limit=100 (max 500) to fetch the rest of your portfolio. Data is always scoped to the landlord tied to your API key.

Notice the response also includes X-HomeDash-Mode: sandbox and X-RateLimit-* headers.

Current occupants: resolve who lives at a property from its active contract — not from tenant propertyId or tenant status (those can lag after move-out). Call GET /contracts?propertyId={uuid}&status=Active, take mainTenantId plus every ID in additionalTenantIds, then fetch names/contact with GET /tenants/{id} for each occupant.

Try a sandbox write

Pick a property id from step 3 and create a maintenance task in sandbox. No data is written; the response is a realistic mock so you can wire your code against the real shape.

BASH

curl -X POST https://app.homedash.co.uk/api/public/v1/tasks \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Boiler not heating water",
    "propertyId": "5b1e07e0-1cb9-4f8c-a3e1-6b6f0a72e9f1",
    "priority": "High"
  }'

Response:

JSON

{
  "data": {
    "id": "9b8c4f6a-3d1e-4a2b-9f7c-1e2d3c4b5a6f",
    "title": "Boiler not heating water",
    "propertyId": "5b1e07e0-1cb9-4f8c-a3e1-6b6f0a72e9f1",
    "priority": "High",
    "status": "New",
    "createdAt": "2026-05-04T17:00:00.000Z",
    "sandbox": true
  }
}

The "sandbox": true flag is your safety net. In your integration, log a warning if you see it in production traffic.

Switch to live

When you are ready, generate a second key with mode = live and replace the key in your code. Nothing else changes — the URLs, headers, and response shapes are identical between sandbox and live.

For AI assistants (Claude, ChatGPT custom GPTs, etc.) always use a read_only key. Never give an AI a key that can change your data.

Authentication deep-dive Rent invoices (PDF & email)Set up webhooks Full API reference