1. Knock
  2. Operations/Marketing
  3. Marketing Automation Suite
  4. Internet Listing Services

Knock Scheduling API for ILS Partners

Permanently deleted user
Updated

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",
"tourType": "IN_PERSON"
  };

  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 , companyName, inPersonToursEnabled and liveVideoToursEnabled.

    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

  • tourType can be either IN_PERSON, LIVE_VIDEO or omitted. When the tourType is omitted, it is assumed to be IN_PERSON. Communities have the option of supporting one or more tourTypes and this support can be toggled at any time. As such, you'll want to access the /communities endpoint, documented in Swagger here, on a daily basis to retrieve which tourTypes are enabled. This endpoint will return values for inPersonToursEnabled and liveVideoToursEnabled for each community. In the event that you attempt to use a tourType that is not supported, the /appointment/request endpoint will respond with an error.

Appointment Webhook Notifications

You may receive webhook notifications about appointments made for properties you have access to. Notifications will be sent to you as POST requests whenever the appointment of interest's status changes, and is guaranteed to be delivered at least once. An example webhook request body is shown below:

 

{
  "edges": [
    {
      "type": "APPOINTMENT",
      "node": {
        "appointmentId": "123456",
        "prospectId": "54321",
        "startTime": "2019-11-19T21:00:00.000Z",
        "endTime": "2019-11-19T21:30:00.000Z",
        "source": "Zillow",
        "status": "CONFIRMED",
        "updatedAt": "2019-11-12T21:19:13.000Z"
      }
     }
  ]
}

To set up webhook notifications: Reach out to the Knock Product Team, and provide the following info:

 

  • webHookUrl : this is the URL of your API endpoint that will be POST ed to when there is new appointment change data.

  • webHookHeaders : (optional) headers necessary to make the request (eg. Auth)

Appointment Statuses:

  • CONFIRMED  = Appointment has been booked

  • VISITED  = Prospect physically visited property for appointment

  • CANCELLED  = Prospect or leasing agent cancelled appointment prior to appointment time

  • NO_SHOW  = Prospect did not show up for scheduled appointment

Notes:

  • To evaluate webhook notifications on our staging environment, you may find it useful to use a mock API service (such as webhook.site) before implementing an API endpoint to receive webhook requests.

  • Should your API service go down, or encounter an error when handling a webhook notification, we will retry the request every 15 minutes for up to 3 days.

  • updatedAt represents when the notification was sent. This can be useful for ordering notifications or recovery after your API endpoint has been down.

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.

Articles in this section