Integrations & API

API keys and webhooks (for developers)

Use the havelo API to read and create properties, tenants and maintenance, and receive webhooks for real-time events.

This guide is for developers who want to connect their own systems to havelo. If you just want to link havelo to another app without code, use Zapier instead.

Integrations are available on the Pro plan and above.

API keys

Every request is authenticated with a personal API key.

In havelo, open Settings and choose the Integrations tab.
Click Create API key and give it a name.
Copy the key immediately. It starts with hv_live_ and is shown only once.

Keep keys secret and out of version control. You can revoke a key at any time and it stops working instantly. Create a separate key per system, so you can revoke one without affecting the others.

Base URL

All endpoints live under https://api.havelo.co.uk/api/public/v1.

Authentication

Send your key on every request, either as a bearer token or an X-API-Key header:

Authorization: Bearer hv_live_your_key_here

For example, to confirm your key works:

curl https://api.havelo.co.uk/api/public/v1/me -H "Authorization: Bearer hv_live_your_key_here"

Endpoints

Method	Endpoint	What it does
GET	/me	The account the key belongs to
GET	/properties	List your properties
POST	/properties	Create a property
GET	/properties/{id}	Get one property
GET	/tenants	List your tenants
POST	/tenants	Create a tenant
GET	/maintenance	List maintenance requests
POST	/maintenance	Create a maintenance request

List endpoints return newest first, in the shape { "object": "list", "data": [ ... ] }. Every request is scoped to the account that owns the key, so you only ever see your own data.

Creating records

Send a JSON body with Content-Type: application/json. A successful create returns 201 and the created object (see Response objects below).

POST /properties fields

Field	Type	Required	Notes
address_line_1	string	Yes	First line of the address
city	string	Yes	Town or city
postcode	string	Yes	UK postcode
address_line_2	string	No	Second address line
property_type	string	No	Defaults to `house`. One of house, flat, terrace, semi-detached, detached, bungalow, hmo, other
bedrooms	integer	No	Number of bedrooms
bathrooms	integer	No	Number of bathrooms
monthly_rent	number	No	Monthly rent in GBP

POST /tenants fields

Field	Type	Required	Notes
property_id	integer	Yes	A property you own
first_name	string	Yes
last_name	string	Yes
email	string	No
phone	string	No

POST /maintenance fields

Field	Type	Required	Notes
property_id	integer	Yes	A property you own
title	string	Yes	Short summary of the issue
description	string	No	Full detail
category	string	No	Defaults to `other`. One of plumbing, electrical, heating, appliance, structural, pest, garden, other
priority	string	No	Defaults to `medium`. One of low, medium, high, urgent

Example (create a repair):

curl -X POST https://api.havelo.co.uk/api/public/v1/maintenance -H "Authorization: Bearer hv_live_your_key_here" -H "Content-Type: application/json" -d '{"property_id": 1, "title": "Leaking tap", "priority": "high"}'

Response objects

Properties, tenants and maintenance requests are returned in these shapes (the same shapes are used in webhook payloads). Fields that can be empty are marked nullable.

Property

Field	Type	Notes
id	integer	Unique id
object	string	Always `property`
address_line_1	string
address_line_2	string, nullable
city	string
postcode	string
country	string
property_type	string
bedrooms	integer, nullable
bathrooms	integer, nullable
status	string	For example `occupied` or `vacant`
monthly_rent	number, nullable	GBP
created_at	datetime	ISO 8601
updated_at	datetime, nullable	ISO 8601

Tenant

Field	Type	Notes
id	integer	Unique id
object	string	Always `tenant`
property_id	integer	The property they belong to
first_name	string
last_name	string
email	string, nullable
phone	string, nullable
status	string	For example `active`
created_at	datetime	ISO 8601
updated_at	datetime, nullable	ISO 8601

Maintenance request

Field	Type	Notes
id	integer	Unique id
object	string	Always `maintenance_request`
property_id	integer
tenant_id	integer, nullable	Set if a tenant reported it
title	string
description	string, nullable
category	string
priority	string	low, medium, high or urgent
severity	string, nullable
status	string	For example `reported`, `in_progress`, `completed`
total_cost	number, nullable	GBP
reported_by_tenant	boolean
created_at	datetime	ISO 8601
updated_at	datetime, nullable	ISO 8601
completed_at	datetime, nullable	ISO 8601

Status codes and errors

Code	Meaning
200	Success (GET requests)
201	Created (successful POST)
401	Missing or invalid API key
404	Resource not found, or not owned by your account
422	Invalid request body (a required field is missing or the wrong type)

Errors return a JSON body of the form { "detail": "a human readable message" }.

Webhooks

Instead of polling, you can have havelo push events to your server the moment they happen.

In Settings, then Integrations, add a webhook endpoint (a public https URL on your server).
havelo sends a POST with a JSON body whenever a matching event fires.
You can send a test delivery from the same screen.

Events

property.created
tenant.created
maintenance.created
maintenance.updated
maintenance.completed

Verifying a delivery

Each delivery includes these headers:

X-Havelo-Event: the event type, for example maintenance.created.
X-Havelo-Delivery: a unique id for the delivery.
X-Havelo-Signature: a signature in the form sha256=<hex>.

The signature is an HMAC-SHA256 of the exact request body, using your endpoint's signing secret (it starts with whsec_ and is shown when you create the webhook). Recompute it on your side and compare, to be sure the request really came from havelo. Reject anything that does not match.

Notes

All traffic is over HTTPS.
Keep your API keys and webhook secrets private. Rotate them if they are ever exposed.
Need a hand? Contact support.

Automate havelo: connect it to your other apps

Connect havelo to Zapier (step by step)

Still stuck?

Send us a note (we reply within one working day).