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

Our customers want more flexibility in how they can offer apartment tours to prospective renters. Knock's Self-Guided Tour 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.

The general flow will be:

  1. 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

  2. User completes registration via vendor’s website, and vendor sends prospect to Knock (via Knock Prospect Creation API) with sourceTitle=utm_knock_source_title

  3. User completes tour and vendor adds walk-in event to prospect (via Knock Visit API, see below) with sourceTitle=utm_knock_source_title and is_self_guided=true

Examples

NOTE: All of the examples below should work without modification in our test environment stage-syndication.knockrentals.com and with API_KEY  syndication-prospect-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",
    "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();
Did this answer your question?