Matchai Docs

Request a visit for a website visitorComing soon

Records a visit request made on your website.

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

Coming soon. Records a visit request made on your website. The visitor becomes a lead, and the request waits in Matchai for the account holder to confirm or decline it; the visitor hears back from them. Returns 409 slot_unavailable when the time was taken in the meantime.

Scopes: calendar:write and contacts: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: calendar:write, contacts:write

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

Request Body

application/json
  1. body

A visit request from someone on your website. It becomes a requested appointment that the account holder confirms or declines in Matchai, and the visitor is added to the contacts as a lead. Needs an email or a phone number.

visitor*|
starts_at*string

A start time from GET /professionals/{username}/booking-slots.

Formatdate-time
duration_minutes?integer

One of the listing’s visit lengths.

Range5 <= value <= 480
notes?string

What the visitor wrote.

Lengthlength <= 2000

Response Body

The request and the contact.

application/json
  1. response
appointment*
contact*

A person in your contacts. Only you (and your team, for team contacts) can see this record; the person cannot.

Example Request
curl -X POST 'https://api.matchai.co/v1/listings/string/viewing-requests' \  -H 'Idempotency-Key: 6f1d3c2a-0b7e-4f5a-9c8d-1e2f3a4b5c6d' \  -H 'Content-Type: application/json' \  -d '{  "visitor": {    "first_name": "string",    "email": null  },  "starts_at": "2019-08-24T14:15:22Z"}'
Example Response
{  "appointment": {    "id": "string",    "title": "string",    "type": "property_viewing",    "status": "requested",    "starts_at": "2019-08-24T14:15:22Z",    "ends_at": "2019-08-24T14:15:22Z",    "duration_minutes": 5,    "timezone": "string",    "location": {      "type": "in_person",      "address": {        "formatted": "string",        "street": "string",        "unit": "string",        "city": "string",        "region": "string",        "postal_code": "string",        "country": "string"      },      "url": "http://example.com",      "phone": "string",      "note": "string"    },    "host": {      "user_id": "string",      "display_name": "string",      "team_id": "string"    },    "participants": [      {        "user_id": "string",        "contact_id": "string",        "display_name": "string",        "role": "attendee",        "status": "pending"      }    ],    "listing_ids": [      "string"    ],    "project_id": "string",    "conversation_id": "string",    "notes": "string",    "internal_notes": "string",    "source": "listing",    "proposed_starts_at": "2019-08-24T14:15:22Z",    "requested_at": "2019-08-24T14:15:22Z",    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z"  },  "contact": {    "id": "string",    "type": "lead",    "first_name": "string",    "last_name": "string",    "display_name": "string",    "email": "user@example.com",    "phone": "string",    "company": "string",    "profession": "string",    "notes": "string",    "source": "listing",    "source_listing_id": "string",    "matchai_user": {      "user_id": "string",      "username": "string",      "avatar_url": "http://example.com"    },    "conversation_id": "string",    "erased": true,    "lead": {      "stage": "welcome",      "temperature": "cold",      "readiness": "exploring",      "lifecycle_stage": "new",      "score": 0,      "budget": {        "min": 0,        "max": 0,        "currency": "string"      },      "timeline": "string",      "preferences": {        "bedrooms": 0,        "bathrooms": 0,        "min_sqft": 0,        "max_sqft": 0,        "property_types": [          "string"        ],        "areas": [          "string"        ],        "features": [          "string"        ]      },      "updated_at": "2019-08-24T14:15:22Z"    },    "client": {      "converted_from_lead_at": "2019-08-24T14:15:22Z",      "property_interests": [        "string"      ],      "transactions": [        {          "type": "purchase",          "date": "2019-08-24",          "value": 0,          "listing_id": "string",          "notes": "string"        }      ],      "preferred_channel": "email"    },    "professional": {      "relationship": "peer",      "specializations": [        "string"      ],      "referral_count": 0,      "notes": "string"    },    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z"  }}