API Documentation

Integrate property liveability reports into your workflow. Use the API directly, or through our Zapier integration (currently in beta - contact support@closeenough.com.au for early access).

The API and bulk lookups are available exclusively to agent accounts. Learn more about agent plans to get started with API access, bulk address uploads, and white-label report sharing.

Authentication

All API requests require an API key sent via the X-API-Key header. API keys are scoped to your organisation and can be created from your agent dashboard.

curl -H "X-API-Key: cesk_your_key_here" \
  https://closeenough.com.au/api/v1/reports

Keys use the prefix cesk_ followed by a random hex string. Store your key securely - it is shown only once when created and cannot be retrieved later.

Base URL

All endpoints are relative to:

https://closeenough.com.au/api/v1

Scopes

API keys are granted specific scopes that control access:

Scope	Access
`reports:read`	List, search, and view reports
`reports:email`	Email reports to recipients
`webhooks:manage`	Subscribe and unsubscribe from webhook events

Default keys are granted all three scopes.

Reports

GET/reports

List reports for your organisation, newest first.

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Results per page, max 100 (default: 25)

Response

{
  "reports": [
    {
      "id": "rpt_abc123",
      "address": "42 Smith St, Collingwood VIC 3066",
      "lat": -37.798,
      "lng": 144.987,
      "generatedAt": 1709366400,
      "shareUrl": "https://closeenough.com.au/r/abc123"
    }
  ],
  "page": 1,
  "perPage": 25,
  "total": 12
}

Scope required: reports:read

GET/reports/search?address=collingwood

Search reports by address text. Returns up to 25 matches.

Parameter	Type	Description
`address` required	string	Address text to search for (case-insensitive partial match)

Scope required: reports:read

GET/reports/:id

Get a single report by ID.

Response

{
  "report": {
    "id": "rpt_abc123",
    "address": "42 Smith St, Collingwood VIC 3066",
    "lat": -37.798,
    "lng": 144.987,
    "generatedAt": 1709366400,
    "shareUrl": "https://closeenough.com.au/r/abc123"
  }
}

Scope required: reports:read

Email Reports

POST/reports/:id/email

Email a report to one or more recipients. Up to 10 recipients per request.

Request Body

{
  "emails": ["buyer@example.com", "agent@realestate.com"],
  "message": "Here is the liveability report for the property."
}

Field	Type	Description
`emails` required	string[]	Recipient email addresses (max 10)
`message`	string	Optional personal message included in the email

Response

{
  "sent": true,
  "count": 2,
  "failed": []
}

Scope required: reports:email

Webhooks

Subscribe to events to receive real-time notifications when reports are generated, shared, or emailed. Webhooks use the REST Hook pattern - subscribe by providing a target URL, and we will POST event payloads to it.

Webhook payloads are signed with HMAC-SHA256. The signature is sent in the X-CE-Signature header. Verify the signature by computing HMAC-SHA256(webhook_secret, request_body) and comparing.

Maximum 5 webhooks per organisation.

POST/hooks

Subscribe to an event. Returns the webhook ID.

Request Body

{
  "targetUrl": "https://hooks.zapier.com/hooks/catch/123/abc",
  "event": "report.generated"
}

Field	Type	Description
`targetUrl` required	string	URL to receive webhook payloads (must be HTTPS)
`event` required	string	Event type to subscribe to (see Events)

Response

{ "id": "wh_abc123" }

Scope required: webhooks:manage

DELETE/hooks/:id

Unsubscribe from a webhook.

Response

{ "deleted": true }

Scope required: webhooks:manage

Events

The following event types are available for webhook subscriptions:

Event	Description
`report.generated`	A new liveability report has been generated
`report.shared`	A report share link has been created
`report.emailed`	A report has been emailed to recipients
`subscription.changed`	Organisation subscription plan has changed

GET/events

List all available event types.

Response

{
  "events": [
    { "key": "report.generated", "label": "Report Generated" },
    { "key": "report.shared", "label": "Report Shared" },
    { "key": "report.emailed", "label": "Report Emailed" },
    { "key": "subscription.changed", "label": "Subscription Changed" }
  ]
}

Error Handling

The API returns standard HTTP status codes with JSON error bodies:

Status	Meaning
`200`	Success
`201`	Created (webhook subscriptions)
`400`	Bad request - missing or invalid parameters
`401`	Unauthorized - missing or invalid API key
`403`	Forbidden - API key lacks required scope
`404`	Not found - resource does not exist or belongs to another org
`500`	Server error

Error responses include a JSON body:

{ "error": "Description of what went wrong" }

Rate Limits

API requests are rate-limited per API key. Current limits are generous for typical integration use. If you encounter rate limiting, implement exponential backoff and retry.

Email sending is limited to 10 recipients per request and subject to fair use. Webhook subscriptions are limited to 5 per organisation.

Coverage

Close Enough covers addresses within Victoria, Australia. Addresses outside Victoria will be rejected. Data quality is highest within Greater Melbourne, with regional areas having reduced coverage for some metrics.

For more detail on data sources and methodology, see the methodology page.