Book a viewing

This guide shows you how to book a property viewing using the Viewings API. Viewings are booked against an enquiry, and Yorlet handles the confirmation, the calendar invite, the reminder, and the follow-up for you.

Prerequisites

Before booking a viewing, ensure you have:

The Leads product enabled on your account.
A secret key.
An enquiry ID.
Viewing availability configured on the account, if you want to offer bookable slots.

Your secret key can perform any action on your account, so only ever use it from your own server. Never embed it in a booking page, a mobile app, or anything else a lead can see.If you want leads to pick their own slot, send them a booking link rather than calling the slots endpoint from the browser. The hosted page authenticates itself with a key scoped to that one enquiry, so your secret key never leaves your server. If a secret key is ever exposed, roll it immediately.

Permissions

Permission	Grants
`leads.viewings.read`	Retrieve and list viewings, and list bookable slots
`leads.viewings.write`	Book, reschedule, and transition viewings

Look up bookable slots

Slots are derived from the account’s weekly viewing availability, minus anything already on the calendar. They respect the configured viewing duration, buffer, minimum notice, and booking horizon, so anything returned is safe to offer a lead.

List bookable slots

curl "https://api.yorlet.com/v1/leads/viewings/slots?enquiry=le_pXm2Qk8sZ1vBnRtY&from=1712716800&to=1713321600" \
  -H "Authorization: Bearer {{API_KEY}}"

Response

{
  "object": "list",
  "data": [
    {
      "object": "leads.viewing_slot",
      "start_time": 1712743200,
      "end_time": 1712745000,
      "duration": 30
    }
  ],
  "count": 1,
  "has_more": false
}

Parameter	Type	Required	Description
`enquiry`	string	Yes	The enquiry to compute slots for
`from`	timestamp	No	Start of the range. Defaults to now
`to`	timestamp	No	End of the range. Defaults to 14 days after `from`, and must be after it

An empty data array usually means the account has no viewing availability configured, or the whole range falls inside the minimum notice period.

Only enquiry and start_time are required. The unit and host default to whatever is on the enquiry, and the duration defaults to the account’s viewing duration.

Book a viewing

curl https://api.yorlet.com/v1/leads/viewings \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
        "enquiry": "le_pXm2Qk8sZ1vBnRtY",
        "start_time": 1712743200,
        "duration": 30,
        "unit": "unit_lrhplff1u4ZhIPSU",
        "assignee": "user_9fRtZm4nQpLxVsKd",
        "notes": "Lead is running late, buzz flat 4"
      }'

Response

{
  "id": "lv_3nQpZr7tKmXwBsLd",
  "object": "leads.viewing",
  "created": 1712716800,
  "enquiry": "le_pXm2Qk8sZ1vBnRtY",
  "unit": "unit_lrhplff1u4ZhIPSU",
  "assignee": "user_9fRtZm4nQpLxVsKd",
  "start_time": 1712743200,
  "duration": 30,
  "status": "scheduled",
  "source": "manual",
  "notes": "Lead is running late, buzz flat 4",
  "canceled_at": null,
  "canceled_reason": null,
  "completed_at": null,
  "metadata": {}
}

Viewing parameters

Parameter	Type	Required	Description
`enquiry`	string	Yes	The ID of the enquiry to book the viewing for
`start_time`	timestamp	Yes	When the viewing starts
`duration`	integer	No	Length in minutes (5–480). Defaults to the account viewing duration
`assignee`	string	No	The ID of the user hosting. Defaults to the enquiry’s assignee
`unit`	string	No	The ID of the unit being viewed. Defaults to the unit on the enquiry
`notes`	string	No	Internal notes recorded against the viewing
`metadata`	object	No	Key-value pairs for storing additional information

Booking a viewing also advances the enquiry to viewing when it is at an earlier stage, so you do not need to transition it yourself.

Requests made with a secret key are only checked for collisions, not against your published availability, so your own team can book outside their usual windows. Bookings made by a lead through their booking link must fall exactly on a published slot.

Let the lead book their own slot

Rather than choosing a time on the lead’s behalf, create a booking link on the enquiry and let them pick. Set notification.type to email to send it to them, or none to return the URL and deliver it yourself.

Create a booking link

curl https://api.yorlet.com/v1/leads/enquiries/le_pXm2Qk8sZ1vBnRtY/booking_link \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{ "notification": { "type": "email" } }'

The response is a leads.viewing_booking_link object with the enquiry it belongs to and the url of the hosted booking page. The link is created on first use and reused for the lifetime of the enquiry, and the hosted page handles its own authentication, so you never expose an API key to the lead. Leads booking through the link can pick a slot, reschedule, and cancel, but they cannot record an outcome. Viewings they book have a source of self_serve; viewings your team books have manual.

Turn on automatic booking links in the account’s viewing settings and Yorlet emails the lead their link as soon as you transition the enquiry to qualified — no extra API call needed.

Reschedule a viewing

Pass a new start_time to the update endpoint. Yorlet re-checks the slot, sends the lead an updated confirmation, and reschedules the reminder and follow-up.

Reschedule a viewing

curl https://api.yorlet.com/v1/leads/viewings/lv_3nQpZr7tKmXwBsLd \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{ "start_time": 1712829600 }'

You can also update duration, assignee, unit, and notes. Pass null to assignee or unit to clear them.

Record the outcome

Use the status endpoint once the viewing has happened, or to call it off.

Mark a viewing as completed

curl https://api.yorlet.com/v1/leads/viewings/lv_3nQpZr7tKmXwBsLd/status \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{ "status": "completed" }'

Status	Meaning
`scheduled`	Booked and upcoming. Setting this again clears any recorded outcome
`completed`	The lead attended. Records `completed_at`
`canceled`	Called off. Records `canceled_at` and the optional `reason`, and frees the slot
`no_show`	The lead did not attend, and the slot is freed

Marking a viewing as completed follows up with the lead and reminds the host to move them on to an application.

What Yorlet sends the lead

Booking a viewing through the API triggers the same lifecycle as booking one in the Dashboard:

When	What happens
Booked or rescheduled	The lead is emailed a confirmation with a calendar invite, and the host is notified
24 hours before	The lead is reminded, unless the viewing has moved or already has an outcome
After the end time	The lead is followed up with, and the host is nudged to record the outcome
Marked as completed	The lead is followed up with, and the host is nudged towards an application

List viewings

List upcoming viewings for an enquiry

curl "https://api.yorlet.com/v1/leads/viewings?enquiry=le_pXm2Qk8sZ1vBnRtY&sort=ascending&expand[]=assignee&expand[]=unit" \
  -H "Authorization: Bearer {{API_KEY}}"

Parameter	Type	Description
`enquiry`	string	Filter to viewings for a single enquiry
`status`	string or array	Filter by one or more statuses
`source`	string	`self_serve` or `manual`
`unit`	string	Filter by the unit being viewed
`assignee`	string	Filter by host
`sort`	string	`ascending` or `descending` by start time

enquiry, assignee, and unit can each be expanded with expand[].

Developer tools

Essentials

Integrations

Platforms

Book a viewing

Prerequisites

Permissions

Look up bookable slots

Book a viewing

Viewing parameters

Let the lead book their own slot

Reschedule a viewing

Record the outcome

What Yorlet sends the lead

List viewings

​Prerequisites

​Permissions

​Look up bookable slots

​Book a viewing

​Viewing parameters

​Let the lead book their own slot

​Reschedule a viewing

​Record the outcome

​What Yorlet sends the lead

​List viewings

Prerequisites

Permissions

Look up bookable slots

Book a viewing

Viewing parameters

Let the lead book their own slot

Reschedule a viewing

Record the outcome

What Yorlet sends the lead

List viewings