Knock Get Prospect API

Knock Get Prospect API is a part of Knock’s solution for providing customers the ability to integrate with 3rd party vendors that build chatbot and messaging software. The focus of this endpoint is to provide a way for our partners to retrieve all the relevant information relating to their prospects, including their status, whether or not they have consented to SMS messages, their email, etc. This is possible through our GET https://syndication.knockrentals.com/prospect/{prospectId} endpoint.

This endpoint will only return an existing prospect’s information. It will not update or add a new prospect nor will it update any fields. The information returned here should be identical to what’s in that prospect’s guest card, with some additional fields. Updates made to the guest card or that are otherwise imported into Knock will be reflected in the information returned by this endpoint.

The general flow will be:

1. Partner can now call a prospect and save the prospectId from the response payload. A prospect can be created via the Knock Prospect Creation API

   1. Note: Currently we do not expose the prospectId, therefore the parter needs to save it from the Prospect Creation API response payload

2. Partner can now call the Get Prospect endpoint : GET:/prospect/{prospectId}, with the prospectId.

   1. Example response for calling GET:/prospect/{prospectId}

{
"prospectId": "47569637",
"communityId": "191b65d2686d11e9",
"email": "[e-mail]",
"phone": "[phone]",
"agent": {
"username": "2be16a9e-b3ab-4b1f-9632-575aca1a3d20"
},
"address": null,
"unit": null,
"city": null,
"state": null,
"zip": null,
"source": {
"title": "Property Website"
},
"firstName": "New",
"lastName": "Lead",
"moveDate": null,
"bedrooms": null,
"pets": null,
"occupants": null,
"leaseTermMonths": null,
"minBudget": null,
"maxBudget": null,
"smsConsent": false,
"isDeleted": false,
"notProspect": false,
"createdAt": "2021-10-14T18:10:34.515181+00:00",
"updatedAt": "2021-10-14T18:10:34.694332+00:00",
"firstContactType": "form",
"status": "new"
}

Getting the Prospect Information

Get a prospect’s information through our Get Prospect endpoint. You can use the API endpoint to get a prospect’s information using GET :/prospect/{prospectId}. For more details on the parameters, check out our swagger docs here: stage documentation, prod documentation.

The following demonstrates this using JavaScript fetch API:

const API_KEY = "syndication-prospect-TEST-KEY";

const getInternalProspect = async (prospectId) => {
const endpoint = `https://stage-syndication.knockrentals.com/prospect/${prospectId}`;
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. { id: '123' }
console.log(resp);
} else {
// Failure: details at resp.errorMessage
console.error(resp);
}
};

getInternalProspect(51316);

NOTE: All of the examples above should work 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.

Variable definitions:

• API_KEY is a header. It’s 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.

• prospectId is a path parameter. It’s the id of the prospect the manager is communicating with. This must be a number without spaces or special characters.

Possible errors:

1. Malformed Prospect Id

   1. Prospect Ids must be numbers with no spaces or special characters.

{
"errorMessage": "Id xxx is not a valid prospect id. Id must be a number."
}

Prospect does not exist

1. If you get this error, it means that prospect is not in the database. Please create a prospect or double check your prospectId.

{
"errorCode": "CORE_API_GET_PROSPECT_FAIL",
"errorMessage": "Unable to get prospect upstream - Prospect_id 0 does not exist."
}