REST API reference

Property Finder API

11 endpoints for Property Finder. Each one is a POST with a JSON body, called with your API key.

Base URL: https://cotlet.dev/api/v1/property-finder
Connects with: Your own PF Expert account (agency admin or agent), email and password
Integration page: Property Finder

Property Finder Endpoints
Endpoint	Access	Description
list_listings	read	Listings in your agency with status, agent, price, quality score and active upgrade.
get_listing	read	Full listing: title, description, location, specs, price, images, permit number and quality score.
get_listing_stats	read	Views and leads for one listing since a date.
list_leads	read	Leads from your listings, newest first, with contact, listing, agent and time received.
list_agents	read	Agents in your agency with their IDs and number of listings.
get_credits	read	The credit balance PF Expert shows for your agency.
create_listing	write	New draft listing in PF Expert. Nothing goes live until you publish it.
update_listing	write	Change the price, description, images, permit or agent of a listing.
publish_listing	write	Put a draft or unpublished listing live on Property Finder.
unpublish_listing	write	Take a live listing off the portal. It stays in PF Expert.
upgrade_listing	write	Apply Featured or Premium to a live listing. Uses credits.

List listings

read

POST https://cotlet.dev/api/v1/property-finder/list_listings

Returns listings of your agency, newest first. Quality score is the percentage PF Expert shows for a published listing. Pages hold up to 100 listings; pass next_cursor back as cursor for the next page.

Parameters

Parameters: list_listings
Name	Type	Description
status	enum	live, draft or unpublished. Default: live.
agent_id	string	Only listings assigned to this agent, from list_agents.
purpose	enum	sale or rent.
max_quality_score	integer	Only listings at or under this quality score, 0 to 100.
limit	integer	1 to 100. Default: 50.
cursor	string	Next page cursor from the previous call.

Request

cURL Python Node.js CLI

curl -X POST https://cotlet.dev/api/v1/property-finder/list_listings \
  -H "Authorization: Bearer $COTLET_API_KEY"

result = client.call("property-finder", "list_listings")

const result = await cotlet.call('property-finder', 'list_listings');

cotlet call property-finder list_listings

Example response

{
  "listings": [
    {
      "listing_id": "01JA7K3M9Q",
      "title": "Furnished 2BR with marina view",
      "purpose": "rent",
      "status": "live",
      "agent_id": "ag_3d91",
      "price": 145000,
      "quality_score": 88,
      "upgrade": "featured"
    },
    {
      "listing_id": "01JA8B2N4R",
      "title": "Studio near the metro",
      "purpose": "rent",
      "status": "live",
      "agent_id": "ag_77c2",
      "price": 62000,
      "quality_score": 64,
      "upgrade": null
    }
  ],
  "next_cursor": null
}

Get listing

read

POST https://cotlet.dev/api/v1/property-finder/get_listing

Returns everything PF Expert holds for one listing, including the permit number if you entered one. Use it to see why a quality score is low before you change anything. A draft has no quality score yet.

Parameters

Parameters: get_listing
Name	Type	Description
listing_id required	string	Listing ID from list_listings.

Request

cURL Python Node.js CLI

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

result = client.call("property-finder", "get_listing", {"listing_id":"listing_8c41d2"})

const result = await cotlet.call('property-finder', 'get_listing', {"listing_id":"listing_8c41d2"});

cotlet call property-finder get_listing --data '{"listing_id":"listing_8c41d2"}'

Example response

{
  "listing_id": "01JA8B2N4R",
  "title": "Studio near the metro",
  "purpose": "rent",
  "status": "live",
  "property_type": "Apartment",
  "location": "Business Bay",
  "price": 62000,
  "bedrooms": 0,
  "size_sqft": 410,
  "description": "Bright studio, close to the metro.",
  "image_urls": [
    "https://example.com/photos/studio-1.jpg"
  ],
  "permit_number": null,
  "agent_id": "ag_77c2",
  "quality_score": 64
}

Get listing stats

read

POST https://cotlet.dev/api/v1/property-finder/get_listing_stats

Returns the performance numbers PF Expert shows for one listing, from the start date to now. Call it once per listing, so keep the set small and filter with list_listings first. A listing that went live after the start date counts from its publish date.

Parameters

Parameters: get_listing_stats
Name	Type	Description
listing_id required	string	Listing ID from list_listings.
since	date	Count from this date. Default: 30 days ago.

Request

cURL Python Node.js CLI

curl -X POST https://cotlet.dev/api/v1/property-finder/get_listing_stats \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listing_id":"01JA7K3M9Q","since":"2026-10-06"}'

result = client.call("property-finder", "get_listing_stats", {"listing_id":"01JA7K3M9Q","since":"2026-10-06"})

const result = await cotlet.call('property-finder', 'get_listing_stats', {"listing_id":"01JA7K3M9Q","since":"2026-10-06"});

cotlet call property-finder get_listing_stats --data '{"listing_id":"01JA7K3M9Q","since":"2026-10-06"}'

Example response

{
  "listing_id": "01JA7K3M9Q",
  "since": "2026-09-11",
  "views": 1840,
  "leads": 0
}

List leads

read

POST https://cotlet.dev/api/v1/property-finder/list_leads

Returns leads that came in through your listings, newest first. Each lead names the listing and the agent it belongs to. Pages hold up to 100 leads; pass next_cursor back as cursor for the next page.

Parameters

Parameters: list_leads
Name	Type	Description
since	datetime	Only leads received after this time.
listing_id	string	Only leads for this listing.
agent_id	string	Only leads for this agent.
limit	integer	1 to 100. Default: 50.
cursor	string	Next page cursor from the previous call.

Request

cURL Python Node.js CLI

curl -X POST https://cotlet.dev/api/v1/property-finder/list_leads \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"since":"2026-10-11T08:00:00+04:00","limit":100}'

result = client.call("property-finder", "list_leads", {"since":"2026-10-11T08:00:00+04:00","limit":100})

const result = await cotlet.call('property-finder', 'list_leads', {"since":"2026-10-11T08:00:00+04:00","limit":100});

cotlet call property-finder list_leads --data '{"since":"2026-10-11T08:00:00+04:00","limit":100}'

Example response

{
  "leads": [
    {
      "lead_id": "ld_90f1",
      "name": "Jamie Hart",
      "phone": "+971500000000",
      "listing_id": "01JA7K3M9Q",
      "agent_id": "ag_3d91",
      "received_at": "2026-10-10T16:42:00+04:00"
    }
  ],
  "next_cursor": null
}

List agents

read

POST https://cotlet.dev/api/v1/property-finder/list_agents

Returns the agents of your agency. Use agent_id from here to assign a listing or to filter listings and leads. You see the agents your own role can see in PF Expert.

Parameters

No parameters.

Request

cURL Python Node.js CLI

curl -X POST https://cotlet.dev/api/v1/property-finder/list_agents \
  -H "Authorization: Bearer $COTLET_API_KEY"

result = client.call("property-finder", "list_agents")

const result = await cotlet.call('property-finder', 'list_agents');

cotlet call property-finder list_agents

Example response

{
  "agents": [
    {
      "agent_id": "ag_3d91",
      "name": "Sara Khan",
      "listings": 24
    },
    {
      "agent_id": "ag_77c2",
      "name": "Omar Haddad",
      "listings": 11
    }
  ]
}

Get credits

read

POST https://cotlet.dev/api/v1/property-finder/get_credits

Returns the credits available for upgrades. Check it before upgrade_listing so the agent does not plan a spend you cannot cover. It reads the balance only and spends nothing.

Parameters

No parameters.

Request

cURL Python Node.js CLI

curl -X POST https://cotlet.dev/api/v1/property-finder/get_credits \
  -H "Authorization: Bearer $COTLET_API_KEY"

result = client.call("property-finder", "get_credits")

const result = await cotlet.call('property-finder', 'get_credits');

cotlet call property-finder get_credits

Example response

{
  "credits": 2500
}

Create listing

write

POST https://cotlet.dev/api/v1/property-finder/create_listing

Saves a draft in PF Expert and returns its listing_id. The draft is visible only to you and your agency. It reaches no one and you can delete it in PF Expert, so it does not ask for confirmation. Run publish_listing to put it live.

Parameters

Parameters: create_listing
Name	Type	Description
title required	string	Listing title.
purpose required	enum	sale or rent.
property_type required	string	As in PF Expert, e.g. Apartment or Villa.
location required	string	Community or building, matched to the Property Finder location list.
price required	integer	Price as you enter it in PF Expert.
bedrooms	integer	Number of bedrooms, 0 for a studio.
bathrooms	integer	Number of bathrooms.
size_sqft	integer	Built-up area in square feet.
description	string	Listing description.
image_urls	string[]	Image URLs, first one is the cover.
permit_number	string	Permit number, where PF Expert asks for one.
agent_id	string	Assigned agent, from list_agents.

Request

cURL Python Node.js CLI

curl -X POST https://cotlet.dev/api/v1/property-finder/create_listing \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Furnished 2BR with marina view","purpose":"rent","property_type":"Apartment","location":"Dubai Marina","price":145000,"bedrooms":2,"permit_number":"7123456789","agent_id":"ag_3d91","image_urls":["https://example.com/photos/marina-2br-1.jpg"]}'

result = client.call("property-finder", "create_listing", {"title":"Furnished 2BR with marina view","purpose":"rent","property_type":"Apartment","location":"Dubai Marina","price":145000,"bedrooms":2,"permit_number":"7123456789","agent_id":"ag_3d91","image_urls":["https://example.com/photos/marina-2br-1.jpg"]})

const result = await cotlet.call('property-finder', 'create_listing', {"title":"Furnished 2BR with marina view","purpose":"rent","property_type":"Apartment","location":"Dubai Marina","price":145000,"bedrooms":2,"permit_number":"7123456789","agent_id":"ag_3d91","image_urls":["https://example.com/photos/marina-2br-1.jpg"]});

cotlet call property-finder create_listing --data '{"title":"Furnished 2BR with marina view","purpose":"rent","property_type":"Apartment","location":"Dubai Marina","price":145000,"bedrooms":2,"permit_number":"7123456789","agent_id":"ag_3d91","image_urls":["https://example.com/photos/marina-2br-1.jpg"]}'

Example response

{
  "listing_id": "01JA9C5P7T",
  "status": "draft",
  "agent_id": "ag_3d91"
}

Update listing

write Confirm

POST https://cotlet.dev/api/v1/property-finder/update_listing

Applies the fields you pass and leaves the rest as they are. Changes to a live listing are visible to buyers and renters, and PF Expert may recalculate the quality score. Returns the updated fields. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: update_listing
Name	Type	Description
listing_id required	string	Listing ID from list_listings.
fields required	object	Any of the create_listing fields.

Request

cURL Python Node.js CLI

curl -X POST https://cotlet.dev/api/v1/property-finder/update_listing \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listing_id":"01JA8B2N4R","fields":{"description":"Bright furnished studio in JLT Cluster D, two minutes from the metro, with lake view and 410 sq ft."}}'

result = client.call("property-finder", "update_listing", {"listing_id":"01JA8B2N4R","fields":{"description":"Bright furnished studio in JLT Cluster D, two minutes from the metro, with lake view and 410 sq ft."}})

const result = await cotlet.call('property-finder', 'update_listing', {"listing_id":"01JA8B2N4R","fields":{"description":"Bright furnished studio in JLT Cluster D, two minutes from the metro, with lake view and 410 sq ft."}});

cotlet call property-finder update_listing --data '{"listing_id":"01JA8B2N4R","fields":{"description":"Bright furnished studio in JLT Cluster D, two minutes from the metro, with lake view and 410 sq ft."}}'

Example response

{
  "listing_id": "01JA8B2N4R",
  "updated": [
    "description",
    "image_urls"
  ],
  "quality_score": 72
}

Publish listing

write Confirm

POST https://cotlet.dev/api/v1/property-finder/publish_listing

Publishes the listing with the listing type you choose on the Publish screen of PF Expert: standard, featured or premium. Featured and premium run for 15 days or 1 month; the options your market shows may differ. It returns the live status and the portal URL. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: publish_listing
Name	Type	Description
listing_id required	string	Listing ID from list_listings.
listing_type required	enum	standard, featured or premium.
duration	enum	15_days or 1_month for featured and premium. Standard runs 1 month.

Request

cURL Python Node.js CLI

curl -X POST https://cotlet.dev/api/v1/property-finder/publish_listing \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listing_id":"listing_8c41d2","listing_type":"standard"}'

result = client.call("property-finder", "publish_listing", {"listing_id":"listing_8c41d2","listing_type":"standard"})

const result = await cotlet.call('property-finder', 'publish_listing', {"listing_id":"listing_8c41d2","listing_type":"standard"});

cotlet call property-finder publish_listing --data '{"listing_id":"listing_8c41d2","listing_type":"standard"}'

Example response

{
  "listing_id": "01JA7K3M9Q",
  "status": "live",
  "listing_type": "standard",
  "url": "https://www.propertyfinder.ae/en/plp/rent/apartment-for-rent-dubai-dubai-marina-01JA7K3M9Q.html"
}

Unpublish listing

write Confirm

POST https://cotlet.dev/api/v1/property-finder/unpublish_listing

Removes the listing from Property Finder search and keeps it in PF Expert with status unpublished, so you can publish it again later. Leads already received stay in your leads. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: unpublish_listing
Name	Type	Description
listing_id required	string	Listing ID from list_listings.

Request

cURL Python Node.js CLI

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

result = client.call("property-finder", "unpublish_listing", {"listing_id":"listing_8c41d2"})

const result = await cotlet.call('property-finder', 'unpublish_listing', {"listing_id":"listing_8c41d2"});

cotlet call property-finder unpublish_listing --data '{"listing_id":"listing_8c41d2"}'

Example response

{
  "listing_id": "01JA8B2N4R",
  "status": "unpublished"
}

Upgrade listing

write Confirm

POST https://cotlet.dev/api/v1/property-finder/upgrade_listing

Upgrades a live listing to featured or premium for 15 days or 1 month and pays with credits. It returns the expiry date and the credits left. Spotlight is a bidding product and is not covered by this tool. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: upgrade_listing
Name	Type	Description
listing_id required	string	Listing ID from list_listings.
listing_type required	enum	featured or premium.
duration required	enum	15_days or 1_month.

Request

cURL Python Node.js CLI

curl -X POST https://cotlet.dev/api/v1/property-finder/upgrade_listing \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listing_id":"01JA7K3M9Q","listing_type":"featured","duration":"15_days"}'

result = client.call("property-finder", "upgrade_listing", {"listing_id":"01JA7K3M9Q","listing_type":"featured","duration":"15_days"})

const result = await cotlet.call('property-finder', 'upgrade_listing', {"listing_id":"01JA7K3M9Q","listing_type":"featured","duration":"15_days"});

cotlet call property-finder upgrade_listing --data '{"listing_id":"01JA7K3M9Q","listing_type":"featured","duration":"15_days"}'

Example response

{
  "listing_id": "01JA7K3M9Q",
  "status": "live",
  "listing_type": "featured",
  "expires_at": "2026-10-26T12:00:00+04:00",
  "credits_left": 2380
}

Parameters

Request

Example response

Parameters

Request

Example response

Parameters

Request

Example response

Parameters

Request

Example response

Parameters

Request

Example response

Parameters

Request

Example response

Parameters

Request

Example response

Parameters

Request

Example response

Parameters

Request

Example response

Parameters

Request

Example response

Parameters

Request

Example response

Analytics cookies