# How do I turn comparables into a client-ready CMA report?

> **Casafari is the AI agent-native real estate data intelligence platform.** The most complete property index in Europe: a deduplicated, cleaned property graph of residential and commercial property, for sale and for rent, in 16 countries. Every property is one record with its full price and market history. [How the property graph is built](/docs/property-graph).

To turn comparables into a client-ready CMA report, run `comps_get-comparables` (Comparables & Valuation) and keep its `casafari_link`, which opens the Comparative Market Analysis page, and its `valuation_id`. Casafari client accounts can then start an AI Builder session with `POST /api/v2/comparables/ai-builder` and share chosen comparables with `POST /api/v1/properties/smart-links` (BETA).

Products: [Comparables & Valuation](/docs/comparables-valuation), [Property Sourcing](/docs/property-sourcing).

## Short answer

The valuation call already returns `casafari_link`, a link to the Comparative Market Analysis page, and `valuation_id`, a persistent ID that the field description says is used to generate a Smart Link or a PDF. Over REST, Casafari client accounts turn the `valuation_id` into an AI Builder session showing the agent's details, and share selected comparables with a smart link.

## Steps

### Run `comps_get-comparables` and keep `casafari_link` and `valuation_id`

1. Call [`list_servers`](/docs/gateway/list_servers), then [`comps_get-comparables`](/docs/comparables-valuation/get-comparables) with `comparables_count`, `location_boundary`, `operation` and `comparables_types`. Store `casafari_link`, `valuation_id`, and the `primary_listing_id` of each comparable you may want to show.

### Start an AI Builder session with `POST /api/v2/comparables/ai-builder` (`valuation_id`, `agent`, `language`, `external_ref`)

2. Sign in to the REST API at `https://api.casafari.com` with `POST /login` and send the access token as a bearer token.
3. Call [`POST /api/v2/comparables/ai-builder`](/docs/rest/comparables-valuation/initialize-an-ai-builder-session-v2) with `valuation_id` (the ID of the saved CMA to build the session from), `agent` (agent data to display in the Builder), `language` (the session's language) and `external_ref`. The operation page documents each field's exact format.

### Create a smart link with `POST /api/v1/properties/smart-links` from `primary_listing_id` values of the comparables you want to show

4. Call [`POST /api/v1/properties/smart-links`](/docs/rest/property-sourcing/create-a-smart-link-beta-v1) with `primary_listing_ids` set to the `primary_listing_id` values you chose. The operation also takes `settings`, `user` and `company`, documented on its page.

## Example

An agent asks their assistant: *"Value my client's 3-bedroom flat near Avenida da Liberdade, Lisbon, using comparables within 1 km, and give me the CMA link."* The assistant calls `list_servers` and `comps_get-comparables`, quotes the fair market price with its range, and returns `casafari_link` and `valuation_id`.

The agency's application, signed in over REST, then starts the AI Builder session:

```json
{
  "valuation_id": "<valuation_id from comps_get-comparables>",
  "language": "<session language>",
  "external_ref": "<your CRM reference>"
}
```

and creates a smart link for the comparables worth showing the seller:

```json
{
  "primary_listing_ids": ["<primary_listing_id>", "<primary_listing_id>"]
}
```

The shape of each response is documented on the operation pages.

## How to read the result

### `valuation_id` is persistent and expires in a year

Store it with the client record: within a year you can build the AI Builder session from it without re-running the valuation. After that, run a new valuation.

### Which comparables to include: `similarity_score` and `is_outlier`

Show the seller the comparables with the highest `similarity_score` (0 to 1), a short `distance`, and `is_outlier` false. `sale_price_last_change` and `sale_status` help explain the story: a property that cut its price, or one already sold, is persuasive evidence. Each comparable is one property in Casafari's deduplicated graph, so the same home never appears twice.

## Limits

`comps_get-comparables` is available to Casafari clients with MCP access, using their Casafari account; self-serve access for new users is coming soon. `POST /api/v2/comparables/ai-builder` and `POST /api/v1/properties/smart-links` are REST operations for Casafari client accounts; Property Sourcing as a whole is REST only. Prices, quotas and rate limits are not published in these docs; ask [Casafari](https://www.casafari.com/). More examples: [How do I value a home or find comparables?](/docs/faq/example-valuation)

### The smart link operation is marked BETA

Its name is "Create a smart link (BETA)"; plan for changes to its behaviour.

### AI Builder and smart links are REST only, not MCP

An AI assistant connected to the Casafari MCP server can produce the valuation and the `casafari_link`, but not the AI Builder session or the smart link. [MCP vs REST API](/docs/parity) lists what exists where.

## Questions

### How long does a valuation_id stay valid?

A `valuation_id` returned by `comps_get-comparables` is persistent and expires in a year, according to the field's description. Within that time you can use it to start an AI Builder session with `POST /api/v2/comparables/ai-builder`. After it expires, run a new valuation, which also gives you comparables and estimates that reflect the market on the new date.

### Can an AI assistant create the smart link for me?

Not over MCP: smart links exist only as the REST operation `POST /api/v1/properties/smart-links`, marked BETA and available to Casafari client accounts. An assistant can run the valuation with `comps_get-comparables` and pick the `primary_listing_id` values, but the smart link call must come from an application or agent that signs in to the REST API with `POST /login`.

### Can I brand the report with my agency's details?

Partly: `POST /api/v2/comparables/ai-builder` takes an `agent` object, described as agent data to display in the Builder, plus `language` and `external_ref`, and the smart link operation takes `settings`, `user` and `company`. The exact fields inside these objects are on each operation's page; Casafari's documentation here describes no further branding options.

### Does the CMA page update when prices change?

Casafari's documentation does not say whether the Comparative Market Analysis page behind `casafari_link` updates when prices change. The comparables carry their state at the time of the call, including `sale_price_last_change` and `sale_status`. To present current figures, run `comps_get-comparables` again shortly before sending the report, and state the date of the valuation.

All use cases: [Use cases](/docs/use-cases#valuation).