# Initialize an AI Builder session (v2)

> **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).

`POST https://api.casafari.com/api/v2/comparables/ai-builder`

[Comparables & Valuation](/docs/comparables-valuation) · [REST API](/docs/rest/comparables-valuation). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token).

Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#comparables-valuation).

## Description

Initializes an AI Builder session from a saved CMA (valuation) and returns
the generated report ID along with the URL of the AI Builder session.

## Request body

Content type `application/json`. Optional. Type: `object`.

- `valuation_id` (integer, required): ID of the saved CMA to build the session from.
- `agent` (object, optional, nullable): Agent data to display in the Builder.
  - `first_name` (string, required): First name of the agent displayed in the Builder.
  - `last_name` (string, optional, nullable): Last name of the agent displayed in the Builder.
  - `shop_name` (string, optional, nullable): Name of the agency or brokerage displayed alongside the agent information.
  - `photo_url` (string (uri), optional, nullable): URL to the profile picture of the agent. pattern `^(?:[a-z0-9.+-]*)://(?:[^\s:@/]+(?::[^\s:@/]*)?@)?(?:(?:0|25[0-5]|2[0-4][0-9]|1[0-9]?[0-9]?|[1-9][0-9]?)(?:\.(?:0|25[0-5]|2[0-4][0-9]|1[0-9]?[0-9]?|[1-9][0-9]?)){3}|\[[0-9a-f:.]+\]|([a-z¡-￿0-9](?:[a-z¡-￿0-9-]{0,61}[a-z¡-￿0-9])?(?:\.(?!-)[a-z¡-￿0-9-]{1,63}(?<!-))*\.(?!-)(?:[a-z¡-￿-]{2,63}|xn--[a-z0-9]{1,59})(?<!-)\.?|localhost))(?::[0-9]{1,5})?(?:[/?#][^\s]*)?\z`.
  - `email` (string (email), optional, nullable): Agent's email address displayed in the Builder and available for client contact.
  - `phone` (string, optional, nullable): Phone number of the agent.
  - `whatsapp` (string, optional, nullable): Agent's WhatsApp phone number displayed as a contact option. Include the country code.
  - `instagram` (string, optional, nullable): Agent's Instagram username or profile identifier displayed in the Builder.
  - `telegram` (string, optional, nullable): Agent's Telegram username displayed in the Builder.
  - `agent_webpage` (string (uri), optional, nullable): Public URL of the agent's personal or professional webpage. pattern `^(?:[a-z0-9.+-]*)://(?:[^\s:@/]+(?::[^\s:@/]*)?@)?(?:(?:0|25[0-5]|2[0-4][0-9]|1[0-9]?[0-9]?|[1-9][0-9]?)(?:\.(?:0|25[0-5]|2[0-4][0-9]|1[0-9]?[0-9]?|[1-9][0-9]?)){3}|\[[0-9a-f:.]+\]|([a-z¡-￿0-9](?:[a-z¡-￿0-9-]{0,61}[a-z¡-￿0-9])?(?:\.(?!-)[a-z¡-￿0-9-]{1,63}(?<!-))*\.(?!-)(?:[a-z¡-￿-]{2,63}|xn--[a-z0-9]{1,59})(?<!-)\.?|localhost))(?::[0-9]{1,5})?(?:[/?#][^\s]*)?\z`.
  - `agent_bio` (string, optional, nullable): Short biography or description of the agent. Displayed in the Builder only if the `photo_url` field is provided in the request.
- `language` (string, optional): Language of the Builder session. Values: `en`, `es`, `pt`. default "en".
- `external_ref` (string, optional, nullable)

## Example request

Placeholders only: replace the token and the values with your own.

```bash
curl -X POST "https://api.casafari.com/api/v2/comparables/ai-builder" \
  -H "Authorization: Bearer $CASAFARI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "valuation_id": 1,
  "agent": {
    "first_name": "John",
    "last_name": "Doe",
    "shop_name": "Example Realty",
    "photo_url": "https://example.com/photo.jpg",
    "email": "john.doe@example.com",
    "phone": "+351912345678",
    "whatsapp": "+351912345678",
    "instagram": "example_agent",
    "telegram": "example_agent",
    "agent_webpage": "https://example.com/agent-page",
    "agent_bio": "Experienced real estate agent."
  },
  "language": "en",
  "external_ref": "CRM-12345"
}'
```

## Responses

### 200 OK

Type: `object`.

- `id` (string, required): ID of the initialized AI Builder session.
- `url` (string, required): URL of the initialized AI Builder session.

Example from the API description:

```json
{
  "id": "6a43a32841b3e35c735b9053",
  "url": "https://www.casafari.com/market-report/valuation/builder/6a43a32841b3e35c735b9053"
}
```

### 401 Unauthorized

Type: `object`.

- `detail` (string, optional): Description of the error encountered.

### 403 Forbidden

Type: `object`.

- `detail` (string, optional): Description of the error encountered.

### 404 Not Found

Type: `object`.

- `errors` (object, optional): Description of the errors encountered.

## Questions about this

- [What does Comparables & Valuation do?](/docs/faq/what-is-comparables-valuation)
- [Which tools exist only over MCP, and which operations only over REST?](/docs/faq/mcp-only-and-rest-only)