# Build with AI

> Instructions an AI site builder can follow to turn the Fondaro listings API into a website, with the key kept in FONDARO_API_KEY.

With one API key, your website can show your agency's listings or every agency's published listings on the Fondaro network. An AI site builder (v0, Lovable, Bolt, Claude Code, Cursor) can build that website 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

- All API pages and the API reference as Markdown, in one file: [/llms-api.txt](https://www.fondaro.com/llms-api.txt)
- Every guide in the documentation, in one file: [/llms-full.txt](https://www.fondaro.com/llms-full.txt)
- An index of every docs page, each linking its Markdown copy: [/llms.txt](https://www.fondaro.com/llms.txt)
- A small skill file that points an AI assistant at the REST API and these pages: [/skills/fondaro/SKILL.md](https://www.fondaro.com/skills/fondaro/SKILL.md)
- The REST API for your own code, one page per area (leads, deals, brochures and more), starting at the [API overview](https://www.fondaro.com/docs/api/overview.md)
- The OpenAPI 3 document for the whole Fondaro API: [/openapi/fondaro.json](https://www.fondaro.com/openapi/fondaro.json) (the listings and property search part alone is still at [/openapi/properties.json](https://www.fondaro.com/openapi/properties.json), for existing integrations), also browsable in the [API reference](https://www.fondaro.com/docs/api-reference.md) and as Markdown at [/docs/api-reference.md](https://www.fondaro.com/docs/api-reference.md)

Every docs page is also plain Markdown at its own address plus `.md` (for example `https://www.fondaro.com/docs/api/properties/search.md`), or send `Accept: text/markdown` to the page address. On any docs page, **Copy page** copies the page as Markdown, and **Open in ChatGPT** or **Open in Claude** starts a chat that is already pointed at it. To use the whole product with your own assistant, see [Use Fondaro with your AI](https://www.fondaro.com/docs/dashboard/use-with-ai.md).

## 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 `Authorization: Bearer <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/fondaro.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

```bash
curl -X POST "https://api.fondaro.com/properties/search?includeBranding=true" \
  -H "Authorization: Bearer $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

```bash
curl "https://api.fondaro.com/properties/<id>?includeBranding=true" \
  -H "Authorization: Bearer $FONDARO_API_KEY"
```

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

### 4. Location menu and filter options

```bash
curl "https://api.fondaro.com/properties/stats/aggregations?filterByOrganization=true" \
  -H "Authorization: Bearer $FONDARO_API_KEY"
curl "https://api.fondaro.com/properties/stats/aggregations?q=sierra" \
  -H "Authorization: Bearer $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](https://www.fondaro.com/docs/api-reference.md) 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 [Integration reporting](https://www.fondaro.com/docs/api/integrations.md)).

### 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.

Source: https://www.fondaro.com/docs/api/ai-builders