API Reference

Technical reference for the Voseno API endpoints.

Authentication

All API requests require an API key to be included in the header X-API-Key.

curl "https://api.voseno.com/v1/listings" \
  -H "X-API-Key: your_api_key_here"

Endpoints

Listings

`GET /v1/listings`

Search for property listings across all connected sources.

Parameters

Name	Type	Required	Description
`city`	string	No	Filter by city name (e.g., “Amsterdam”)
`min_price`	number	No	Minimum price in Euros
`max_price`	number	No	Maximum price in Euros
`type`	string	No	`rent` or `buy`

Response

{
  "data": [
    {
      "id": "lis_123456789",
      "address": {
        "street": "Keizersgracht",
        "number": "123",
        "city": "Amsterdam",
        "postcode": "1015 CJ"
      },
      "price": 2500,
      "surface_area": 85,
      "source": {
        "name": "Funda",
        "url": "https://funda.nl/..."
      }
    }
  ],
  "meta": {
    "total": 124,
    "page": 1
  }
}

Properties

`GET /v1/properties/{bag_id}`

Retrieve the Golden Record for a specific property using its BAG ID.

Response

{
  "bag_id": "0363010000xxxxxx",
  "building": {
    "year_built": 1905,
    "energy_label": "C",
    "woz_value": 545000
  },
  "valuation": {
    "estimated_price": 560000,
    "confidence": "high"
  }
}

Errors

The API uses standard HTTP status codes to indicate the success or failure of an API request.

200 OK: Request succeeded.
400 Bad Request: Invalid parameters.
401 Unauthorized: Invalid API key.
404 Not Found: Resource not found.
429 Too Many Requests: Rate limit exceeded.