API Guide - Leadpro

API Authentication

To authenticate, you must pass an API token, generated from your Lead management account, into an 'x-api-key' header along with your request.

"X-API-KEY": "avcdef***YOUR KEY***123"

In order to generate an API token, you can go to your account's developer tab and generate a new API token there. Lead Management allows you to generate multiple token per account, with logging of inbound requests and requests success against each token, allowing you to debug where your lead data came from more precisely.

Create Lead

POST https://api.lead.pro/api/v103/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.

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.

Example Request

{
    "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"
    }
}

{
    "id": 18376,
    "type": "sale",
    "title": "Mrs",
    "meta": {
        "Property ID": "7362",
        "Virtual Tour": "true",
        "Property Type": "detached"
    },
    "message": "I would like a valuation please",
    "first_name": "Marla",
    "email": "cloud9@cloud.com",
    "advert_url": "https://placeholder.com/150",
    "advert_image": null,
    "advert_postcode": "DE1 1JX",
    "advert_address": "123 Example Street, Example town",
    "address": null,
    "postcode": null,
    "appointment_availability": {
        "hours": [
            "2025-01-01T08:00:00.000Z",
            "2025-01-01T09:00:00.000Z"
        ]
    },
    "comparable_props": null,
    "phone": "01623000000",
    "source": "homepage",
    "full_name": "Marla Singer",
    "last_name": "Singer",
    "created_at": "2026-02-25T08:25:47.038Z",
    "is_parent": true,
    "parent_id": null,
    "questionnaire": null,
    "stage": "Unread",
    "status": "New",
    "minimum_sale_estimation": null,
    "average_sale_estimation": null,
    "maximum_sale_estimation": null,
    "minimum_rent_estimation": null,
    "average_rent_estimation": null,
    "maximum_rent_estimation": null,
    "valuation_status": null,
    "gdpr_checkbox": null,
    "host": null,
    "property_bedrooms": null,
    "property_reference": null,
    "property_type": null,
    "raw_property_reference": null,
    "office_id": 375,
    "office_name": "Nottingham",
    "out_of_area_distance": 5947.12,
    "international": false,
    "account_id": 18,
    "account_name": "Demo Brand",
    "referred_by_office_id": null,
    "referred_by_office_name": null,
    "referred_by_account_id": null,
    "referred_by_account_name": null,
    "eta": null,
    "facebook_pixel_id": null,
    "utm_source": "social_media",
    "utm_medium": null,
    "utm_campaign": "newsletter_2025",
    "utm_content": null,
    "utm_term": null,
    "utm_gclid": null,
    "property_bathrooms": null,
    "property_receptions": null
}

Create Instant Valuation Lead

POST https://api.lead.pro/api/v103/leads/valuation

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.

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.

Example Request

{
    "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"
}

{
    "id": 18381,
    "type": "vendor",
    "title": "Mrs",
    "meta": {
        "virtual tour": "true"
    },
    "message": "I would like to know how much my home is worth",
    "first_name": "Marla",
    "email": "cloud9@cloud.com",
    "advert_url": null,
    "advert_image": null,
    "advert_postcode": null,
    "advert_address": null,
    "address": "123 Example street, Example town",
    "postcode": "De1 1JX",
    "appointment_availability": {
        "hours": [
            "2021-01-01T08:00:00.000Z",
            "2021-01-01T09:00:00.000Z"
        ]
    },
    "comparable_props": null,
    "phone": "07986000000",
    "source": "ivt",
    "full_name": "Marla Singer",
    "last_name": "Singer",
    "created_at": "2026-02-25T08:37:23.861Z",
    "is_parent": true,
    "parent_id": null,
    "questionnaire": null,
    "stage": "Unread",
    "status": "New",
    "minimum_sale_estimation": 290000,
    "average_sale_estimation": 360000,
    "maximum_sale_estimation": 440000,
    "minimum_rent_estimation": 1000,
    "average_rent_estimation": 1200,
    "maximum_rent_estimation": 1500,
    "valuation_status": "Not Enough Comparable Properties",
    "gdpr_checkbox": true,
    "host": "https://www.yourdomain.ivt.com",
    "property_bedrooms": 4,
    "property_reference": null,
    "property_type": null,
    "raw_property_reference": null,
    "office_id": 42,
    "office_name": "Banbury",
    "out_of_area_distance": 22259.9,
    "international": false,
    "account_id": 18,
    "account_name": "Demo Brand",
    "referred_by_office_id": null,
    "referred_by_office_name": null,
    "referred_by_account_id": null,
    "referred_by_account_name": null,
    "eta": null,
    "facebook_pixel_id": null,
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null,
    "utm_content": null,
    "utm_term": null,
    "utm_gclid": null,
    "property_bathrooms": null,
    "property_receptions": null
}

Update Lead

PATCH https://api.lead.pro/api/v103/leads/{id}

Endpoint name: Update lead Endpoint URL: https://api.lead.pro/api/v103/leads/<id> Type: PATCH

The update lead endpoint allows you to pass a request body via a PATCH request with the ID of the lead you intend to update passed in the URI. The lead ID is sourced from the response body of the leads you create via the Create Lead endpoint.

Available fields

The following fields are available to be used to update a lead.

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
address	string	max 255	Contact address
postcode	string	max 255	Contact postcode
advert_address	string	max 255	Advert address
advert_postcode	string	max 255	Advert postcode
status	string		Status of the lead
office_id	number		Has to match an office ID
gdpr_checkbox	bool		If lead individual consents to GDPR
next_action_date	string	ISO8601 date string	Date of the next action on the lead
questionnaire	Collection<string, string>	max JSON byte size 2048, each value in questionnaire should be array of strings with 2 elements	Questionnaire responses. appended to existing responses
meta	Collection<string, string>	max JSON byte size 1024, object with only string values	any custom key value pairs you wish to use
utm_source	string		used for lead journeys
utm_campaign	string		used for lead journeys
utm_medium	string		used for lead journeys
utm_term	string		used for lead journeys
utm_content	string		used for lead journeys

Example Request

{
    "first_name": "Joe",
    "last_name": "Bloggs",
    "address": "123 Example Street",
    "postcode": "EX1 2MP",
    "advert_address": "456 Test Lane",
    "advert_postcode": "EX3 4NP",
    "status": "Contacted",
    "office_id": 375,
    "gdpr_checkbox": true,
    "next_action_date": "2025-07-12T10:00:00Z",
    "questionnaire": [["Do you have pets?", "Yes"]],
    "meta": {
        "data2": "value2",
    }
    "utm_source": "Google",
    "utm_medium": "CPC",
    "utm_campaign": "Summer Sale",
    "utm_content": "Ad1",
    "utm_term": "Real Estate",
    "utm_gclid": "GCLID1234567890"
}

{
    "first_name": "Joe",
    "last_name": "Bloggs",
    "address": "123 Example Street",
    "postcode": "EX1 2MP",
    "advert_address": "456 Test Lane",
    "advert_postcode": "EX3 4NP",
    "status": "Contacted",
    "office_id": 375,
    "gdpr_checkbox": true,
    "next_action_date": "2025-07-12T10:00:00Z",
    "questionnaire": [["Do you have pets?", "Yes"]],
    "meta": {
        "data2": "value2",
    }
    "utm_source": "Google",
    "utm_medium": "CPC",
    "utm_campaign": "Summer Sale",
    "utm_content": "Ad1",
    "utm_term": "Real Estate",
    "utm_gclid": "GCLID1234567890"
}

Get Leads

GET https://api.lead.pro/api/v103/leads/{id}

There are two endpoints available to get lead data from your leadpro system. One uses the explicit lead ID that you may have retained when creating leads through the API, the other allows you to return multiple leads that match on contact data such as email or phone.

Get lead by ID

Endpoint name: Get Lead Endpoint URL: https://api.lead.pro/api/v103/leads/<id> Type: GET

The get lead endpoint allows you to fetch lead data for a lead from it's ID. This is useful to check what data from a lead created through the API has changed since its initial creation, before applying any updates to it. You must specify a lead ID in the request URI to fetch lead data. A lead's ID is provided in the response body when creating leads through the API.

Get leads by contact details

Endpoint name: Get Lead Endpoint URL: https://api.lead.pro/api/v103/person/leads Type: GET

The get leads endpoint can return one or multiple leads from your system by matching contact details of the lead individual. The parameters that are available to use to query for leads are:

- email. The Person's email address. - phone The Person's phone number. - firstName The Person's first name. - lastName The Person's last name.

Note: Email or Phone must be supplied in your query parameters. Attempting to get lead data by first name or last name alone is not possible. The parameters can be passed into the get URL.

{
    "id": 28512440,
    "type": "mortgage_request",
    "title": "Mrs.",
    "meta": null,
    "message": null,
    "first_name": "Marla",
    "email": "example@lead.pro",
    "advert_url": null,
    "advert_image": null,
    "advert_postcode": null,
    "advert_address": null,
    "address": "123 Example Street",
    "postcode": "OX3 9NX",
    "appointment_availability": null,
    "comparable_props": null,
    "phone": "02061449046",
    "source": "zoopla",
    "full_name": "Marla Singer",
    "last_name": "Singer",
    "created_at": "2025-10-02T13:24:33.779Z",
    "is_parent": true,
    "parent_id": null,
    "questionnaire": null,
    "stage": "Unread",
    "status": "New",
    "minimum_sale_estimation": null,
    "average_sale_estimation": null,
    "maximum_sale_estimation": null,
    "minimum_rent_estimation": null,
    "average_rent_estimation": null,
    "maximum_rent_estimation": null,
    "valuation_status": null,
    "gdpr_checkbox": null,
    "host": null,
    "property_bedrooms": null,
    "property_reference": null,
    "property_type": null,
    "raw_property_reference": null,
    "office_id": 5271,
    "office_name": "Oxford",
    "out_of_area_distance": null,
    "international": false,
    "account_id": 2389,
    "account_name": "Skyline Estates Ltd",
    "referred_by_office_id": null,
    "referred_by_office_name": null,
    "referred_by_account_id": null,
    "referred_by_account_name": null,
    "eta": null,
    "facebook_pixel_id": null,
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null,
    "utm_content": null,
    "utm_term": null,
    "utm_gclid": null,
    "property_bathrooms": null,
    "property_receptions": null
}

Get Offices

GET https://api.lead.pro/api/v103/offices

This guide covers using the Lead API to get office data, other guides available that cover the Lead API are:

Endpoint name: Get Offices Endpoint URL: https://api.lead.pro/api/v103/offices Type: GET

The get offices endpoint provides you with a list of office names and IDs from your Lead management account. These IDs can be used when creating or updating leads if you prefer to explicitly route a lead to a particular office.

{
   "data": [
       {"id": "1213", "name": "office 1 name"}, 
       {"id": 1214, "name": "office 2 name"}
   ]
}

Get Statuses

GET https://api.lead.pro/api/v103/statuses

The get statuses endpoint provides you with a list of lead status names and IDs from your Lead management account. These IDs can be used when updating leads to change the status of said lead.

[
    {
        "id": 20,
        "name": "New",
        "stageId": 50,
        "isPredefined": true
    },
    {
        "id": 44,
        "name": "Another one",
        "stageId": 50,
        "isPredefined": false
    },
    {
        "id": 21,
        "name": "Contacted",
        "stageId": 100,
        "isPredefined": true
    }
]