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.

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.