Claro AI · Use cases

Load every match into a CRM or warehouse nightly

For data and BI engineers at retail, restaurant, coffee or fitness chains. Page every match 200 at a time within the search's 24 hours, key rows on pm_ ids, reconcile with matching, and refresh status and price history nightly.

#What is the problem?

The expansion team wants candidates in the CRM or the warehouse each morning: deduplicated, with each criterion's state, prices, areas, coordinates and location figures with their vintages, and with counts the load can be reconciled against.

#How does it work, step by step?

1. Gate the run on GET /v1/health (health): no key, cached 60 seconds, 503 with ok false when the database cannot be read. Store active_listings and the vintages with the run (on 15 October 2026 it reports 230,403 active premises). It is at Claro's own host, https://expansion.casafari.com/v1/health; whether the platform also exposes it is not published yet.
2. Run the saved search: POST /v1/claro/search (REST, tool search_premises) with criteria as data, limit set to 200 and "check": false.
3. Walk next_cursor as cursor until page shows the total ranked is reached, within the search's 24 hours; pages never repeat or skip a premises. Compare the rows loaded with matching.
4. Key rows on the opaque pm_ id. Store each criterion as three states (met, not met, not_stated) with its sentence, null location figures as unknown, and coordinates with their flag (exact, approximate, or absent).
5. For rows already in the pipeline call GET /v1/claro/premises/{id} (REST, tool get_premises) for status (whether it is still on the market) and timeline (listed_since, days_listed, first and current asking price, price cuts, change in percent, history).
6. Store what the content terms allow: excerpt and sentences, not the full text; agency_links and the agency name; Casafari thumbnail URLs from photos only.

curl -X POST https://platform.casafari.com/v1/claro/search \
  -H "Authorization: Bearer $CASAFARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"criteria": {"operation": "rent", "cities": ["madrid"], "street_level": true, "smoke_extraction": true}, "limit": 200, "check": false}'

#What do you get?

Exact counts to reconcile against, every match with its data and per-criterion state, location figures with location_sources (unit, source, vintage, when computed) when the account has location access, and the Claro-Version date in every response (dated additive changes, published with each Claro-Version).

#What are the limits?

A search lives 24 hours: finish paging inside it or run it again. check is off above 50 a page, so expect no fit verdict at 200 a page. Per-account limits on calls a minute and a day answer 429 with rate_limited (wait, retry) or quota_reached (stop until it resets); the platform's own limits answer first in problem+json (limits). Location criteria the account cannot apply are named in not_applied.

#Related use cases

• Score every premises with your own agent
• Get location figures for any point in Spain
• Keyword search from a simple form, no model
• Compare a shortlist for the committee dossier
• Claro AI FAQ