Build your website with AI

The Fondaro agent network is the shared listing network of the agencies on Fondaro. With one API key, your website can show your agency's listings or every agency's published listings, and an AI site builder can build that website for you from the instructions on this page.

The short version

1. In the dashboard, open Settings → Integrations → API keys and create a key with the Read listings (properties:read) scope. If the site calls the API from the browser, list your website under Allowed websites.
2. In your builder's environment or secrets panel, save the key as FONDARO_API_KEY. Never paste the key into the chat or the code.
3. On the same page, Connect your website with AI gives you these instructions tailored to your agency, with real examples from your own listings. Copy or download them (fondaro-mls-integration.md) and paste them into the builder.

The generic instructions below work too, without signing in.

For AI assistants

• This whole API documentation plus the OpenAPI document, in one file: /llms-full.txt
• An index of every docs page as raw Markdown: /llms.txt
• The OpenAPI 3 document: /openapi/properties.json, also browsable in the API reference

Instructions to paste into your builder

Everything below this heading is written for the builder. The key is always the placeholder FONDARO_API_KEY.

Connection

• Base URL: https://api.fondaro.com
• Authentication: send the header X-API-Key: <FONDARO_API_KEY> on every request.
• The key is the environment variable FONDARO_API_KEY. Read it with process.env.FONDARO_API_KEY in server code. Never write the key into the code or a client bundle.
• Full API description (OpenAPI 3): https://api.fondaro.com/openapi/properties.json
• Scopes: a listings website needs properties:read only. A request without the scope it needs gets 403 with code: "API_KEY_SCOPE_MISSING".

1. Search, first page

curl -X POST "https://api.fondaro.com/properties/search?includeBranding=true" \
  -H "X-API-Key: $FONDARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "own",
    "cursor": "*",
    "limit": 24,
    "query": "sea views",
    "listingType": ["sale"],
    "propertyType": ["house_detached", "penthouse"],
    "city": ["Marbella"],
    "bedrooms": { "min": 3 },
    "price": { "min": 500000, "max": 3000000 },
    "sort": [{ "field": "relevance" }]
  }'

• scope: "own" for your agency's listings, "network" (the default) for every agency's published listings. Other agencies' listings arrive without private fields.
• cursor: "*" starts keyset paging. The response is { "results": [...], "total": 142, "totalIsLowerBound": false, "nextCursor": "..." }; total is on the first page only.
• sort: relevance (best match for query, newest when there is no query), or price, publishedAt, bedrooms, livingArea with "order": "asc" | "desc".
• query is free text: words, "quoted phrases", -exclusion, OR. Numbers are not read as prices or bedrooms: use the filters.
• Other filters: propertyCategory, countryCode, region, bathrooms, livingArea, plotArea, features (for example ["pool", "sea_view"]), boundingBox for a map view.

2. Next page

Send the same body with "cursor": "<nextCursor>". Stop when the response has no nextCursor. When a filter changes, start again with "cursor": "*".

3. One listing

curl "https://api.fondaro.com/properties/<id>?includeBranding=true" \
  -H "X-API-Key: $FONDARO_API_KEY"

<id> is a result's id. Show referenceNumber (FDR-...) as the reference buyers quote.

4. Location menu and filter options

curl "https://api.fondaro.com/properties/stats/aggregations?filterByOrganization=true" \
  -H "X-API-Key: $FONDARO_API_KEY"
curl "https://api.fondaro.com/properties/stats/aggregations?q=sierra" \
  -H "X-API-Key: $FONDARO_API_KEY"

Counts per town (byCity), region, country and property type, plus availableCities and availablePropertyTypes for dropdowns. filterByOrganization=true counts your listings only; without it, the whole network. q narrows towns and regions to names containing it and adds matching communities, for a type-ahead place picker.

Images

• images[]: full-size JPEG photos (up to 1920x1080) with url, order (0 first), isFeatured (the cover), width and height. Use them on the detail page and in galleries.
• thumbnails[]: WebP versions (up to 400x225); originalImageIndex points at the photo. Use them in grids and cards.
• floorPlans[]: floor plan images, same shape as photos.
• Sort by order, lazy-load below the fold, and set width and height to avoid layout shift. Load the URLs as they are (Fondaro hosts them); do not proxy or re-host.

Fields

The OpenAPI document describes every field and enum value. The ones a listings site shows most: title, description, price and currency, listingType (sale, rent, sale_or_rent, fraction), propertyType, city, region, community, latitude and longitude, bedrooms, bathrooms, livingArea and plotArea (in areaUnit), features (amenity slugs), energyRating, agent and organizationBranding (with includeBranding=true).

Do and don't

• Do cache API responses for 60 seconds (for example Next.js revalidate: 60) and render listing pages on the server.
• Do show the listing agency (organizationBranding) and agent on another agency's listing.
• Do handle 429 by waiting the Retry-After seconds; handle 403 (missing scope or origin) and 404 (listing no longer published).
• Don't scrape the Fondaro dashboard or bulk-copy listings into another database; read them through this API.
• Don't put the key in client-side code unless it is a read-only key with allowed websites set to your site.
• Don't show a listing after it disappears from search: it was sold, withdrawn or expired.

Contact form

Fondaro has no public enquiry endpoint a browser may call directly. Make the contact form post to your own site's server code (a server action or serverless function) that emails your agency, including the listing referenceNumber in the message. If your agency uses the Fondaro Integrations API, that server code can instead create a lead with POST https://api.fondaro.com/integrations/v1/leads using a separate integration key with the leads:write scope, kept on the server (see Integrations API).

Ask your builder

Build a property listings website that reads the Fondaro agent network through the API described above, with the key in the FONDARO_API_KEY environment variable used only in server code. Make: a listings grid with photo, title, price, town, bedrooms and bathrooms; filters for price, bedrooms, property type and location (fill the location menu from /properties/stats/aggregations); cursor pagination with a "Load more" button; a detail page per listing with a photo gallery, the description, key facts, amenities, a map from latitude/longitude, the agent card and a contact form that posts to our own server route and emails us with the listing reference. Cache API calls for 60 seconds.

API contract v1.