Matchai Docs

Update a listingComing soon

Changes the fields you send and nothing else.

Coming soon. This is documented ahead of launch so you can plan your integration; it is not available yet.
PATCH
/listings/{listing_id}

Coming soon. Changes the fields you send and nothing else. Lists (highlights, neighbourhood_tags) are replaced as a whole. A published listing updates on the public web straight away, and translations of changed text are refreshed.

Scopes: listings:write

Pricing: Included with the connection.

Authorization

headerAuthorizationBearer <matchai_<base62>>

A personal API key, sent as Authorization: Bearer matchai_…. Create keys in Matchai under Settings → Connectors → Advanced (for developers). A key starts with matchai_ followed by letters and digits, carries the scopes chosen when it was created, and can be revoked at any time. Keys reach only the account that created them: to serve other professionals, use Connect with Matchai.

Scope: listings:write

Path Parameters

listing_id*string

Listing id, or its slug.

Length1 <= length <= 200

Request Body

application/json
  1. body

Only the fields you send change. To publish, unpublish or archive, use the dedicated endpoints; to move the listing to a new address, use PUT /listings/{listing_id}/address.

Properties1 <= properties
title?string

Headline.

Lengthlength <= 200
description?string

Full description. Paragraph breaks are kept.

Lengthlength <= 20000
highlights?array<>

Short selling points. Replaces the whole list.

Itemsitems <= 12
price?
transaction_types?array<>

How the property is offered.

Items1 <= items
neighbourhood?string

Neighbourhood name.

Lengthlength <= 120
neighbourhood_summary?string

Two or three sentences about the area.

Lengthlength <= 2000
neighbourhood_tags?array<>

Replaces the whole list.

Itemsitems <= 12
virtual_tour_url?|

Link to a virtual tour.

Formaturi
property?

Only the fields you send change. Bedroom and bathroom counts cannot go below the rooms listed in spaces: remove the room first, or the request returns 422 rooms_exceed_count.

availability?ListingAvailability

Where the property stands on the market.

Value in"available""sold""rented""withdrawn"

Response Body

The updated listing.

application/json
  1. response
id*string

Listing id.

Length1 <= length <= 64
slug*string

URL-friendly name, unique per professional.

url?|

Public address of the listing page. null until it is published.

Formaturi
status*ListingStatus

draft: only you see it. published: on the public web. archived: off the market; publishing it again restores it.

Value in"draft""published""archived"
availability*ListingAvailability

Where the property stands on the market.

Value in"available""sold""rented""withdrawn"
transaction_types*array<>

How the property is offered.

title?|

Headline.

description?|

Full description.

highlights*array<string>

Short selling points.

price?|null
address?|null
coordinates?|null
neighbourhood?|

Neighbourhood name.

neighbourhood_summary?|

About the area.

neighbourhood_tags?array<string>

One- or two-word descriptors of the area.

property*

The building facts. Areas are in square feet; convert square metres (1 m² = 10.7639 ft²).

virtual_tour_url?|

Link to a virtual tour.

Formaturi
cover_image_url?|

The first photo.

Formaturi
media_count*integer

Photos and videos in the gallery.

Range0 <= value
content_locale*Locale

A language Matchai publishes in: English (en-US), Québec French (fr-CA) or Spanish (es).

Value in"en-US""fr-CA""es"
owner*

Who owns a listing or a site: one professional, or a team.

sites*array<>

The Matchai Sites this listing appears on. A listing you publish is added to your own site automatically.

listed_on?|

Date it went on the market.

Formatdate
created_at*string

Created.

Formatdate-time
updated_at*string

Last changed.

Formatdate-time
Example Request
curl -X PATCH 'https://api.matchai.co/v1/listings/string' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "string",  "slug": "string",  "url": "http://example.com",  "status": "draft",  "availability": "available",  "transaction_types": [    "for_sale"  ],  "title": "string",  "description": "string",  "highlights": [    "string"  ],  "price": {    "amount": 1,    "currency": "string"  },  "address": {    "formatted": "string",    "street": "string",    "unit": "string",    "city": "string",    "region": "string",    "postal_code": "string",    "country": "string"  },  "coordinates": {    "latitude": -90,    "longitude": -180  },  "neighbourhood": "string",  "neighbourhood_summary": "string",  "neighbourhood_tags": [    "string"  ],  "property": {    "property_type": "house",    "building_type": "detached",    "categories": [      "residential"    ],    "bedrooms": 0,    "bathrooms": 0,    "living_area_sqft": 0,    "lot_size_sqft": 0,    "year_built": 1600,    "parking_spaces": 0,    "stories": 0  },  "virtual_tour_url": "http://example.com",  "cover_image_url": "http://example.com",  "media_count": 0,  "content_locale": "en-US",  "owner": {    "type": "user",    "id": "string",    "name": "string"  },  "sites": [    {      "site_id": "string",      "featured": true    }  ],  "listed_on": "2019-08-24",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}