Matchai Docs

Publish a listingComing soon

Puts the listing on the public web, and on your own Matchai Site. Publishing an archived listing restores it.

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

Coming soon. Puts the listing on the public web, and on your own Matchai Site. Publishing an archived listing restores it.

Final action. When the connection is set to Ask me, this call returns 202 with an approval_url and does nothing until the account holder approves it in Matchai; Matchai then performs it exactly as sent and sends approval.resolved. When the connection is set to Allowed, it runs straight away.

Scopes: listings:publish

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:publish

Path Parameters

listing_id*string

Listing id, or its slug.

Length1 <= length <= 200

Header Parameters

Idempotency-Key?string

A unique string (a UUID works). Retrying with the same key within 24 hours returns the first response instead of acting twice. Reusing a key with a different body returns 409 idempotency_key_reused.

Length1 <= length <= 255

Response Body

The published 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 POST 'https://api.matchai.co/v1/listings/string/publish' \  -H 'Idempotency-Key: 6f1d3c2a-0b7e-4f5a-9c8d-1e2f3a4b5c6d'
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"}