Need help? Contact support
Dashboard
Introduction
Users
Webhooks
Portals
Emails
Push Notifications
CSV Export
Instant Valuation Tool
Quickstart
Custom domains
Lead Responder
Quickstart
Autocaller
Quickstart
Integrations
Facebook
Google Analytics
Jupix
MailChimp
Reapit
Zapier
Your Website
Reapit Integration - Internet Registrations
API
Documentation

Inbound Lead 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/v103/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/v103/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

‘vendor’ - used to indicate the lead has a property to sell.

‘landlord’ - used to indicate the lead has a property to rent.

**IMPORTANT - if type is 'vendor' or 'landlord' then postcode is a mandatory field.

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', '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 campaign data for reporting
property_type
string
detached, semi-detached, terraced, flat-maisonette
indicate the type of property user/lead has or interested in

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/v103/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,
    "valuation_status" : "Success",
    "gdpr_checkbox": true,
    "host": "https://www.yourdomain.ivt.com",
    "property_bedrooms": 4,
    "property_reference": null,
    "office_id": 3442,
    "office_name": "The Cloud Factory"
}

Note*

There may be a case where our API can not find an estimated property valuation for the address provided but the request does not fail and a lead is created in the dashboard.

To handle this we have a valuation_status to highlight the status of the lead created.

If no valuation can be found then valuation status will be set to the according valuation_status reason and all fields relating to a property valuation will be null or empty on the response.

If the API does find an estimated property value then valuation_status will be set to 'Success'.

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
Yes if sale/let and no office_id is specified
length : max 100
advert_postcode
String
N1 3JY
Yes if sale/let and no office_id is specified
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 8192 characters
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'
length: max 50 char
property_bedrooms
Number
4
No
N/A
office_name
String
Oxford
No
Read only
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
international
boolean
true
No
N/A
account_id
Number
9999
No
Not writeable
account_name
String
Skyline Estates
No
Not writeable
office_id
Number
9999
No
Not writeable
office_name
String
Oxford
No
Not writeable
referred_by_office_id
Number
222
No
Not writeable
referred_by_office_name
string | null
'Oxford'
No
Not writeable
referred_by_account_id
number | null
334
No
Not writeable
referred_by_account_name
string | null
'Lead Pro Ltd'
No
Not writeable
property_type
string | null
detached
No
only one of detached, semi-detached, terraced, flat-maisonette

Contents
GET - Offices
POST - Lead
Metadata field
POST - Instant Valuation Lead
Lead Structure