Property data in your product · Use case

How do I resolve a portal or agency ad id to the property it belongs to?

Send the advertisement ids you hold to POST /api/v1/properties/match-by-listings in Casafari's Property Sourcing REST API. Casafari's property graph recognises the same property advertised by several agencies and portals as one record. The operation returns that single property, which you then fetch in full, with every source and its history, by property id.

Products: References, Property Sourcing

#Short answer

Casafari collects advertisements from agency websites and portals in 16 countries. It structures and cleans them, then deduplicates them: the same property, advertised by several agencies and portals, is recognised as one. Every advertisement of that property is merged into one record with its full history.

POST /api/v1/properties/match-by-listings takes the ad ids you hold and returns the property they belong to. Your feed, CRM or statistics can then count each property once. Background: The property graph.

#Steps

First sign in with POST /login (email and password). Send Authorization: Bearer <access_token> on each call below.

#Check the sources the graph is built from: GET /api/v1/references/sources

1. Call GET /api/v1/references/sources. It returns the sources the graph is built from. Confirm that the portals and agency websites your ids come from are among them.

#Send your ids: POST /api/v1/properties/match-by-listings with listing_ids

2. Send the ad ids in the listing_ids array. The operation resolves them to the property they belong to.

#Fetch the full record: GET /api/v1/properties/search/{property_id}

3. Call GET /api/v1/properties/search/{property_id} with the returned property id. The record holds the property, its linked advertisements, agencies and agents, and its price and status history.

#Example

A portal team in Valencia receives three ads for what looks like the same flat: two from portals and one from an agency website.

POST https://api.casafari.com/api/v1/properties/match-by-listings
Authorization: Bearer <access_token>
Content-Type: application/json

{ "listing_ids": ["<ad id 1>", "<ad id 2>", "<ad id 3>"] }

If the graph recognises the three ads as one flat, all three resolve to one property id. Fetch that id to read the full record. Your product then shows one flat, not three. The exact response schema is on the reference page.

#How to read the result

Treat the property id as the key in your own system. Store it next to each ad id you receive. Two ads with the same property id are the same home.

#primary_listing_id and the linked advertisements

In Casafari property records, primary_listing_id is the primary ad id chosen after matching into the property. The other advertisements stay linked to the same record.

• Use the property id for counting.
• Use primary_listing_id where an operation asks for primary ad ids, such as primary_listing_ids in POST /api/v1/properties/smart-links.
• Property records may also carry listing_urls, the URLs of the advertisements, and ref_numbers, the agencies' reference numbers.

#sale_active_listings_count and rent_active_listings_count

These fields give the number of active advertisements for the property on the sales market and on the rental market. A value above one means several agencies or portals offer the same home at once.

That supports two decisions:

• Show the property once, with a note that several agencies offer it.
• Discount it when you measure supply.

Check the fetch operation's reference page for the exact fields it returns.

#Limits

Property Sourcing and References are REST operations for Casafari client accounts. They are not offered over MCP. For Property Sourcing, self-serve access for new users is coming soon.

The sources give no figures for pricing, quotas, rate limits, refresh frequency or SLAs. Ask Casafari at https://www.casafari.com/.

#Ids must come from sources in the graph

Only ads from sources Casafari collects can be resolved. Check GET /api/v1/references/sources first. An ad that never appeared in those sources has no property to resolve to. The fields of the advertisement entity are listed in Data Export at /docs/data-export/listing.

#Client account only

You need a Casafari client account with REST access. An assistant asked "are these three ads the same flat?" over the Casafari MCP server cannot answer from Property Sourcing. Your code or a REST-enabled agent calls the operation. See Why does Casafari count properties and not advertisements? and What is the Casafari property graph?.

#Questions

Related: Resolve client-forwarded links to one property record

All use cases