# WoningMe Developer API

Dutch Rental Listings API. Rental listings from 900+ sources across the Netherlands through one REST API: social housing, mid-market (middenhuur) and private-sector rentals, queried by city and radius. New listings can be pushed to your server by signed webhook. Rentals only, no properties for sale.

- Page: https://woning.me/developer
- Documentation: https://woning.me/developer/docs
- OpenAPI 3 spec: https://woning.me/developer/openapi.json
- Terms: https://woning.me/developer/terms
- Sign up: https://woning.me/developer/register

## Pricing

- Personal plan: EUR 15 per month, for personal and non-commercial use, billed through Stripe, VAT included.
- New accounts get a 2-day trial. The API only works once billing is set up, so a payment method is added first. Cancel within the 2 days and nothing is charged. Without billing, requests return HTTP 402.
- One trial per account. Resubscribing after cancelling is charged immediately.
- Commercial use, higher volumes or other use cases: collaboration is possible, see https://woning.me/en/collaborate

## For AI assistants and people who build with AI

- Quickest call, no setup: `GET https://woning.me/api/developer/v1/listings?city=Utrecht&max_price=1500` (city names are forgiving; rent is in euro cents).
- MCP server (Streamable HTTP): `https://woning.me/mcp`, authenticate with `X-Api-Key` or `Authorization: Bearer <key>`. Tools: search_rentals, list_saved_searches, create_saved_search, delete_saved_search, get_saved_search_listings, get_webhook, set_webhook, test_webhook. Guide: https://woning.me/developer/mcp-server
- Copy-paste prompt for an AI assistant: https://woning.me/developer/ai-prompt.txt, guide: https://woning.me/developer/build-with-ai
- Errors include a `hint` field that says how to fix them.

## How it works

1. Create an account, add a payment method in the dashboard, generate an API key (shown once).
2. Create searches with a city and a radius (max 50 km) and optional price, room and surface filters. Optionally set one account webhook URL.
3. Read matching properties with cursor pagination, or receive `listing.new` webhooks.

Authentication: header `X-Api-Key: <key>`.

```
curl -X POST https://woning.me/api/developer/v1/searches \
  -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"label":"Utrecht","city":"Utrecht","radius_km":5,"max_price":1600}'

curl -X PUT https://woning.me/api/developer/v1/webhook \
  -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://you.dev/hooks"}'

curl "https://woning.me/api/developer/v1/searches/42/properties?limit=5" -H "X-Api-Key: $KEY"
```

## Webhooks

On a new match we POST JSON `{"event":"listing.new","searches":[{"id":42,"label":"Utrecht"}],"property":{...}}` to your account webhook URL. The raw body is signed with HMAC-SHA256 using the webhook `secret`; the digest is in the `X-WoningMe-Signature` header as `sha256=<hex>`. A failed delivery is retried once after about 30 seconds. Delivery history: `GET /api/developer/v1/webhook/deliveries`.

## Limits

30 requests per minute per key. Property endpoint: 5,000 requests per rolling 24 hours, 50,000 per rolling 30 days, 50 properties per request. 10 searches per account. Search radius up to 50 km. Search changes: 20 per minute, 50 per rolling 24 hours.

## Property fields

id, source, sourceLabel, url, imageUrl, street, postcode, city, propertyType, surfaceM2, rooms, priceEurCents, priceText, agent, agentWebsite, agentPhone, isHousingAssociation, isMiddenhuur, lat, lon, firstSeenAt, lastSyncedAt. Many fields can be null because agencies do not all publish the same data.