We are very excited to offer our scheduling API to select ILS partners to display realtime availability to prospects and give them the ability to instantly book tours that will seamlessly funnel into Knock CRM. This is a win for everyone: prospects get to instantly schedule a tour at the property which leads to higher web to tour to lease conversion rates for property managers.

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

The general flow will be:

  1. ILS makes the available-times API call to Knock to retrieve the community's available time slots for apartment tours
  2. ILS displays the available times to the prospect on their site so that prospects can instantly book right from an ILS listing:
  3. Prospect fills out their contact information and selects an available time in the UI to book their tour
  4. ILS makes /appointment/request API call to book an appointment in Knock CRM
  5. This will create the appointment in Knock, and Knock will immediately send the prospect a confirmation email. Additionally, if smsConsent  is set to true in the API request, Knock will immediately send the prospect a confirmation text as well as a reminder text 2 hours before the tour time.
  • If the prospect does not yet exist in Knock at the community, Knock will automatically create the prospect (i.e. there is no need to make a separate API call to create the prospect- the /appointment/request suffices)
  • If the prospect already exists in Knock at the community, Knock will match the appointment to the existing prospect based on email/phone match (i.e. there is no need to do a lookup to see if the prospect already exists- Knock automatically de-dupes)
  • If the prospect already exists in Knock at the community AND has an upcoming appointment at the community (rare), Knock will cancel the old appointment and schedule the new one

We use OpenAPI/Swagger to document our endpoints. For more details and technical documentation of each endpoint, please see swagger.yml. Below are some examples of the two API calls an ILS partner should make for appointment scheduling:

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.

Appointment Availability

Appointment availability can be checked for a given property using our /community/${communityId}/available-times  endpoint. The following example demonstrates this using the JavaScript fetch API:

const API_KEY = "syndication-appointment-TEST-KEY";
const endpoint = "https://stage-syndication.knockrentals.com/community/b9XQN6eMvvrr07zg/available-times";

const getAvailableTimes = async () => {
  const res = await fetch(endpoint, {
    headers: {
      "Content-Type": "application/json",
      "x-api-key": API_KEY
    },
    method: "GET"
  });

  const resp = await res.json();

  if (res.status === 200) {
    // Success, e.g. { acceptableTimes: ['2018-12-20T07:00:00-08:00', ...]}
    console.log(resp);
  } else {
    // Failure: details at resp.errorMessage
    console.error(resp);
  }
};
 getAvailableTimes();

With the response from this API call, the interface on the ILS should show the prospect the times available to book a tour:

Appointment Request

Appointments can be requested for a given property using our /appointment/request  endpoint. The following example demonstrates this using the JavaScript fetch  API:

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

const requestAppointment = async () => {
  const req = {
    "communityId": "b9XQN6eMvvrr07zg",
    "profile": {
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "janedoe@example.com",
      "phone": "2065554567",
      "moveDate": "2020-01-01",
      "bedrooms": ["STUDIO"],
      "occupants": 1,
      "leaseTermMonths": 12,
      "minBudget": 1000,
      "maxBudget": 2000,
      "pets": ["CAT", "LARGE_DOG"]
    },
    "requestedTimes": [{"startTime": "2019-07-17T15:00:00-07:00"}],
    "smsConsent": false,
    "sourceTitle": "Zillow"
  };

  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. `
    // {
    //    "endTime": "2019-07-17T08:15:00.000Z",
    //    "id": "12345",
    //    "startTime": "2019-07-17T08:00:00.000Z",
    //    "status": "CONFIRMED"
    //  }
    //
    console.log(resp);
  } else {
    // Failure: details at resp.errorMessage
    console.error(resp);
  }
};

requestAppointment();

At this point, the prospect will be submitting their form to book their tour:

Assuming Knock's API returns a success message, the ILS interface should show some sort of confirmation that the prospect's tour booking was completed:

If Knock's API returns an error for that time, the ILS interface should show the appropriate error message to the prospect and allow them to rebook.

Variable Definitions

  • API_KEY  is the key that gives you access to Knock's API. We will provide you with your production API_KEY  once we have validated a successful test in our staging environment. You will need to replace the above key with the unique key we issue to you before attempting to use our API in production.
  • smsConsent indicates whether you have captured prior express written consent from the prospect to receive marketing text messages by automated dialing systems from the property.

    LEGAL NOTE PRIOR TO USING THIS FIELD:

    (i) Knock does not assume liability for messages that result from the usage of our API.
    (ii) Please consult your legal council to review your required legal disclaimers and disclosures.
    (iii) Please consult your legal council to review your texting communications and content policies.
    (iv) Please consult your legal council to review your Knock Partner Services Agreement for more information.
  • communityId  is an internal Knock ID referring to a specific community. You can retrieve a complete list of all communities your API_Key has access to via the /communities endpoint documented in Swagger here. This endpoint will return communityName , communityId , address , geolocation , and companyName.

    N.B. The endpoint uses a cursor-based pagination pattern. To iterate through the list of pages, first make a request and omit the after parameter. Then make subsequent requests and set the after parameter equal to the value of the previous page's endCursor. Repeat the process until the value of hasNextPage is false, and you have reached the last page

Did this answer your question?