Lead API - Create Leads

Create new leads via the Lead API

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

The create lead endpoint allows you to post new lead data into your Lead Management system. There are a multitude of fields available against leads for you to populate, below outlines fields of particular importance to consider when creating leads via the API.

Lead Type

You must specify a lead type using the 'type' field in your request body, there are four lead types available to use:

Sale - used to indicate the lead is a sales applicant, looking to buy a property
Let - used to indicate the lead is a let applicant, looking to rent a property
Vendor - used to indicate the lead is a sales vendor, looking to sell a property
Landlord - used to indicate the lead is a lettings vendor, looking to rent out a property

Address Fields

Leads have two address objects that can be populated, a contact address—used for indicating the address a lead individual can be contacted at, and an advert address—used for indicating an on-market property an applicant is interested in.

For Sale and Let leads, ensure the advert address fields are populated, these are the fields that represent the on-market property the individual is interested in buying or renting. These fields are 'advert_address' and 'advert_postcode'. The contact address, made up of 'address' and 'postcode' can still be populated for Sale or Let leads, if you have their contact address available to do so.
For Vendor and Landlord leads, only populate the 'address' and 'postcode' fields, as these are used for referencing their vendor data.

Sources

The source field can be used to indicate where a lead came from. The default source for API leads is 'homepage' indicating it came for your website. If you do not pass a source, or pass an invalid source, 'homepage' will be used against your lead. Other sources available to use include 'rightmove', 'rightmove_valuation', 'zoopla', 'zoopla_valuation', 'onthemarket', 'gumtree', 's1', 'lettingweb', 'propertypal', 'ivt'.

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": "sale",
    "phone": "01623000000",
    "first_name": "Marla",
    "last_name": "Singer",
    "email": "cloud9@cloud.com",
    "title": "Mrs",
    "advert_address": "123 Example Street, Example town",
    "advert_postcode": "DE1 1JX",
    "advert_url": "https://placeholder.com/150",
    "utm_source": "social_media",
    "utm_campaign": "newsletter_2025"
     "appointment_availability": {
      "hours": ["2025-01-01T08:00:00.000Z", "2025-01-01T09:00:00.000Z"]
    },
    "message": "I would like a valuation please",
    "meta": {
        "Property Type": "detached",
        "Virtual Tour": "true",
        "Property ID": "7362"
    }
}

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

Metadata object

The metadata object can be used to supply your own additional information with a created lead. The JSON format is a collection of string string pairs as demonstrated in the example payload further above. Metadata fields can be filtered on in the Lead Management system for Lead Responder workflows.

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.