ZILLOW RENTALS
Lead Delivery API Guide
Dec 11, 2024
Table of Contents
Audience................................................................................................................................................. 2
Use Case.................................................................................................................................................. 2
Deliverable..............................................................................................................................................2
Format..................................................................................................................................................... 3
Header & Payload Example.........................................................................................................................3
Header.....................................................................................................................................................3
Payload (URL Encoded)......................................................................................................................... 3
Field Details................................................................................................................................................... 4
Implementation..................................................................................................................................... 6
Applying & Triggering the API..................................................................................................................... 6
Routing Leads................................................................................................................................................6
Triggering the Lead API......................................................................................................................... 6
But what if you are not the feed provider and the feed ID is unknown?.................6
Multi-Family Listings..............................................................................................................................6
Security...........................................................................................................................................................6
Security Header/Token.................................................................................................6
OAuth...........................................................................................................................6
Lead Delivery Responses.............................................................................................................................7
Success.................................................................................................................................................... 7
Endpoint Failure & Lead Redelivery.................................................................................................... 7
Testing............................................................................................................................................................ 7
Deploying to Production..............................................................................................................................8
Third-Party Lead API’s........................................................................................................................... 8
Audience
This is a technical document for web developers and project managers tasked with creating an API
endpoint to receive lead inquiries from listings published on Zillow Rentals platforms.
Use Case
Lead Delivery APIs are used to ingest lead data directly into a CRM or lead management system.
Deliverable
HTTP Post callback API endpoint capable of receiving lead data from Zillow Rentals.
2
Format
Header & Payload Example
Header
POST /request HTTP/1.1
content-type: application/x-www-form-urlencoded; charset=UTF-8
host: [Link]
content-length: 277
Payload (URL Encoded)
Unset
listingId=p01023&name=Rachel%20Lee&email=rachel%[Link]&phone=555-555-8378&
movingDate=20160926&numBedroomsSought=3&numBathroomsSought=2&message=Looking%20
for%20spacious%203%20bedroom%20apartment%20or%20house&listingStreet=246%20Tenne
ssee%20Avenue&listingUnit=C102&listingCity=Sunnyvale&listingPostalCode=94086&li
stingState=CA&listingContactEmail=propertymanager%[Link]&n
eighborhoods=%5B%22Park%20Merced%22%2C%20%22Sunset%22%5D&propertyTypesDesired=%
5B%22apartment%22%2C%20%22house%22%2C%20%22townhouse%22%5D&leaseLengthMonths=12
&introduction=Hello%20my%20name%20is%20Rachel&smoker=false&parkingTypeDesired=r
equired&incomeYearly=150000&creditScoreRangeJson=%7B%22creditScoreMin%22%3A675%
2C%22creditScoreMax%22%3A690%7D&movingFromCity=San%20Francisco&movingFromState=
CA&moveInTimeframe=asap&reasonForMoving=high%rent&employmentStatus=employed&job
Title=Software%Engineer&employer=Zillow&employmentStartDate=2015-09-27&employme
ntDetailsJson=%5B%7B%22jobTitle%22%3A%22Software%20Engineer%22%2C%22employer%22
%3A%22Google%22%2C%22startDate%22%3A%222012-07-21%22%2C%22endDate%22%3A%222015-
09-20%22%7D%5D&petDetailsJson=%5B%7B%22type%22%3A%22dog%22%2C%22breed%22%3A%22L
ab%22%2C%22size%22%3A%22huge%22%2C%22weightPounds%22%3A50%2C%22description%22%3
A%22Really%20awesome%20lab%22%7D%2C%7B%22type%22%3A%22cat%22%2C%22size%22%3A%22
small%22%2C%22description%22%3A%22Really%20annoying%20cat%22%7D%5D&leadType=tou
rRequest
3
Field Details
Field Name Notes Example
listingId Feed sourced listing ID listingId=p01023
name Renter name name=Rachel Lee
Email Renter’s email email=rachel@[Link]
phone Renter phone number phone=555-555-8378
movingDate YYYYMMDD (omitted if null) movingDate=20230916
numBedroomsSought Integer, 0 is studio numBedroomsSought=3
numBathroomsSought Integer numBathroomsSought=2
message Text blob from lead form message=Looking for spacious
3 bedroom apartment or
house
listingStreet Listing Street Address listingStreet=246 Tennessee
Avenue
listingUnit Listing Unit Number listingUnit=C102
listingCity Listing City listingCity=Sunnyvale
listingPostalCode Listing Zip Code listingPostalCode=94086
listingState Listing State Code listingState=CA
listingContactEmail Contact email address for this listingContactEmail=propertym
listing (not used when sending anager@HaywardParkApart
leads via API). [Link]
neighborhoods Neighborhoods of interest neighborhoods=["Park
Merced", "Sunset"]
propertyTypesDesired Property types of interest propertyTypesDesired=["apart
ment", "house", "townhouse"]
leaseLengthMonths lease duration leaseLengthMonths=12
introduction Text blob from renter profile introduction=Hello my name is
Rachel
smoker Boolean smoker=false
parkingTypeDesired Enumerated: ‘required’, ‘not parkingTypeDesired=required
needed’
incomeYearly Yearly income in US dollars incomeYearly=150000
creditScoreRangeJson Credit Score creditScoreRangeJson={"credit
ScoreMin":675,"creditScore
4
Max":690}
movingFromCity Renter origination city movingFromCity=San Francisco
movingFromState Renter origination state movingFromState=CA
moveInTimeframe Enum: 'asap', 'flexible', 'week', moveInTimeframe=asap
'month', 'twoWeeks',
'twoMonths'
employmentStatus Enumerated: 'unemployed', employmentStatus=employed
'student', 'retired', 'employed'
jobTitle Job Title jobTitle=Software Engineer
employer Employer employer=Zillow
employmentStartDate yyyy-mm-dd employmentStartDate=2020-0
9-27
employmentDetailsJson Employment Details employmentDetailsJson=[{"job
Title":"Software
Engineer","employer":"Google",
"startDate":"2012-07-
21","endDate":"2015-09-20"}]
petDetailsJson Renter pet details petDetailsJson=[{"type":"dog","
breed":"Lab","size":"huge","
weightPounds":50,"description
":"Really awesome
lab"},{"type":"cat","size":"small"
,"description":"Really annoying
cat"}]
leadType Lead enumerated types: leadType=tourRequest
question
tourRequest
applicationRequest
providerModelId Model ID for multifamily providerModelId=0
listings, otherwise 0
Bold Italic indicates that the lead payload will always include this data.
5
Implementation
Applying & Triggering the API
Following are common ways that lead APIs can be applied or triggered:
● Feed - applied to all listings within a specific feed.
● Company ID - applied to a specific company ID within a feed.
● Email Domain - API is triggered for any listings with a specific contact email domain.
Note that we can apply the API based on other criteria, but these are the most common ways to
automatically trigger an API.
Routing Leads
Triggering the Lead API
If the listing ID from the feed is available to the API recipient, routing the lead to the correct listing is
trivial, since that ID is unique by listing and can easily be used for routing.
Even for multi-famil
But what if you are not the feed provider and the feed ID is unknown?
You can match the leads to a listing by address, but not confidently because the address contains
multiple components that are parsed separately and the address may not match exactly.
If the lead API is being triggered by email domain, one option is to provide a unique prefix for each
property’s contact email, and use that email prefix to route leads, i.e. propertyId@[Link]
where the domain triggers the api, and the prefix “propertyId” is the unique listing ID used for
routing the lead to the correct property.
Multi-Family Listings
Listings can be routed by the listing ID, but for multi-family listings, you may also want to match
leads to specific floorplans or available units within the listing.
In this case, the model ID from the feed is provided within the lead payload when a lead is made on
a specific unit or floorplan. This ID is taken from the feed, so it is only relevant where the feed
provider is also receiving and routing the lead via the API.
Security
By default the API is configured without a security header or security token.
Security Header/Token
Our lead delivery API supports a static security header and/or token which we can configure & test
prior to deploying to production.
OAuth
Our lead delivery API does not currently support the OAuth framework.
6
Lead Delivery Responses
Success
When the lead is delivered successfully, the endpoint must respond with the standard http 200 or
202 success code. Note that the 200 success code should indicate that the lead was received
successfully by the endpoint and it was able to be parsed and placed within your data-store.
If you respond with either 202/200 success, but the lead can’t be routed, we will not attempt to
redeliver the lead if the routing fails, so you may want to respond with a descriptive failure code if
the lead data is received successfully, but cannot be parsed/routed.
Endpoint Failure & Lead Redelivery
If a lead is not received successfully or is received but cannot be handled by the parser, the endpoint
should respond with a http failure code as well as information about the failure.
A failed delivery will trigger automatic redelivery. This means that if your endpoint is unavailable for
any reason, intentional or not, as long as you respond with an error message, your leads will not be
lost, and will automatically be redelivered once it is available again.
Entertaining list of http response codes: [Link]
Examples of Failure Responses we receive:
Unset
HTTP/1.1 400 Bad Request,
{"errorCode":"INVALID_TRACKING_EMAIL","errorMessage":"Property with
tracking email 'email@[Link]' does not exist"}
HTTP/1.1 500 Internal Server Error, {"errorMessage":"received error
status code 500"}
{"status":"400 - Bad Request","messages":["This property (xxxxxx) does not have
a valid e-mail address or it has recently been deleted. This lead will not
reach the property manager."],"code":"40002","moreInfo":""}
Could not identify the property.
We review lead delivery errors daily and detailed failure responses make it easier to troubleshoot
and resolve lead errors.
Testing
Leads can be delivered via our test platform so there is no need to create or modify production
listings for testing purposes.
Once you are ready to test your endpoint, we can configure it on our test environment and you can
send and receive leads.
7
Deploying to Production
Once you are satisfied that leads are being successfully delivered to your endpoint and ingested into
your lead management platform, we can deploy the API to production.
Third-Party Lead API’s
Zillow Rentals supports many third-party lead delivery API’s. Please ask to see if your provider’s API is
already supported.