---
title: "Viewing Appointments"
url: "https://real-estate-agency.apim.eu/apis/viewing-appointments/versions/70b37971-1301-4569-bd6c-e68e8b19e7e2"
---

# Viewing Appointments

OpenAPI specification document.

```json
{"openapi":"3.0.3","info":{"title":"Viewing Appointments","version":"1.0.0","description":"Schedules individual and group viewings, manages confirmations and\ncancellations, and collects feedback after the appointment.\n\nThe API supports two models: **fixed appointments**, to which you invite\nleads, and **availability windows**, from which leads pick their own slot.\nBoth can be mixed per property.\n","contact":{"name":"API Support - Real Estate Agency","email":"api-support@realestateagency.example"}},"servers":[{"url":"https://api.realestateagency.example/v1","description":"Production"},{"url":"https://sandbox.api.realestateagency.example/v1","description":"Sandbox"}],"tags":[{"name":"Appointments"},{"name":"Availability"},{"name":"Feedback"}],"security":[{"apiKey":[]}],"paths":{"/appointments":{"get":{"tags":["Appointments"],"summary":"List appointments","operationId":"listAppointments","parameters":[{"name":"property_id","in":"query","schema":{"type":"string","example":"prop_8f2c1a"}},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/AppointmentStatus"}}],"responses":{"200":{"description":"Results list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Appointment"}},"page":{"$ref":"#/components/schemas/Page"}}}}}},"401":{"$ref":"#/components/responses/NotAuthenticated"}}},"post":{"tags":["Appointments"],"summary":"Create an appointment","operationId":"createAppointment","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppointmentInput"},"examples":{"single":{"summary":"Individual viewing","value":{"property_id":"prop_8f2c1a","type":"individual","start":"2026-09-03T16:00:00+02:00","duration_minutes":30,"meeting_point":"In front of the main entrance, 148 Elm Street"}},"group":{"summary":"Group viewing with twelve slots","value":{"property_id":"prop_8f2c1a","type":"group","start":"2026-09-05T11:00:00+02:00","duration_minutes":60,"slots":12}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Appointment"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"409":{"description":"Time conflict with an existing appointment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"conflict","message":"There is already an appointment for this property at that time.","details":[{"field":"start","reason":"overlap"}]}}}}}}},"/appointments/{appointmentId}":{"parameters":[{"name":"appointmentId","in":"path","required":true,"schema":{"type":"string","example":"appt_9a44"}}],"get":{"tags":["Appointments"],"summary":"Retrieve an appointment","operationId":"getAppointment","responses":{"200":{"description":"Appointment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Appointment"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Appointments"],"summary":"Reschedule or update an appointment","description":"When the start time changes, all confirmed attendees are notified automatically.","operationId":"updateAppointment","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppointmentInput"},"example":{"start":"2026-09-03T17:30:00+02:00"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Appointment"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["Appointments"],"summary":"Cancel an appointment","operationId":"cancelAppointment","responses":{"204":{"description":"Cancelled; attendees have been notified"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/appointments/{appointmentId}/confirmations":{"parameters":[{"name":"appointmentId","in":"path","required":true,"schema":{"type":"string","example":"appt_9a44"}}],"get":{"tags":["Appointments"],"summary":"List confirmations for an appointment","operationId":"listConfirmations","responses":{"200":{"description":"Attendee list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Confirmation"}},"open_slots":{"type":"integer","example":4}}}}}}}},"post":{"tags":["Appointments"],"summary":"Confirm a lead's attendance","description":"If the appointment is fully booked, the lead is placed on the waitlist instead.","operationId":"createConfirmation","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["lead_id"],"properties":{"lead_id":{"type":"string","example":"lead_71ab"},"guests":{"type":"integer","minimum":0,"maximum":3,"default":0}}}}}},"responses":{"201":{"description":"Confirmation recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Confirmation"}}}},"409":{"description":"Lead has already confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/availability":{"get":{"tags":["Availability"],"summary":"Query open time slots","description":"Returns bookable slots for a property, derived from the responsible\nagent's stored working hours minus appointments already booked.\n","operationId":"getAvailability","parameters":[{"name":"property_id","in":"query","required":true,"schema":{"type":"string","example":"prop_8f2c1a"}},{"name":"from","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":true,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Time slots","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TimeSlot"}}}},"example":{"data":[{"start":"2026-09-03T16:00:00+02:00","end":"2026-09-03T16:30:00+02:00","bookable":true},{"start":"2026-09-03T16:30:00+02:00","end":"2026-09-03T17:00:00+02:00","bookable":false}]}}}}}}},"/appointments/{appointmentId}/feedback":{"parameters":[{"name":"appointmentId","in":"path","required":true,"schema":{"type":"string","example":"appt_9a44"}}],"post":{"tags":["Feedback"],"summary":"Record feedback after a viewing","description":"The basis for reporting back to the property owner.","operationId":"createFeedback","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["lead_id","interest"],"properties":{"lead_id":{"type":"string","example":"lead_71ab"},"interest":{"type":"string","enum":["intent_to_buy","still_considering","not_interested"]},"price_assessment":{"type":"string","enum":["fair","too_high","too_low"]},"comment":{"type":"string","maxLength":1000}}}}}},"responses":{"201":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Feedback"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"apikey","description":"Every call carries an API key in the `apikey` header. You generate the\nkey in the Real Estate portal under \"My Apps\"; it's shown exactly once.\n\nEach key has the scopes it's allowed to use attached to it. If one is\nmissing, the API responds with `403` and `code: \"scope_missing\"`; the\nmissing scope is in `details[].field`.\n"}},"responses":{"NotAuthenticated":{"description":"Key is missing, revoked or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"The request doesn't match the schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Rate limit reached","headers":{"Retry-After":{"schema":{"type":"integer","example":12}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Page":{"type":"object","description":"Cursor-based pagination.","properties":{"count":{"type":"integer","example":25},"total":{"type":"integer","example":138},"next_cursor":{"type":"string","nullable":true,"example":"eyJzIjoyNX0"}}},"ErrorDetail":{"type":"object","properties":{"field":{"type":"string","example":"start"},"reason":{"type":"string","example":"missing"}}},"Error":{"type":"object","description":"Uniform error format across all Real Estate Agency APIs.","required":["code","message"],"properties":{"code":{"type":"string","example":"validation_failed"},"message":{"type":"string","example":"The appointment start time is missing."},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"AppointmentStatus":{"type":"string","enum":["scheduled","confirmed","completed","cancelled"],"example":"confirmed"},"AppointmentType":{"type":"string","enum":["individual","group","virtual"],"example":"individual"},"AppointmentInput":{"type":"object","required":["property_id","type","start"],"properties":{"property_id":{"type":"string","example":"prop_8f2c1a"},"type":{"$ref":"#/components/schemas/AppointmentType"},"start":{"type":"string","format":"date-time","example":"2026-09-03T16:00:00+02:00"},"duration_minutes":{"type":"integer","minimum":10,"maximum":240,"default":30},"slots":{"type":"integer","minimum":1,"description":"Only evaluated when `type: group`.","example":12},"meeting_point":{"type":"string","maxLength":200,"example":"In front of the main entrance, 148 Elm Street"},"note":{"type":"string","maxLength":500,"example":"Please bring photo ID; the unit is currently occupied."}}},"Appointment":{"allOf":[{"$ref":"#/components/schemas/AppointmentInput"},{"type":"object","properties":{"id":{"type":"string","example":"appt_9a44"},"status":{"$ref":"#/components/schemas/AppointmentStatus"},"confirmations_count":{"type":"integer","example":8},"waitlist_count":{"type":"integer","example":2},"created_at":{"type":"string","format":"date-time","example":"2026-08-20T11:02:10Z"}}}]},"Confirmation":{"type":"object","properties":{"id":{"type":"string","example":"conf_1f7c"},"appointment_id":{"type":"string","example":"appt_9a44"},"lead_id":{"type":"string","example":"lead_71ab"},"state":{"type":"string","enum":["confirmed","waitlisted","cancelled","attended","no_show"]},"guests":{"type":"integer","example":1},"confirmed_at":{"type":"string","format":"date-time","example":"2026-08-21T09:14:00Z"}}},"TimeSlot":{"type":"object","properties":{"start":{"type":"string","format":"date-time","example":"2026-09-03T16:00:00+02:00"},"end":{"type":"string","format":"date-time","example":"2026-09-03T16:30:00+02:00"},"bookable":{"type":"boolean","example":true}}},"Feedback":{"type":"object","properties":{"id":{"type":"string","example":"fb_60d2"},"appointment_id":{"type":"string","example":"appt_9a44"},"lead_id":{"type":"string","example":"lead_71ab"},"interest":{"type":"string","example":"still_considering"},"price_assessment":{"type":"string","example":"too_high"},"comment":{"type":"string","example":"Layout works well, but the price is above what we had in mind."},"created_at":{"type":"string","format":"date-time","example":"2026-09-03T17:12:00Z"}}}}}}
```