Knock Self-Guided Appointment API

Our customers want more flexibility in how they can offer apartment tours to prospective renters. Knock's Self-Guided Appointment API aims provide that flexibility by allowing prospects to schedule a tour, access the building (enabled via integration partners), and complete their tour all on their own.

This article contains the technical documentation and details for developers to get started using this API.

Note: earlier Self-Guided Tour integrations used the Self-Guided Visit Integration API, which has been deprecated in favor of Self-Guided Appointments. Appointments appear on the Knock calendar and enable a better workflow than just Self-Guided Visits.

The general flow will be:

User clicks Self-Guided Tour link on Doorway and is redirected to a self-guided tour vendor partner's website with any utm_knock_source_title parameter appended to the URL
Vendor uses the availabile-times endpoint with forSelfGuided=true (see the Appointment Availability section at Knock Appointment Creation API). This endpoint automatically considers the client's preference on whether Self-Guided Appointments can be scheduled concurrently with In-Person Appointments.
User completes registration via vendor’s website, and vendor sends the appointment and prospect to Knock (via the Knock Appointment Creation API) with sourceTitle=utm_knock_source_title, tourType=SELF_GUIDED and the desired endTime. Note: endTime is specified in requestedTimes, e.g. "requestedTimes": [{ "startTime": "2020-09-23T15:30:00-07:00", "endTime": "2020-09-23T16:00:00-07:00" }]. The response payload from requesting the appointment will have an appointmentId, which will be needed later to associate a visit with an appointment. In the event that an appointment must be cancelled by the vendor, call the PUT /appointment/{appointmentId}/cancel endpoint.
User completes tour and vendor adds visit event to prospect (via Knock Visit API, see below) with sourceTitle=utm_knock_source_title, isSelfGuided=true, and appointmentId=<appointmentId from create appt response>.

Examples

NOTE: All of the examples below should work without modification in our test environment stage-syndication.knockrentals.com and with API_KEY syndication-appointment-TEST-KEY. Once you have completed testing and are ready to move to the production environment, you will need to replace the below endpoint with syndication.knockrentals.com and replace the below API_KEY with the production API_Key Knock provides you with.

Visit Event Creation

Create a prospect walk-in event using our Visit endpoint. You can use this endpoint to capture when a prospect took a self-guided tour through a property.

The visitTime is the time the prospect physically visited the property- note this must be in the past. The optional unitNames attribute, can be used to specify units that will be associated with the visit. We perform a case and space agnostic search against the unit names in our database and associate any matching units with the visit. In the real world, units can sometimes be out of sync between systems; therefore, we ignore units for which there is no match in our database. This graceful handling of units ensures that the visit is always recorded.

The following example demonstrates this using the JavaScript fetch API:

const API_KEY = "syndication-prospect-TEST-KEY";
const endpoint = "https://stage-syndication.knockrentals.com/visit";

const createVisit = async () => {
  const req = {
    "prospectId": "1",
    "visitTime": "2020-03-31T23:22:06.214Z",
    "appointmentId": "2"
    "isSelfGuided": true, // optional
    "sourceTitle": "Property Website", // optional
    "unitNames": ["123"] // optional
  };

  const res = await fetch(endpoint, {
    body: JSON.stringify(req),
    headers: {
      "Content-Type": "application/json",
      "x-api-key": API_KEY
    },
    method: "POST"
  });

  const resp = await res.json();

  if (res.status === 200) {
    // Success, e.g. `
    // `{
    //    "visitId": "12345"
    //  }`
    //
    console.log(resp);
  } else {
    // Failure: details at resp.errorMessage
    console.error(resp);
  }
};

createVisit();