Knock Prospect Creation API

Prospects come into Knock from a variety of sources, including property website contact forms and ILS contact forms. For inserting leads into Knock from a 3rd party, we recommend using our API, outlined below.

If you are unable to use an API you can insert leads into Knock either using our standard email format or our doorway contact form. 

Using the Knock API will ensure:

1. Prospects properly populate into our system

2. You are getting proper source attribution for those leads

We use OpenAPI/Swagger to document our API endpoints. For more details about /prospect endpoint and to test out live examples, please see our swagger.yml.

Prospect Creation

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 this endpoint with syndication.knockrentals.com and Knock will issue you your API_KEY for production.

Prospects can be created using our /prospect endpoint. The following example demonstrates this using the JavaScript fetch API:

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

const createProspect = async () => {
  const req = {
    "communityId": "b9XQN6eMvvrr07zg",
    "sourceTitle": "Property Website",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "janedoe@example.com",
    "phone": "2065550155",
    "moveDate": "2020-01-15",
    "bedrooms": ["STUDIO"],
    "occupants": 1,
    "leaseTermMonths": 12,
    "minBudget": 1000,
    "maxBudget": 2000,
    "autorespond": true,
    "message": "Hi there- Do you have any east facing Studios available?"
  };
  
  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. { id: '123' }
    console.log(resp);
  } else {
    // Failure: details at resp.errorMessage
    console.error(resp);
  }
};

createProspect();

Variable definitions:

• API_KEY  is the key that gives you access to Knock's API. We will provide you 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.

• sourceTitle  refers to the marketing channel to which this prospect should be attributed. In the example above, we use Property Website, but this could be any source supported by Knock. Knock will provide you with your appropriate sourceTitle 

• communityId refers to the unique identifier associated with a property in Knock's system. The example above refers to a community we have setup for testing purposes, but Knock will provide these community IDs for you. Alternatively, you can use the knockTrackingEmail  to specify the community you want to send the lead to.

• autorespond  refers to whether or not the prospect will receive an automatic email response from Knock with a link to schedule a tour through Knock. This is optional and defaults to true 

• The max character limit for the message field is 1000. 

Misc

• Note that if you do not have a phone number or an email address, you should either omit those fields entirely or set them to null .
  
  Do NOT set a hardcoded placeholder value like "phone": "XXXXXXXXXX" or "email": "noemail@nowhere.com" or Knock's deduplicating logic will tie all the prospects under one guestcard.
  
  For example, here is what you could have as the JSON for a request for a prospect with no phone:

{
    "communityId": "b9XQN6eMvvrr07zg",
    "sourceTitle": "Property Website",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "janedoe@example.com",
    "moveDate": "2020-01-15",
    "message": "Hi there- Do you have any east facing Studios available?"
  }

OR

{
    "communityId": "b9XQN6eMvvrr07zg",
    "sourceTitle": "Property Website",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "janedoe@example.com",
    "phone": null,
    "moveDate": "2020-01-15",
    "message": "Hi there- Do you have any east facing Studios available?"
  }