Lead API - Create Instant Valuation Leads

Create new instant valuation leads via the Lead API

This guide covers using the Lead API to create new instant valuation leads, other guides available that cover the Lead API are:

Endpoint name: Create Instant Valuation Lead Endpoint URL: https://api.lead.pro/api/v103/leads/valuation Type: POST

The create instant valuation lead endpoint allows you to post new lead data into your Lead Management system, and receive a sale or let valuation estimate immediately in your lead response, to utilise on your own website or in your own software.

Creating an instant valuation lead, you can only pass in the lead types Vendor or Landlord, depending on if you'd like to receive a sale or let estimate.

The default source for a created valuation lead is 'ivt', which will appear against the lead in the dashboard as 'Instant Valuation'. You can instead pass a different source, as outlined in the Create Lead endpoint documentation.

Routing Leads to Offices

Routing leads to Lead Management offices through the API can be achieved through two methods. To explicitly instruct a lead to land in a particular office, include the 'office_id' field in your request payload. You can source your office names and IDs from the Get Offices endpoint.

If no office ID is provided in the request, the 'postcode', or 'advert_postcode' field will be used, depending on lead type, to route the lead to the closes office with near or exact postcode coverage.

Example Request Payload

{ "type": "vendor", "phone": "07986000000", "property_bedrooms" : 4, "first_name": "Marla", "last_name": "Singer", "email": "cloud9@cloud.com", "title": "Mrs", "address": "123 Example street, Example town", "postcode": "De1 1JX", "appointment_availability": { "hours": ["2021-01-01T08:00:00.000Z", "2021-01-01T09:00:00.000Z"] }, "message": "I would like to know how much my home is worth", "meta": { "virtual tour" : "true" }, "gdpr_checkbox": true, "host": "https://www.yourdomain.ivt.com" }

Available Request Fields

The following fields are available to include in your request payloads for creating new leads.

Field Name	Type	Validation	Use
first_name *	string	length : min 1 max 50	first name of user/lead
last_name *	string	length : min 1 max 50	last name of user/lead
email *	string	must be valid email address	email of user/lead
phone *	string	length : max 255 ( only valid UK phone numbers will be called by autocaller)	phone number of user/lead
type *	string	either : 'sale', 'vendor', 'landlord', 'let', 'mortgage_request'	categorising your lead in the dashboard
title	string	length : min 1 max 50	title of user/lead
advert_address	string	length : max 100	address user/lead is enquiring about
advert_postcode	string	length : min 2 max 10	postcode of the address user/lead is enquiring about
advert_url	string	length : max 255	url of the property user/lead is enquiring about
advert_image	string	length : max 255	image location of the property user/lead is enquiring about
message	string	length : max 255	custom message from the user/lead
appointment_availability	Collection<string>	max JSON byte size 1024, object with only string values	appointment avaliablity of the user/lead
meta	Collection<string, string>	max JSON byte size 1024, object with only string values	any custom key value pairs you wish to use
questionnaire	Collection<string, string>	max JSON byte size 2048, each value in questionnaire should be array of strings with 2 elements	if they answer questions on your enquiry
gdpr_checkbox	boolean	true/false	if user/lead consents to GDPR
host	string	length : max 255	the page or host where lead/user submits information
office_id	number	N/A	has to match an officeID in the account if not provided api will autoassign to nearest office
address	string	length : max 100	home address of the user/lead
postcode	string	length : min 2 max 10	postcode of the user/lead
source	string	N/A	you can submit a specific lead source. If no source is submitted it will default to 'homepage' possible values : 'rightmove', 'rightmove_valuation', 'zoopla', 'zoopla_valuation', 'onthemarket', 'gumtree', 's1', 'lettingweb', 'propertypal', 'propertynews', 'ivt', 'homepage',
international	boolean	N/A	used to categorise if lead is from an international source
utm_source	string	N/A	used to pass through any source data for reporting
utm_campaign	string	N/A	used to pass through any campaign data for reporting
utm_medium	string	N/A	used to pass through any medium data for reporting
utm_term	string	N/A	used to pass through any term data for reporting
utm_content	string	N/A	used to pass through any content data for reporting
property_type	string	detached, semi-detached, terraced, flat-maisonette	indicate the type of property user/lead has or interested in

Estimation Data

The returned response will include the following fields that will indicate if the valuation was a success, and what the estimate values are:

{

"minimum_sale_estimation": 2000000, "average_sale_estimation": 2200000, "maximum_sale_estimation": 2400000, "minimum_rent_estimation": 5995, "average_rent_estimation": 6595, "maximum_rent_estimation": 7194, "valuation_status" : "Success",

}

Responses

Upon successful lead creation, you will receive a Success 200 code. If the request fails you will receive a Failure 4xx code with a reason for failure.