Introduction
This API is used by agents to retrieve leads. Applicant and Appraisal leads are available via different endpoints and return data in separate structures.
Integration URLs:
- Production URL: services.zoopla.co.uk
Authentication:
The REST API uses OAuth2 authentication and at this time alternatives are not available. The authentication endpoint is https://services-auth.services.zoopla.co.uk - please see example request below:
curl --request POST \
--url https://services-auth.services.zoopla.co.uk/oauth2/token \
--header ‘Content-Type: application/x-www-form-urlencoded’ \
--data grant_type=client_credentials \
--data client_id=123 \
--data client_secret=456 \
--data audience=https://services.zoopla.co.uk
Your client_id and client_secret will be provided to you by us. The audience will be the relevant integration URL, as specified above, and grant_type will always be client_credentials. A successful response will provide a token which can then be added under an Authorization header in requests to the data endpoint. The fields above are all form encoded URL data and are no longer provided via the JSON body.
Service busy
There are times when you may receive a 429 error if the service is especially busy. In this instance, the best thing to do is to wait and retry.
To try and mitigate this error, the best practice is to ensure that you're using your access tokens correctly.
When the access token is returned it has an expiry time, try to ensure that you are caching this token for the length of its expiry time and only requesting a new one when the old has expired. This will reduce the number of calls required and free up the services
Poll Requests
By default, the API will return all leads submitted in the last 24 hours, however we retain leads for 30 days. Query parameters can be added to the request URL in order to only retrieve leads from a specific time period, please refer to either the /appraisal-leads or /applicant-leads specs for more information.
Filters
As mentioned above, if you have more than one branch, brand, company, or group configured for your setup then the API will require you to filter based on a singular branch, brand, company, or group id.
These IDs are specifically Zoopla internal IDs so we are able to retrieve the correct leads for your request.
Response Objects
If you are unsure about any of the fields that appear in the 200 response, we have an exhaustive list of the available fields, and their definitions in the Field Definitions. The success response can also be seen in the Push Service section as they share a payload.
An example error response would be the following:
{
"errors": [
{
"message": "product not one of available enum values",
"code": "invalid_valuation_lead_product",
"links": []
}
]
}
Contact
For any enquiries please contact the Zoopla Leads Team