Search

POST /properties/search searches Fondaro listings: your own in any status, and the active listings of every agency on the Fondaro network. It combines ranked free text, structured filters, map areas, sorting and cursor pages. To search Resales Online, Zoddak, Inmobalia or property sites, use Property sources.

Needs the properties:read scope. Send the key as Authorization: Bearer <key>; X-API-Key is still accepted. Every body field is optional: {} returns the newest active network listings.

Search listings

POST /properties/search

curl -X POST https://api.fondaro.com/properties/search \  -H "Authorization: Bearer fondaro_pk_abc123" \  -H "Content-Type: application/json" \  -d '{    "query": "villa \"sea views\" -golf",    "city": ["Marbella", "Benahavís"],    "price": { "min": 500000, "max": 2000000 },    "bedrooms": { "min": 3 },    "cursor": "*",    "limit": 20  }'

{  "results": [    {      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",      "referenceNumber": "FDR-7KQ2MX9A",      "listingType": "sale",      "propertyCategory": "residential",      "propertyType": "house_detached",      "city": "Marbella",      "countryCode": "ES",      "price": 1250000,      "currency": "EUR",      "bedrooms": 4,      "bathrooms": 3,      "livingArea": 320,      "status": "active"    }  ],  "total": 142,  "nextCursor": "eyJ2IjoxLCJpdiI6Ii4uLiJ9"}

Choose whose listings

partners and followed are dashboard-only scopes; an API key gets 400 (PROPERTY_FILTER_UNSUPPORTED).

With no scope, asking for any non-active status makes the search own. These combinations are refused, so an own-listings request never turns into a network search:

Another agency's listing comes back with everything except its private commission, viewingInstructions and import-only additionalFeatures keys. It keeps the street address, postcode, exact coordinates and sharedCommission (what the agency offers a collaborating agency). With includeBranding=true, its agent card has the agent's name, photo and title, plus email and phone numbers when that agent shares their contact with the network. Read sharedCommissionNotes with GET /properties/:id.

Search by text

query takes web-search syntax and searches each listing's reference, title, town, community, region, postcode, type, description (every translation), amenities and street address. Accents and case are ignored, and English words match their other forms (villas finds villa).

Numbers are plain words: 3 bedrooms under 500000 is not read as filters. With a query and no sort, results are ranked by relevance (an exact reference first, then reference and title, then place and type, then description and amenities).

Filter

An unknown enum value is a 400 naming the field. An agentId that is not on your roster is a 400 (PROPERTY_FILTER_VALUE_INVALID).

Features. A list of 1 to 30 slugs from the amenity list returns listings with every one:

{ "features": ["pool", "sea_view", "gated_complex"] }

The object form takes hasPool, hasSeaView, hasGarage, hasTerrace, hasGarden, hasAirConditioning, hasLift and isFurnished: true requires the feature, false excludes it. isFurnished: true matches partly and fully furnished listings.

Search a map area

Send at most one shape. If several arrive, boundingBox wins, then polygon, then location.

A boundingBox search returns up to 1,000 rows per page and no total.

Sort

{ "sort": [{ "field": "price", "order": "asc" }] }

Fields: relevance, price, createdAt, updatedAt, publishedAt, bedrooms, bathrooms, livingArea, plotArea, commission, yearBuilt, city, countryCode, referenceNumber, status, propertyType, propertyCategory, listingType. order is asc or desc (default desc). The older sortBy and sortOrder fields still work.

With no sort, a search with query is ordered by relevance and one without by most recently published. relevance cannot be combined with another field. Ties always break on the listing id, so the order is stable.

Commission is private. Another agency's commission never selects or orders its listings. With no scope, a commission range matches only your listings, and a commission sort puts other agencies' listings after yours. Compare offers with sharedCommission instead.

Page through results

Cursor (recommended). Send "cursor": "*" for the first page, then the same body with each response's nextCursor. Listings published while you page never repeat or shift a page.

Only the first page carries total: exact up to 10,000, beyond that 10000 with totalIsLowerBound: true. Whether more exist is nextCursor, never a comparison with total. A cursor is bound to your organization, scope and criteria and lasts 30 minutes; anything else is a 400 (PROPERTY_CURSOR_INVALID).

Page numbers. Without cursor, send page (from 1) and limit; every page carries the exact total. page and cursor together are a 400.

Price histogram

Add priceDistribution to also get a histogram of every match, counted with all filters except price, so a price slider can show what lies either side.

{  "priceDistribution": {    "interval": 50000,    "minPrice": 200000,    "maxPrice": 5000000,    "buckets": [{ "key": 200000, "count": 5 }, { "key": 250000, "count": 12 }]  }}

Response fields

What Ask Fondaro can do that the API cannot

Ask Fondaro searches properties with the same engine, but a few things differ from the routes with an API key. The assistant's tools are listed under MCP server. The key routes are this page's POST /properties/search and, for other sources, POST /property-sources/{source}/search on Property sources.

The daily allowance for property sites is shared with the assistant and the dashboard. The existing POST /property-sources/{source}/search answers a used-up allowance with 400 and PROPERTY_PORTAL_QUOTA_EXHAUSTED; the /v1 routes answer 429 with DAILY_LIMIT_REACHED.

Errors