Matchai Docs

Decline a requestComing soon

Declines a requested appointment. The person who asked is told.

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

Coming soon. Declines a requested appointment. The person who asked is told.

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

Path Parameters

appointment_id*string

Appointment id.

Length1 <= length <= 64

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
note?string

A short note shown to the other people.

Lengthlength <= 500

Response Body

The declined appointment.

application/json
  1. response
id*string

Appointment id.

Length1 <= length <= 64
title?|

Title. When null, Matchai shows one built from the type and the listing.

type*AppointmentType
Value in"property_viewing""open_house""virtual_tour""walkthrough""client_consultation""client_followup""offer_review""negotiation_meeting""contract_review""contract_signing""contract_amendment""closing_meeting""key_exchange""inspection""environmental_inspection""move_in_inspection""move_out_inspection""appraisal""work_estimation""surveying""title_search""mortgage_meeting""insurance_consultation""legal_consultation""escrow_meeting""marketing_photoshoot""staging_consultation""renovation_consultation""relocation_consultation""zoning_consultation""architectural_review""construction_update""developer_meeting""hoa_meeting""property_management_meeting""tenant_screening""utility_setup""status_update""team_meeting"
status*AppointmentStatus

requested: waiting for the host’s answer. confirmed: booked. reschedule_pending: a new time was proposed and waits for an answer.

Value in"requested""confirmed""reschedule_pending""completed""cancelled""declined""no_show"
starts_at*string

Start, with the UTC offset of timezone.

Formatdate-time
ends_at*string

End.

Formatdate-time
duration_minutes*integer

Length.

Range5 <= value <= 480
timezone*string

IANA time zone of the appointment.

location*
host*
participants*array<>

Everyone invited except the host.

listing_ids*array<>

Listings it is about.

project_id?|

Project it belongs to.

Length1 <= length <= 64
conversation_id?|

Conversation it was arranged in.

Length1 <= length <= 64
notes?|

Notes every participant sees.

internal_notes?|

Notes only you see.

source*string
Value in"listing""direct""project""assistant""api"
proposed_starts_at?|

For reschedule_pending: the proposed new start.

Formatdate-time
requested_at?|

When it was requested.

Formatdate-time
created_at*string

Created.

Formatdate-time
updated_at*string

Last changed.

Formatdate-time
Example Request
curl -X POST 'https://api.matchai.co/v1/appointments/string/decline' \  -H 'Idempotency-Key: 6f1d3c2a-0b7e-4f5a-9c8d-1e2f3a4b5c6d' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "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"}