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:
Prospects properly populate into our system
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 productionAPI_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 useProperty Website
, but this could be any source supported by Knock. Knock will provide you with your appropriatesourceTitle
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 theknockTrackingEmail
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 totrue
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?"
}