# Immobiliare.it API

> Every Immobiliare.it endpoint on Cotlet: inputs, JSON Schema, cURL, Python and Node.js examples and an example response for each call.

Source: https://cotlet.dev/docs/api/immobiliare

Docs sections: [Get started](https://cotlet.dev/docs.md) · [REST API](https://cotlet.dev/docs/api.md) · [MCP](https://cotlet.dev/docs/mcp.md) · [SDKs & CLI](https://cotlet.dev/docs/sdks.md) · [Integrations](https://cotlet.dev/docs/integrations.md)

12 endpoints for Immobiliare.it. Each one is a POST with a JSON body, called with your API key.

- Base URL: `https://cotlet.dev/api/v1/immobiliare`
- Connects with: Your own Immobiliare.it account (email or social sign-in), as a private advertiser or a house hunter
- Integration page: https://cotlet.dev/integrations/immobiliare-api-mcp-server

## Endpoints

| Endpoint | Access | Description |
|---|---|---|
| `list_listings` | read | Your Published listings with contract, price, address, visibility and number of views. |
| `get_listing` | read | Full listing: category, type, contract, address, characteristics, price, description, photos, floor plans and URL. |
| `list_conversations` | read | Conversations in Messages, with the listing, the other person, the last message and any visit request. |
| `get_conversation` | read | Every message in a conversation, plus the visit request details: in person or remote, days and time slots. |
| `list_saved_listings` | read | Listings you saved with the heart icon, your notes on them, and whether they were removed. |
| `save_search` | write | Save a search by name to get an email or notification for every new matching listing. |
| `create_listing` | write | Post a new listing with free BASE visibility. It goes live after the editorial review, up to 48 hours. |
| `update_listing` | write | Change fields of one of your listings, as with Edit this listing. |
| `delete_listing` | write | Remove one of your listings from the portal for good. |
| `reply_to_conversation` | write | Send a reply as you in a Messages conversation. |
| `contact_advertiser` | write | Send a first message to whoever posted a listing; the conversation then lives in Messages. |
| `request_visit` | write | Ask the advertiser for a viewing. Not a booking: they contact you to confirm. |

## List listings

`POST https://cotlet.dev/api/v1/immobiliare/list_listings`

Access: read.

Returns the listings in your Published listings, with the number of views the portal shows for each. Filter by sale or rent. Pass next_cursor back as cursor for the next page. Use listing_id from each item in the other tools.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `contract` | enum | no | sale, rent or all. Default: all. |
| `limit` | integer | no | 1 to 100. Default: 50. |
| `cursor` | string | no | Next page cursor from the previous call. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/immobiliare/list_listings \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contract":"all","limit":50}'
```

**Python**

```python
result = client.call("immobiliare", "list_listings", {"contract":"all","limit":50})
```

**Node.js**

```js
const result = await cotlet.call('immobiliare', 'list_listings', {"contract":"all","limit":50});
```

**CLI**

```bash
cotlet call immobiliare list_listings --data '{"contract":"all","limit":50}'
```

### Example response

```json
{
  "listings": [
    {
      "listing_id": "118734552",
      "title": "Two-room flat, Bologna",
      "contract": "sale",
      "price": 239000,
      "address": "Via Example 5, Bologna",
      "visibility": "BASE",
      "views": 412,
      "url": "https://www.immobiliare.it/annunci/118734552/"
    },
    {
      "listing_id": "118790021",
      "title": "Studio, Milano",
      "contract": "rent",
      "price": 950,
      "address": "Via Example 10, Milano",
      "visibility": "BASE",
      "views": 96,
      "url": "https://www.immobiliare.it/annunci/118790021/"
    }
  ],
  "next_cursor": null
}
```

## Get listing

`POST https://cotlet.dev/api/v1/immobiliare/get_listing`

Access: read.

Returns one listing as the portal shows it. Works for your own listings and for any public listing, so your agent can read a flat before it asks for a visit.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `listing_id` | string | yes | Your listing ID from list_listings, or any public listing ID. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/immobiliare/get_listing \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listing_id":"listing_8c41d2"}'
```

**Python**

```python
result = client.call("immobiliare", "get_listing", {"listing_id":"listing_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('immobiliare', 'get_listing', {"listing_id":"listing_8c41d2"});
```

**CLI**

```bash
cotlet call immobiliare get_listing --data '{"listing_id":"listing_8c41d2"}'
```

### Example response

```json
{
  "listing_id": "118734552",
  "category": "residential",
  "property_type": "apartment",
  "contract": "sale",
  "price": 239000,
  "address": "Via Example 5, Bologna",
  "characteristics": {
    "surface_m2": 68,
    "rooms": 2,
    "bathrooms": 1,
    "floor": 2
  },
  "description": "Bright two-room flat near the centre.",
  "photo_count": 12,
  "url": "https://www.immobiliare.it/annunci/118734552/"
}
```

## List conversations

`POST https://cotlet.dev/api/v1/immobiliare/list_conversations`

Access: read.

Lists conversations in Messages, most recent first. Filter by listing_id to see only the people who wrote about one listing. Each item flags whether it has a visit request. Pass next_cursor back as cursor for the next page.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `listing_id` | string | no | Only conversations about this listing. |
| `limit` | integer | no | 1 to 100. Default: 50. |
| `cursor` | string | no | Next page cursor from the previous call. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/immobiliare/list_conversations \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("immobiliare", "list_conversations")
```

**Node.js**

```js
const result = await cotlet.call('immobiliare', 'list_conversations');
```

**CLI**

```bash
cotlet call immobiliare list_conversations
```

### Example response

```json
{
  "conversations": [
    {
      "conversation_id": "c_58210934",
      "listing_id": "118734552",
      "with": "Marco R.",
      "last_message": "Is the flat still available?",
      "last_message_at": "2026-10-10T15:10:00+02:00",
      "has_visit_request": true
    }
  ],
  "next_cursor": null
}
```

## Get conversation

`POST https://cotlet.dev/api/v1/immobiliare/get_conversation`

Access: read.

Returns all messages of one conversation, oldest first, so your agent reads the thread in order. If the person asked for a visit, the request shows the mode, the days and the time slots they offered.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `conversation_id` | string | yes | Conversation ID from list_conversations. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/immobiliare/get_conversation \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id":"conversation_8c41d2"}'
```

**Python**

```python
result = client.call("immobiliare", "get_conversation", {"conversation_id":"conversation_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('immobiliare', 'get_conversation', {"conversation_id":"conversation_8c41d2"});
```

**CLI**

```bash
cotlet call immobiliare get_conversation --data '{"conversation_id":"conversation_8c41d2"}'
```

### Example response

```json
{
  "conversation_id": "c_58210934",
  "listing_id": "118734552",
  "messages": [
    {
      "message_id": "m_903114100",
      "from": "them",
      "body": "Is the flat still available?",
      "sent_at": "2026-10-10T15:10:00+02:00"
    }
  ],
  "visit_request": {
    "mode": "in_person",
    "days": [
      "2026-10-17"
    ],
    "time_slots": [
      "10:00-12:00"
    ]
  }
}
```

## List saved listings

`POST https://cotlet.dev/api/v1/immobiliare/list_saved_listings`

Access: read.

Returns your saved listings with the note you wrote on each and a removed flag for listings that left the portal. Use ad_id from each item with get_listing, contact_advertiser and request_visit.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `limit` | integer | no | 1 to 100. Default: 50. |
| `cursor` | string | no | Next page cursor from the previous call. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/immobiliare/list_saved_listings \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("immobiliare", "list_saved_listings")
```

**Node.js**

```js
const result = await cotlet.call('immobiliare', 'list_saved_listings');
```

**CLI**

```bash
cotlet call immobiliare list_saved_listings
```

### Example response

```json
{
  "saved": [
    {
      "ad_id": "117220481",
      "title": "Three-room flat, Torino",
      "price": 285000,
      "note": "Check the heating",
      "removed": false
    },
    {
      "ad_id": "116004417",
      "title": "Two-room flat, Torino",
      "price": 199000,
      "note": "",
      "removed": true
    }
  ],
  "next_cursor": null
}
```

## Save search

`POST https://cotlet.dev/api/v1/immobiliare/save_search`

Access: write.

Saves the filters of an Immobiliare.it results URL under a name, as the save search option does. The portal then alerts you to new matching listings. It reaches no one, and the saved search can be removed in your personal area, so it runs without asking.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | Name of the saved search. |
| `search_url` | string | yes | Immobiliare.it results URL with your filters set. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/immobiliare/save_search \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","search_url":"https://example.com"}'
```

**Python**

```python
result = client.call("immobiliare", "save_search", {"name":"Jane Doe","search_url":"https://example.com"})
```

**Node.js**

```js
const result = await cotlet.call('immobiliare', 'save_search', {"name":"Jane Doe","search_url":"https://example.com"});
```

**CLI**

```bash
cotlet call immobiliare save_search --data '{"name":"Jane Doe","search_url":"https://example.com"}'
```

### Example response

```json
{
  "name": "Torino under 300k",
  "status": "saved"
}
```

## Create listing

`POST https://cotlet.dev/api/v1/immobiliare/create_listing`

Access: write. Confirm: waits for the user's OK before it runs.

Creates a listing from the details you give and returns its ID with status in_review. The portal reviews it before it goes live, which can take up to 48 hours. Photos and floor plans are uploaded from the URLs you pass. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `category` | string | yes | Property category, e.g. residential or commercial. |
| `property_type` | string | yes | Type within the category, e.g. apartment, villa, office. |
| `contract` | enum | yes | sale or rent. |
| `address` | string | yes | Street address and town of the property. |
| `characteristics` | object | yes | Surface, rooms, bathrooms, floor and other features. |
| `price` | integer | yes | Price in EUR; monthly rent for rentals. |
| `description` | string | yes | Listing text. |
| `photo_urls` | string[] | no | Photos to upload, by URL. |
| `floor_plan_urls` | string[] | no | Floor plans to upload, by URL. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/immobiliare/create_listing \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"category","property_type":"property type","contract":"sale","address":"address","characteristics":"characteristics","price":1,"description":"description"}'
```

**Python**

```python
result = client.call("immobiliare", "create_listing", {"category":"category","property_type":"property type","contract":"sale","address":"address","characteristics":"characteristics","price":1,"description":"description"})
```

**Node.js**

```js
const result = await cotlet.call('immobiliare', 'create_listing', {"category":"category","property_type":"property type","contract":"sale","address":"address","characteristics":"characteristics","price":1,"description":"description"});
```

**CLI**

```bash
cotlet call immobiliare create_listing --data '{"category":"category","property_type":"property type","contract":"sale","address":"address","characteristics":"characteristics","price":1,"description":"description"}'
```

### Example response

```json
{
  "listing_id": "118790021",
  "status": "in_review",
  "visibility": "BASE",
  "url": "https://www.immobiliare.it/annunci/118790021/"
}
```

## Update listing

`POST https://cotlet.dev/api/v1/immobiliare/update_listing`

Access: write.

Changes only the fields you pass and returns the updated values. The listing keeps its ID and URL. It reaches no one directly and the old value goes back with one more call, so it runs without asking.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `listing_id` | string | yes | Listing ID from list_listings. |
| `fields` | object | yes | Any of price, description, characteristics, photo_urls, floor_plan_urls. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/immobiliare/update_listing \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listing_id":"listing_8c41d2","fields":"fields"}'
```

**Python**

```python
result = client.call("immobiliare", "update_listing", {"listing_id":"listing_8c41d2","fields":"fields"})
```

**Node.js**

```js
const result = await cotlet.call('immobiliare', 'update_listing', {"listing_id":"listing_8c41d2","fields":"fields"});
```

**CLI**

```bash
cotlet call immobiliare update_listing --data '{"listing_id":"listing_8c41d2","fields":"fields"}'
```

### Example response

```json
{
  "listing_id": "118734552",
  "updated": [
    "price",
    "description"
  ],
  "price": 239000,
  "status": "online"
}
```

## Delete listing

`POST https://cotlet.dev/api/v1/immobiliare/delete_listing`

Access: write. Confirm: waits for the user's OK before it runs.

Deletes the listing from the portal. It cannot be undone with another call; you would publish it again. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `listing_id` | string | yes | Listing ID from list_listings. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/immobiliare/delete_listing \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listing_id":"listing_8c41d2"}'
```

**Python**

```python
result = client.call("immobiliare", "delete_listing", {"listing_id":"listing_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('immobiliare', 'delete_listing', {"listing_id":"listing_8c41d2"});
```

**CLI**

```bash
cotlet call immobiliare delete_listing --data '{"listing_id":"listing_8c41d2"}'
```

### Example response

```json
{
  "listing_id": "118790021",
  "status": "deleted"
}
```

## Reply to conversation

`POST https://cotlet.dev/api/v1/immobiliare/reply_to_conversation`

Access: write. Confirm: waits for the user's OK before it runs.

Sends a message in an existing conversation under your name and returns its ID and time. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `conversation_id` | string | yes | Conversation ID from list_conversations. |
| `body` | string | yes | Reply text. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/immobiliare/reply_to_conversation \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id":"c_58210934","body":"Hello, the flat is still available. I can show it on Saturday at 10:00 or 11:30. Which suits you?"}'
```

**Python**

```python
result = client.call("immobiliare", "reply_to_conversation", {"conversation_id":"c_58210934","body":"Hello, the flat is still available. I can show it on Saturday at 10:00 or 11:30. Which suits you?"})
```

**Node.js**

```js
const result = await cotlet.call('immobiliare', 'reply_to_conversation', {"conversation_id":"c_58210934","body":"Hello, the flat is still available. I can show it on Saturday at 10:00 or 11:30. Which suits you?"});
```

**CLI**

```bash
cotlet call immobiliare reply_to_conversation --data '{"conversation_id":"c_58210934","body":"Hello, the flat is still available. I can show it on Saturday at 10:00 or 11:30. Which suits you?"}'
```

### Example response

```json
{
  "conversation_id": "c_58210934",
  "listing_id": "118734552",
  "message_id": "m_903114208",
  "sent_at": "2026-10-10T16:42:00+02:00",
  "status": "sent"
}
```

## Contact advertiser

`POST https://cotlet.dev/api/v1/immobiliare/contact_advertiser`

Access: write. Confirm: waits for the user's OK before it runs.

Writes to the advertiser of one public listing, as the contact form does. The conversation then appears in list_conversations. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `ad_id` | string | yes | ID of any public listing on immobiliare.it, from its URL (/annunci/{id}/). |
| `body` | string | yes | Message text. |
| `phone` | string | no | Phone number to be contacted at. Optional. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/immobiliare/contact_advertiser \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ad_id":"ad_8c41d2","body":"body"}'
```

**Python**

```python
result = client.call("immobiliare", "contact_advertiser", {"ad_id":"ad_8c41d2","body":"body"})
```

**Node.js**

```js
const result = await cotlet.call('immobiliare', 'contact_advertiser', {"ad_id":"ad_8c41d2","body":"body"});
```

**CLI**

```bash
cotlet call immobiliare contact_advertiser --data '{"ad_id":"ad_8c41d2","body":"body"}'
```

### Example response

```json
{
  "conversation_id": "c_58301177",
  "ad_id": "117220481",
  "status": "sent",
  "sent_at": "2026-10-10T17:05:00+02:00"
}
```

## Request visit

`POST https://cotlet.dev/api/v1/immobiliare/request_visit`

Access: write. Confirm: waits for the user's OK before it runs.

Sends a visit request with the mode, the days and the time slots you are free. It is a request, not a booking: the advertiser contacts you to confirm. Time slots are those the form offers. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `ad_id` | string | yes | ID of any public listing on immobiliare.it, from its URL (/annunci/{id}/). |
| `mode` | enum | yes | in_person or remote (video call with the agent). |
| `days` | string[] | yes | Days you are available, as YYYY-MM-DD. |
| `time_slots` | string[] | yes | Time slots you are available, as offered on the form. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/immobiliare/request_visit \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ad_id":"117220481","mode":"in_person","days":["2026-10-18","2026-10-19"],"time_slots":["09:00-12:00"]}'
```

**Python**

```python
result = client.call("immobiliare", "request_visit", {"ad_id":"117220481","mode":"in_person","days":["2026-10-18","2026-10-19"],"time_slots":["09:00-12:00"]})
```

**Node.js**

```js
const result = await cotlet.call('immobiliare', 'request_visit', {"ad_id":"117220481","mode":"in_person","days":["2026-10-18","2026-10-19"],"time_slots":["09:00-12:00"]});
```

**CLI**

```bash
cotlet call immobiliare request_visit --data '{"ad_id":"117220481","mode":"in_person","days":["2026-10-18","2026-10-19"],"time_slots":["09:00-12:00"]}'
```

### Example response

```json
{
  "ad_id": "118734552",
  "mode": "remote",
  "days": [
    "2026-10-19",
    "2026-10-20"
  ],
  "time_slots": [
    "18:00-19:00"
  ],
  "status": "requested"
}
```