REST API reference

Immobiliare.it API

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
Immobiliare.it
Immobiliare.it 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

read

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

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

Parameters: list_listings
NameTypeDescription
contract enum sale, rent or all. Default: all.
limit integer 1 to 100. Default: 50.
cursor string Next page cursor from the previous call.

Request

cURL
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
result = client.call("immobiliare", "list_listings", {"contract":"all","limit":50})
Node.js
const result = await cotlet.call('immobiliare', 'list_listings', {"contract":"all","limit":50});
CLI
cotlet call immobiliare list_listings --data '{"contract":"all","limit":50}'

Example response

{
  "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

read

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

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

Parameters: get_listing
NameTypeDescription
listing_id required string Your listing ID from list_listings, or any public listing ID.

Request

cURL
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
result = client.call("immobiliare", "get_listing", {"listing_id":"listing_8c41d2"})
Node.js
const result = await cotlet.call('immobiliare', 'get_listing', {"listing_id":"listing_8c41d2"});
CLI
cotlet call immobiliare get_listing --data '{"listing_id":"listing_8c41d2"}'

Example response

{
  "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

read

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

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

Parameters: list_conversations
NameTypeDescription
listing_id string Only conversations about this listing.
limit integer 1 to 100. Default: 50.
cursor string Next page cursor from the previous call.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/immobiliare/list_conversations \
  -H "Authorization: Bearer $COTLET_API_KEY"
Python
result = client.call("immobiliare", "list_conversations")
Node.js
const result = await cotlet.call('immobiliare', 'list_conversations');
CLI
cotlet call immobiliare list_conversations

Example response

{
  "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

read

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

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

Parameters: get_conversation
NameTypeDescription
conversation_id required string Conversation ID from list_conversations.

Request

cURL
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
result = client.call("immobiliare", "get_conversation", {"conversation_id":"conversation_8c41d2"})
Node.js
const result = await cotlet.call('immobiliare', 'get_conversation', {"conversation_id":"conversation_8c41d2"});
CLI
cotlet call immobiliare get_conversation --data '{"conversation_id":"conversation_8c41d2"}'

Example response

{
  "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

read

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

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

Parameters: list_saved_listings
NameTypeDescription
limit integer 1 to 100. Default: 50.
cursor string Next page cursor from the previous call.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/immobiliare/list_saved_listings \
  -H "Authorization: Bearer $COTLET_API_KEY"
Python
result = client.call("immobiliare", "list_saved_listings")
Node.js
const result = await cotlet.call('immobiliare', 'list_saved_listings');
CLI
cotlet call immobiliare list_saved_listings

Example response

{
  "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
}

Create listing

write Confirm

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

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

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

Request

cURL
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
result = client.call("immobiliare", "create_listing", {"category":"category","property_type":"property type","contract":"sale","address":"address","characteristics":"characteristics","price":1,"description":"description"})
Node.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
cotlet call immobiliare create_listing --data '{"category":"category","property_type":"property type","contract":"sale","address":"address","characteristics":"characteristics","price":1,"description":"description"}'

Example response

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

Update listing

write

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

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

Parameters: update_listing
NameTypeDescription
listing_id required string Listing ID from list_listings.
fields required object Any of price, description, characteristics, photo_urls, floor_plan_urls.

Request

cURL
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
result = client.call("immobiliare", "update_listing", {"listing_id":"listing_8c41d2","fields":"fields"})
Node.js
const result = await cotlet.call('immobiliare', 'update_listing', {"listing_id":"listing_8c41d2","fields":"fields"});
CLI
cotlet call immobiliare update_listing --data '{"listing_id":"listing_8c41d2","fields":"fields"}'

Example response

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

Delete listing

write Confirm

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

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

Parameters: delete_listing
NameTypeDescription
listing_id required string Listing ID from list_listings.

Request

cURL
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
result = client.call("immobiliare", "delete_listing", {"listing_id":"listing_8c41d2"})
Node.js
const result = await cotlet.call('immobiliare', 'delete_listing', {"listing_id":"listing_8c41d2"});
CLI
cotlet call immobiliare delete_listing --data '{"listing_id":"listing_8c41d2"}'

Example response

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

Reply to conversation

write Confirm

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

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

Parameters: reply_to_conversation
NameTypeDescription
conversation_id required string Conversation ID from list_conversations.
body required string Reply text.

Request

cURL
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
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
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
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

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

Contact advertiser

write Confirm

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

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

Parameters: contact_advertiser
NameTypeDescription
ad_id required string ID of any public listing on immobiliare.it, from its URL (/annunci/{id}/).
body required string Message text.
phone string Phone number to be contacted at. Optional.

Request

cURL
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
result = client.call("immobiliare", "contact_advertiser", {"ad_id":"ad_8c41d2","body":"body"})
Node.js
const result = await cotlet.call('immobiliare', 'contact_advertiser', {"ad_id":"ad_8c41d2","body":"body"});
CLI
cotlet call immobiliare contact_advertiser --data '{"ad_id":"ad_8c41d2","body":"body"}'

Example response

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

Request visit

write Confirm

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

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

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

Request

cURL
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
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
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
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

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