Lead Push Service

The Zoopla lead push service sends leads in real-time to a destination of your choosing.

The service has resilience strategies built-in. This means that should your consuming service be down for any reason we will continue to retry sending leads until such a time as your service is back up and running, or 24 hours have elapsed. Once the 24 hours have elapsed, we retain leads in our system for a further 29 days, for a total of 30. There is currently no mechanism to automatically replay leads after the initial 24 hour retry window, however if the recipient endpoint suffers a prolonged outage then please get in contact and we may be able to help.

Endpoints

The push service requires you to provide a data-recipient endpoint and an optional authentication endpoint (see Auth section below). A single recipient endpoint can be used for receiving all leads data, or separate endpoints for applicant and appraisal leads can be configured if required. If a single endpoint is used, applicant and appraisal leads will have different top-level keys in order to distinguish them; appraisal leads have a top level key of "appraisal" and applicant leads have a top level key of "applicant".

Auth

We support both OAuth2 and API Key authentication methods (NB the REST API is OAuth2 only). For OAuth2 we will require the following:

Client id
Client secret
OAuth2 token endpoint
Audience (dependent on configuration)

For API Key authentication we do not need any details except the key itself. Both methods use the Authorization header when making the POST request.

NB currently we only support the client_credentials grant type. One limitation we are aware of is that Salesforce does not support this flow and so anyone integrating with Salesforce should opt for the Poll mechanism at this time.

Below is an example request that we will send when getting an access token from the OAuth2 token endpoint you provide:

curl --request POST \
  --url ${your-token-endpoint} \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=${your-client-id} \
  --data client_secret=${your-client-secret}

Filters

The push service can be configured to only send certain kinds of leads to an endpoint. There are four such configuration options, all of which can be set to true or false;

applicant leads, ie leads from consumers looking to buy or rent properties
appraisal leads, ie leads from consumers looking to sell or let properties
sales leads, ie leads from consumers looking to buy or sell properties
lettings leads, ie leads from consumers looking to rent or let properties

Payloads

The push service sends an HTTP POST request per lead categorised as either an applicant or an appraisal lead. The payload for each can be distinguished by its top level key, "applicant" or "appraisal" respectively - see the example payloads below:

Example Applicant Payload

{
  "applicant": {
    "id": "dcec2eae-2002-4198-bc1d-fa32e9fdc389",
    "contact": {
      "firstName": "Joe",
      "lastName": "Bloggs",
      "phoneNumber": "00000 000000",
      "email": "[email protected]",
      "preferences": {
        "method": "CONTACT_METHOD_PHONE",
        "time": "TIME_PREFERENCE_AFTERNOON"
      }
    },
    "createdAt": "2021-04-12T15:19:53Z",
    "intent": "APPLICANT_INTENT_BUY",
    "enquiryType": "ENQUIRY_TYPE_SALES",
    "message": "Hello\r\n\r\nWe're very interested in viewing this property",
    "propertyUse": "PROPERTY_USE_RESIDENTIAL",
    "isOverseas": false,
    "portalLeadId": "00000000",
    "portalBranchId": "00000",
    "portalCompanyId": "00000",
    "sourceBranchId": "000000",
    "viewingTimes": [
      {
        "earliest": "2021-04-18T12:00:00Z",
        "latest": "2021-04-18T17:00:00Z"
      }
    ],
    "organiseViewing": true,
    "requestPropertyDetails": false,
    "consumerSituation": "CONSUMER_SITUATION_FIRST_TIME_BUYER",
    "consumerPostcode": "NW3 3DN",
    "recipientEmail": "[email protected]",
    "leadSource": "APPLICANT_SOURCE_ZOOPLA_WEBSITE",
    "portalSource": "APPLICANT_PORTAL_SOURCE_LISTING",
    "searchCriteria": {
      "location": {
        "alias": "test-alias",
        "area": "test-area",
        "areaStreet": "test-area-street",
        "country": "test-country",
        "countyArea": "test-county-area",
        "incode": "test-incode",
        "outcode": "test-outcode",
        "postTown": "test-post-town",
        "postalArea": "test-postal-area",
        "region": "test-region",
        "district": "test-district",
        "countryCode": "test-country-code"
      },
      "radius": 5,
      "minimumBedrooms": 1,
      "maximumBedrooms": 11,
      "minimumPrice": 999999,
      "maximumPrice": 9999999,
      "priceFrequency": "RENT_FREQUENCY_PER_WEEK",
      "propertyType": "PROPERTY_TYPE_HOUSEBOAT",
      "propertySubType": "Terraced"
    },
    "listingDetails": {
      "id": "000000",
      "bedrooms": 2,
      "bathrooms": 1,
      "receptions": 1,
      "lifeCycleStatus": "LIFE_CYCLE_STATUS_FOR_SALE",
      "address": {
        "propertyNumberOrName": "1",
        "streetName": "Wadham Gardens",
        "locality": "",
        "townOrCity": "LONDON",
        "postcode": "PO5T C0D3",
        "countryCode": "GB"
      },
      "pricing": {
        "transactionType": "TRANSACTION_TYPE_SALE",
        "currencyCode": "gbp",
        "price": 123456.78,
        "rentFrequency": "RENT_FREQUENCY_PER_MONTH"
      },
      "propertyId": "000000",
      "propertyType": "PROPERTY_TYPE_FLAT",
      "sourceBranchId": "000000",
      "sourceId": "000000",
      "url": "https://www.zoopla.co.uk/for-sale/details/58391988",
      "images": [
        {
          "original": "https://lc.zoocdn.com/324dafa495e710565615f2bf329b3b56265c08ba.jpg",
          "cdnUrl": "https://lc.zoocdn.com/",
          "filename": "324dafa495e710565615f2bf329b3b56265c08ba.jpg"
        }
      ]
    }
  }
}

Example Appraisal Payload

{
  "appraisal": {
    "id": "f24dd54d-1425-48f4-8d31-3c79663ae97e",
    "enquiryType": "ENQUIRY_TYPE_SALES",
    "contact": {
      "firstName": "Joe",
      "lastName": "Bloggs",
      "phoneNumber": "00000000",
      "email": "[email protected]",
      "preferences": {
        "method": "CONTACT_METHOD_PHONE",
        "time": "TIME_PREFERENCE_AFTERNOON"
      }
    },
    "createdAt": "2021-03-29T12:40:59Z",
    "intent": "APPRAISAL_INTENT_SELL",
    "message": "I am looking to sell my home",
    "propertyUse": "PROPERTY_USE_RESIDENTIAL",
    "isOverseas": false,
    "portalLeadId": "000000",
    "portalBranchId": "000000",
    "portalCompanyId": "00000",
    "sourceBranchId": "000000",
    "propertyDetails": {
      "propertyId": "000000",
      "bedrooms": 2,
      "bathrooms": 2,
      "receptions": 1,
      "floorArea": 96,
      "tenure": "Leasehold",
      "propertyType": "PROPERTY_TYPE_FLAT",
      "estimate": {
        "lowerRange": 100000,
        "upperRange": 200000,
        "value": 150000,
        "confidence": 90,
        "confidenceBand": "CONFIDENCE_BAND_HIGH"
      },
      "lastSalePrice": 300000,
      "latitude": 0,
      "longitude": -0,
      "address": {
        "line1": "Example Flat",
        "line2": "Example Road",
        "line3": "Example Area",
        "town": "Town",
        "county": "County",
        "postcode": "SW1 1AA"
      },
      "energy": {
        "efficiency": 86,
        "rating": "B"
      }
    },
    "justCurious": false,
    "recipientEmail": "[email protected]",
    "leadSource": "APPRAISAL_SOURCE_ZOOPLA_WEBSITE",
    "portalSource": "APPRAISAL_PORTAL_SOURCE_ASKANAGENT"
  }
}

Example Push Request

Using the access token we have received above and depending on the payload of the lead we're aiming to push we will then send the following request:

curl --request POST \
  --url ${your-leads-endpoint} \
  --header 'content-type: application/json' \
  --body ${example-payload}

Notes

For field definitions please see here