Matchai Docs

Create a listing with AIComing soon

Starts AI listing creation, the same as Create listing in the app.

Coming soon. This is documented ahead of launch so you can plan your integration; it is not available yet.
POST
/listing-generations

Coming soon. Starts AI listing creation, the same as Create listing in the app. From photos and a few details, Matchai writes the title, description, highlights, neighbourhood and rooms; from a web page, it imports a listing published elsewhere. The result is always a draft. The run takes a minute or two: poll GET /listing-generations/{generation_id} or wait for listing.generation.completed. The Energy it spends grows with the number of photos.

Spends Matchai Energy. Returns 402 without doing anything when the account does not have enough Energy, or when this connection reached the Energy limit the account holder set for it.

Scopes: listings:write

Pricing: Included with the connection, and spends Matchai Energy.

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

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

Request Body

application/json
  1. body

Starts AI listing creation. photos writes a complete listing from photos and a few details. web_page imports a listing you already published elsewhere, from its address on the web.

source*string
Value in"photos""web_page"
photo_urls?array<>

For photos: the photos, in the order you want them.

Items1 <= items <= 60
document_ids?array<>

For photos: documents to read facts from, for example a seller declaration.

Itemsitems <= 5
url?string

For web_page: the page to import.

Formaturi
details?

Facts you already know. They win over anything read from the photos.

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"
team_id?string

Create the listing for a team you own or administer.

Length1 <= length <= 64

Response Body

The run has started.

application/json
  1. response

An AI listing creation run. It produces a draft listing; nothing is published.

id*string

Run id.

Length1 <= length <= 64
status*string
Value in"queued""running""succeeded""failed"
source*string
Value in"photos""web_page"
listing_id?|

The draft listing, once the run has created it.

Length1 <= length <= 64
step?|

What the run is doing now, in plain words, for example "Writing the description".

error?|null
created_at*string

Started.

Formatdate-time
completed_at?|

Finished.

Formatdate-time
Example Request
curl -X POST 'https://api.matchai.co/v1/listing-generations' \  -H 'Idempotency-Key: 6f1d3c2a-0b7e-4f5a-9c8d-1e2f3a4b5c6d' \  -H 'Content-Type: application/json' \  -d '{  "source": "photos"}'
Example Response
{  "id": "string",  "status": "queued",  "source": "photos",  "listing_id": "string",  "step": "string",  "error": {    "code": "string",    "message": "string"  },  "created_at": "2019-08-24T14:15:22Z",  "completed_at": "2019-08-24T14:15:22Z"}