Partners can now update or reassign a prospect’s agent using Knock’s Post Prospect API. This feature is a part of Knock’s solution for providing customers the ability to integrate with 3rd party vendors that build chatbot and messaging software. With the correct permissions, a partner can use the existing POST endpoint to assign a prospect to a specific agent by including that agent’s username in the payload.

What fields get updated on subsequent requests for the same prospect?

  1. Agent Username (Assigned Agent)

  2. First Name

  3. Last Name

  4. Phone Number

  5. Email Address

  6. Move-In Date

  7. Desired Lease Term

  8. Bedrooms

  9. Occupants

  10. Min Budget

  11. Max Budget

The general flow will be:

  1. Partner can now update or create a prospect with an agent username and save the prospectId from the response payload. Please see Knock Prospect Creation API for creating a prospect without an agent username.

    1. Note: Currently we do not have a way to look up a prospect Id, therefore the partner needs to save it from the Prospect Creation API response payload

  2. Partner can now call the Post Prospect endpoint : Post:/prospect with the following payload.

    1. Example request sent to POST:/prospect/

"agent": {
"username": "mock agnet username"
"knockTrackingEmail": "mockTrackingEmail@email.knck",
"sourceTitle": "Property Website",
"firstName": "Jane",
"lastName": "Doe",
"email": "",
"phone": "2065550155",
"moveDate": "2020-01-15",
"bedrooms": ["STUDIO"],
"occupants": 1,
"leaseTermMonths": 12,
"minBudget": 1000,
"maxBudget": 2000,
"autorespond": false,
"message": "Hi there- Do you have any east facing Studios available?"

Modify 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"; 2const endpoint = ""; 3 4const createProspect = async () => { 5 const req = { 6 "agent": { 7 "username": "1ed33973-975b-4d30-91a1-cdba4fa78190" 8 }, 9 "knockTrackingEmial": "", 10 "sourceTitle": "Property Website", 11 "firstName": "Jane", 12 "lastName": "Doe", 13 "email": "", 14 "phone": "2065550155", 15 "moveDate": "2020-01-15", 16 "bedrooms": ["STUDIO"], 17 "occupants": 1, 18 "leaseTermMonths": 12, 19 "minBudget": 1000, 20 "maxBudget": 2000, 21 "autorespond": false, 22 "message": "Hi there- Do you have any east facing Studios available?" 23 }; 24 25 const res = await fetch(endpoint, { 26 body: JSON.stringify(req), 27 headers: { 28 "Content-Type": "application/json", 29 "x-api-key": API_KEY 30 }, 31 method: "POST" 32 }); 33 34 const resp = await res.json(); 35 36 if (res.status === 200) { 37 // Success, e.g. { id: '123' } 38 console.log(resp); 39 } else { 40 // Failure: details at resp.errorMessage 41 console.error(resp); 42 } 43}; 44 45createProspect();

NOTE: All of the examples above should work in our test environment 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 and Knock will issue you your API_KEY for production.

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.


  • 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": "" 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:

{   2 "communityId": "b9XQN6eMvvrr07zg", 3    "sourceTitle": "Property Website", 4    "firstName": "Jane", 5    "lastName": "Doe", 6    "email": "", 7    "moveDate": "2020-01-15", 8    "message": "Hi there- Do you have any east facing Studios available?", 9 "autorespond" : false 10  }


{   2    "communityId": "b9XQN6eMvvrr07zg",    3 "sourceTitle": "Property Website", 4    "firstName": "Jane", 5    "lastName": "Doe", 6    "email": "", 7    "phone": null, 8    "moveDate": "2020-01-15", 9    "message": "Hi there- Do you have any east facing Studios available?", 10 "autorespond": false 11  }

Possible errors:

  1. Agent username does not exist

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

{ 2 "errorCode": "CORE_API_POST_PROSPECT_FAIL", 3 "errorMessage": "Unable to create prospect upstream - Invalid agent username failmepls." 4}
Did this answer your question?