Dashboard
Instant Valuation Tool
Lead Responder
Autocaller

LeadPro API

The current version of our API is v103 and you will need this version number to use the API

Each request must have your LeadPro API key in the authorization header.

X-API-KEY : ay****YOUR-API-KEY****9hw4

GET - Offices

You may need to assign leads to offices within your account when using other endpoints. To get your office IDs associated with your account you can use this endpoint :

*Offices are created by admin accounts in the lead.pro dashboard

GET - https://api.lead.pro/api/v{version_number}/offices

If the request is successful, you will receive a 200 OK status code and the information will be returned in the request.

Example Response

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



POST - Lead

This endpoint will create a lead and make it visible in your dashboard

 

POST - https://api.lead.pro/api/v{version_number}/leads

The most common use for POST- Lead is to capture information about users that enquire about properties you either have for sale or to let on your website (these are called leads) . In this example we will create a lead that is interested in a property for sale on your website. 

The type field is used for indicating how the lead will be categorised within your dashboard.

These are the possible type values for POST - Lead

‘sale’ - used to indicate the lead is interested in buying a property 

‘let’ - used to indicate the lead is interested in letting a property

Example request body to create a ‘sale’ lead within your dashboard : 

{
    "type": "sale",
    "phone": "1234567812",
    "first_name": "Fluffy",
    "last_name": "Cloud",

    "email": "cloud9@cloud.com",

    "title": "Mr",
    "advert_address": "51 Asimov Place, Starbridge",
    "advert_postcode": "N1 3JY",
    "advert_url": "https://via.placeholder.com/150",
     "appointment_availability": {
      "hours": ["2021-01-01T08:00:00.000Z", "2021-01-01T09:00:00.000Z"]
    },
    "message": "I would like a valuation please",
    "meta": {
        "Marketing Source": "PPC",
        "Marketing Permission": "true",
        "Min Price": "£200,000",
        "Property Type": "detached",
        "Virtual Tour": "true",
        "Property ID": "7362"
    }
}

There are some fields that are required when creating a lead in your dashboard, the table below shows what fields you can send. * fields with this symbol are required when creating 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
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
JSON
max JSON byte size 1024, object with only string values
appointment avaliablity of the user/lead
meta
Record<String, String>
max JSON byte size 1024, object with only string values
any custom key value pairs you wish to use
questionnaire
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', 'yourmove', 'yourmove_valuation', 'reedsrains', 'reedsrains_valuation', 'homepage', 'folio'

Metadata field

You can use the metadata field type to send custom options unique to your use case

For example :

You may want to indicate that a lead has come from a PPC source, wants to receive marketing materials, owns a detached property, is interested in re-mortgaging, have a minimum budget of £200,000 and would also like an in person rental valuation. You could use the metadata field to do this.

Example Metadata

{
    "Marketing Source": "PPC",
    "Marketing Permission": "true",
    "Min Price": "£200,000",
    "Property Type": "detached",
    "Virtual Tour": "true",
    "Property ID": "7362",
    "Mortgage Type": "remortgage",
    "Additional Opportunity": "Vendor has also requested rental valuation"
}

The fields sent in the metadata will be displayed in your dashboard under 'additional information' section for that specific lead.

We will assign a lead to an office within your account based on the address fields passed in the request. It is not advised to assign an office manually, if however you need to do this for some reason the office_id you send must be a valid office_id otherwise the request will fail.

If the request is successful, you will receive a “Success”:200 status code and the created valuation lead information will be returned to you.

If the request fails you will receive a “Failure”: 4xx with the relevant code relating to the error.

Example created lead response

{
    "id": 6016019,
    "type": "sale",
    "title": "Mr",
    "meta": {
        "Min Price": "£200,000",
        "Property ID": "7362",
        "Virtual Tour": "true",
        "Property Type": "detached",
        "Marketing Source": "PPC",
        "Marketing Permission": "true"
    },
    "message": "I would like a valuation please",
    "first_name": "Fluffy",
    "email": "cloud9@cloud.com",
    "advert_url": "https://via.placeholder.com/150",
    "advert_image": null,
    "advert_postcode": "N1 3JY",
    "advert_address": "51 Asimov Place, Starbridge",
    "address": null,
    "postcode": null,
    "appointment_availability": {
        "hours": [
            "2021-01-01T08:00:00.000Z",
            "2021-01-01T09:00:00.000Z"
        ]
    },
    "comparable_props": null,
    "phone": "1234567812",
    "source": "homepage",
    "full_name": "Fluffy Cloud",
    "last_name": "Cloud",
    "created_at": "2021-09-01T13:59:40.706Z",
    "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,
    "gdpr_checkbox": null,
    "host": null,
    "property_bedrooms": null,
    "property_reference": null,
    "office_id": 3442,
    "office_name": "North 500ft"
}


POST - Instant Valuation Lead

Instant Valuation Leads can be created by sending a POST request to

POST - https://api.lead.pro/api/v{version_number}/leads/valuation

The most common use case for this endpoint is to create your own instant valuation tool. It will return an accurate valuation of a property address the user provides to you and create a lead in your dashboard.

This is an example of a web application using this endpoint Online Valuation Tool Example

This endpoint will return both a lettings valuation estimation and a sales valuation estimation.

It is up to you to categorise if your user required a sales or letting valuation

The type field is used for categorising a lead within the lead.pro dashboard. Possible values for POST- instant valuation lead.

‘vendor’ - used to categorise that the lead has requested a sales valuation of a property

‘landlord’ - used to categorise that the lead has requested a letting valuation of a property

'mortgage_request' - used to indicate the lead is interested in mortgages

Here is an example request to create a ‘vendor’ lead in your dashboard and get an instant valuation of a property address the lead has requested.

{
    "type": "vendor",
    "phone": "1234567812",
    "property_bedrooms" : 4,
    "first_name": "Fluffy",
    "last_name": "Cloud",
    "email": "cloud9@cloud.com",
    "title": "Mr",
    "address": "51 Asimov Place, Starbridge",
    "postcode": "N1 3JY",
     "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"
}


The POST request has some required fields that must be sent in order for the request to be successful and the instant valuation lead created and estimation returned to you.

* fields with this symbol are required when creating a valuation lead

Field Name
Type
Validation
Use
property_bedrooms *
number
integer
number of bedrooms that the property user/lead would like to know the valuation of
postcode *
string
length : min 2 max 10
postcode of the property user/lead wants a valuation of
first_name *
string
length : min 1 max 50
user/lead first name
last_name *
string
length : min 1 max 50
user/lead last name
email *
string
email
user/lead email
phone *
string
GB phone number
user/lead phone number
address *
string
length : max 100
address you want to know the value of
type *
string
type 'vendor', 'sale', 'mortgage_request'
send the right type for the valuation the user is intrested in

All fields from POST - Lead can also be used in POST - Instant Valuation Lead

The difference is that you will get a valuation estimation of the property you provided and comparable sold properties in the surrounding area for the ‘address’, postcode’ and ‘property_bedrooms’ you pass in the request, these estimations will be returned to you alongside the other lead fields sent in the request. (see example response below)

If the request is successful, you will receive a “Success”:200 status code and the created valuation lead information will be returned to you.

If the request fails you will receive a “Failure”: 4xx with the relevant code relating to the error

Example response including the valuation estimations calculated by our algorithm that you can use however you would like.

{
    "id": 6099387,
    "type": "vendor",
    "title": "Mr",
    "meta": {
        "virtual tour": "true"
    },
    "message": "I would like to know how much my home is worth",
    "first_name": "Fluffy",
    "email": "cloud9@cloud.com",
    "advert_url": null,
    "advert_image": null,
    "advert_postcode": null,
    "advert_address": null,
    "address": "51 Asimov Place, Starbridge",
    "postcode": "N1 3JY",
    "appointment_availability": {
        "hours": [
            "2021-01-01T08:00:00.000Z",
            "2021-01-01T09:00:00.000Z"
        ]
    },
    "comparable_props": [
   
  {
            "address": "24 Northcloud Road",
            "beds": 4,
            "coords": {
                "x": -0.082372,
                "y": 51.5414
            },
            "date": "2020-08-14T00:00:00.000Z",
            "distance": 204,
            "months_ago": 12,
            "original_asking_price": 2750000,
            "price": 2450000,
            "time_taken_to_sell": 143
        },
  
  {
            "address": "48 Cloudways",
            "beds": 4,
            "coords": {
                "x": -0.086674,
                "y": 51.5427
            },
            "date": "2019-02-20T00:00:00.000Z",
            "distance": 129,
            "months_ago": 30,
            "original_asking_price": 3000000,
            "price": 2800000,
            "time_taken_to_sell": 61
      },
   
],
    "phone": "1234567812",
    "source": "ivt",
    "full_name": "Fluffy Cloud",
    "last_name": "Cloud",
    "created_at": "2021-09-10T08:41:15.783Z",
    "parent_id": null,
    "questionnaire": null,
    "stage": "Unread",
    "status": "New",
    "minimum_sale_estimation": 2000000,
    "average_sale_estimation": 2200000,
    "maximum_sale_estimation": 2400000,
    "minimum_rent_estimation": 5995,
    "average_rent_estimation": 6595,
    "maximum_rent_estimation": 7194,
    "gdpr_checkbox": true,
    "host": "https://www.yourdomain.ivt.com",
    "property_bedrooms": 4,
    "property_reference": null,
    "office_id": 3442,
    "office_name": "The Cloud Factory"
}

GET - Leads

The lead.pro API allows you to GET your leads associated with your account.

GET - https://api.lead.pro/api/v{version_number}/leads

Example Response

{
  "data": [{
    "id": 1,
    "title": "Sir",
    "first_name": "Richard",
    "last_name": "Branson",
    "email": "rbranson@virgin.com",
    "type": "vendor",
     "status" : 'UNREAD',
     "state" : 'CONTACTED'
    "source": "homepage",
    "phone": 07123456789,
    "address": "51 Asimov Place, Starbridge",
    "postcode": "N1 3JY",
    "advert_address": "51 Asimov Place, Starbridge",
    "advert_postcode": "N1 3JY",
    "parentId" : 2, 
    "advert_image": "https://www.site.com/result",
    "questionnaire" :  "[
      [“Do you have a property to sell?”, “yes”], 
       [“When would you like to move”, “Before july”]
    ]",
    "advert_url": "https://via.placeholder.com/150",
    "appointment_availability": {
      "hours": ["2021-01-01T08:00:00.000Z", "2021-01-01T09:00:00.000Z"],
    },
    "gdpr_checkbox" : false, 
    "officeId" : 345,
    "minimum_sale_estimation": 900000,
    "average_sale_estimation": 1000000,
    "maximum_sale_estimation": 1100000,
    "minimum_rent_estimation": 1500,
    "average_rent_estimation": 1667,
    "maximum_rent_estimation": 1833,
    "host": "https://www.leadpro.ivt.com",
    "property_bedrooms": 1,
    "property_reference":"8839787Prop2",
    "comparable_props" : null,
    "full_name": "Sir Ricard Branson"    "message": "When can we view and also get a valuation because your estimation was  good?",
    "meta": {
      "virtual tour": true
    },
{
    "id": 2,
    "title": "Mr",
    "first_name": "Alfred",
    "last_name": "Hitchcock",
    "email": "ahitchcock@scarymovie.com",
    "type": "vendor",
    "source": "homepage",
    "phone": 07123456789,
    "address": "45, Scary Films",
    "postcode": "HP 3JY",
    "advert_address": "45, Scary Film",
    "advert_postcode": "HP 3JY",
    "advert_image": "https://www.site.com/result",
    "advert_url": "https://via.placeholder.com/200",
    "appointment_availability": {
      "hours": ["2021-01-01T08:00:00.000Z", "2021-01-01T09:00:00.000Z"],
    },
    "full_name": "Mr Alfred Hitchook"    "message": "When can we view?",
    "meta": {
      "virtual tour": true
    },
   "meta" : {
      "limit" : 5,
      "start" : 2020-09-02,
      "end" : 2021-09-02,
      "officeId" : 1
     }
  }]
}

Filtering

You can filter leads by adding parameters to your endpoint

  1. Date

  2. Pagination

Filter By Date

Parameters

startTime - ISO 8601 UTC datetime - the start date for the range of leads

endTime - ISO 8601 UTC datetime - the end date for the range of leads

If you want to get your leads between 31/09/2020 and 21/03/2021 you would use the below example request

GET - https://api.lead.pro/api/v{version_number}/leads?date=start"2020-09-31"to=end"2021-03-21"

Pagination

Parameters

A limit on the number of objects to be returned, between 1 and 100.

If you wanted to get the 5 most recent leads you would set the limit parameter to 5

GET - https://api.lead.pro/api/v{version_number}/leads?limit=5"

Lead Structure

These are all the available fields on a lead

Field
Type
Example
Mandatory
Validation
id
Number
1
Yes
auto-generated
first_name
String
Richard
No
length : min 1 max 50
last_name
String
Smith
No
length : min 1 max 50
full_name
String
Richard Smith
Yes
length min 1 max 100
email
String
richard.smith@gmail.com
Yes
valid email address
phone
String
07123456789
Yes
length : max 255 ( only valid UK phone numbers will be called by autocaller)
type
String
vendor
Yes
either : 'sale', 'vendor', 'landlord', 'let', 'mortgage_request'
source
String
rightmove
No
you can submit a specific lead source only for /leads. If no source is submitted source will default to 'homepage'.
address
String
51 Asimov Place, Starbridge
Yes if Vendor/Landlord/ Mortgage
length : max 100
postcode
String
N1 3JY
Yes if Vendor/Landlord/ Mortgage
length : min 2 max 10
advert_address
String
51 Asimov Place, Starbridge
No
length : max 100
advert_postcode
String
N1 3JY
No
length : min 2 max 10
advert_url
String
https://www.site.com/result
No
length : max 255
advert_image
String
https://via.placeholder.com/150
No
length : max 255
title
String
Mr
No
length : min 1 max 10
message
String
When can I view this property?
No
length : max 255
appointment_availability
JSON
{ hours: [ 2021-04-22T10:00:00.000Z, 2021-05-22T10:00:00.000Z, ] }
No
max JSON byte size 2048, array values must be ISO 8601 date string
meta
Record<String, String>
{“virtual tour”: “true”}
No
max JSON byte size 1024, object with only string values
questionnaire
String[][]
[[“Do you have property to sell?”, “yes”], [“When would you like to move”, “Before july”]]
No
max JSON byte size 2048, each value in questionnaire should be array of strings with 2 elements
parentId
Number
54
No
Must be a valid parent lead
createdAt
String(ISO 8601)
2000-01-23T01:23:45.678+09:00
No
not writeable
status
String
active
No
must be UNREAD, IN_PROGRESS, NO_BUSINESS, BUSINESS, DUPLICATE
stage
String
complete
No
must be NEW CONTACTED, KEEP_IN_TOUCH, LOST, NOT_CONTACTABLE, WON VALUATION_BOOKED, INSTRUCTED, VIEWING_BOOKED, REGISTERED, DUPLICATE, SPAM DELETED,
gdpr_checkbox
Boolean
false
No
N/A
host
String
https://valuation.mydomain.com
No
N/A
average_sale_estimation
Number
10000
No
max 2 decimal places
average_rent_estimation
Number
1000000
No
max 2 decimal places
office_id
Number
567
No
Must be a valid office_id
property_reference
String
'your unique property reference'
If type 'sale' or 'let'
N/A
property_bedrooms
Number
4
If type 'vendor' or 'landlord'
N/A
office_name
String
Oxford
No
Not writeable
minimum_sale_estimation
Number
10000
No
max 2 decimal places
maximum_sale_estimation
Number
233333
No
max 2 decimal places
minimum_rent_estimation
Number
55444333
No
max 2 decimal places
maximum_rent_estimation
Number
343444455
No
max 2 decimal places
comparable_props
Object[]
{ "address": "68 Uftwen Road", "beds": 4, "coords": { "x": -0.082544, "y": 51.5422 }, "date": "2021-02-10T00:00:00.000Z", "distance": 166, "months_ago": 7, "original_asking_price": 2150000, "price": 1782500, "time_taken_to_sell": 76 }
No
Not writeable

Contents