Zillow Confidential
This is the Zillow Mortgages JSON lender contact notification API.
NOTE: Respond with non-2xx HTTP status code to indicate failure.
Name | Type | Attributes | Description |
---|---|---|---|
id | ContactId |
The ID of this contact in the Zillow contact system. Example: "LC-EXAMPLE" |
|
created | datetime |
The date and time when the contact was created, in ISO-8601 format. Example: "2015-01-22T10:30:00-08:00" |
|
type | ZillowLenderContactType |
The type of the contact. New contact types may be added in the future. |
|
source | string |
A human-readable description of the source of the contact. This field may contain any text and should not be relied on for business logic. |
|
brand | ZillowGroupBrand |
The brand associated with the user experience through which the contact was initiated. New contact brands may be added in the future. |
|
channel | ZillowLenderContactChannel |
The channel through which the contact was initiated. New contact channels may be added in the future. |
|
mvp | bool |
|
For internal use only. |
affiliate | bool |
|
For internal use only. |
price | float |
The price charged for the contact, in dollars. |
|
recipient | ZillowLenderContactRecipient |
Information about the lender who is the intended recipient of the contact. |
|
sender | ZillowLenderContactSender |
Information about the sender of the contact. |
|
details | ZillowLenderContactDetails |
Additional details provided by the sender. |
|
quote | ZillowLenderContactLoanQuote |
|
Information about the loan quote which the contact is in reference to, if any. |
Name | Type | Attributes | Description |
---|---|---|---|
externalContactReference | string |
|
The optional external contact reference ID. |
applicationURL | string |
|
An optional contact-specific application URL. This should be a custom link to start an application based on the provided contact information. This URL must use an https:// scheme. |
The action returns no custom error codes.
Encoded contact ID, like "LC-EXAMPLE".
Type |
---|
string |
Email address.
Type | Attributes |
---|---|
string |
|
Encoded lender ID (aka ZUID), like "ZUexampleexample".
Type |
---|
string |
Encoded quote ID, like "ZQ-EXAMPLE".
Type |
---|
string |
Encoded loan request ID, like "ZR-EXAMPLE".
Type |
---|
string |
Encoded user ID (aka ZUID), like "ZUexampleexample".
Type |
---|
string |
Additional details provided by the sender of a contact.
All details are optional. If a detail is not appropriate for the sender's loan scenario, or was not specified by the sender, then it will not be included.
Name | Type | Attributes | Description |
---|---|---|---|
acceptPrepaymentPenalty | bool |
|
Whether the borrower is willing to accept a loan with a pre-payment penalty. |
agentBusinessName | string |
|
The business name of the real-estate agent, associated with the contact. |
agentEmailAddress | string |
|
The email address of the real-estate agent, associated with the contact. |
agentFirstName | string |
|
The first name of the real-estate agent, associated with the contact. |
agentId | UserId |
|
The Zillow user ID of the real-estate agent, associated with the contact. Example: "ZUexampleexample" |
agentLastName | string |
|
The last name of the real-estate agent, associated with the contact. |
agentPhoneNumber | string |
|
The first name of the real-estate agent, associated with the contact. Example: "(206) 555-1212" |
annualIncome | int |
|
The borrower's annual income, in dollars. If there is a co-borrower, this value represents the total of both borrowers' annual income. |
cashOut | int |
|
The amount that the borrower wants to take out as part of a refinance, in dollars. This value will only be present if wantsCashOut is true, and even then may not be present if it was not explicitly specified by the sender. |
city | string |
|
The name of the city where the property is located. Example: "Seattle" |
county | string |
|
The name of the county where the property is located. Example: "King" |
closingTimelineDays | int |
|
The borrower's estimated days until closing. |
creditScoreHigh | int |
|
The higher range of the borrower's self-reported credit score range. If there is a co-borrower, this value represents the lowest high between the borrowers' credit score ranges. |
creditScoreLow | int |
|
The lower range of the borrower's self-reported credit score range. If there is a co-borrower, this value represents the lowest low between the borrowers' credit score ranges. |
creditScoreRange | CreditScoreRange |
|
This field is DEPRECATED. Please use creditScoreLow and creditScoreHigh. The borrower's self-reported credit score range. If there is a co-borrower, this value represents the lower of the borrowers' credit score ranges. |
currentBacker | KnownBacker |
|
The backer of the borrower's current mortgage. This value will only be present if loanPurpose is Refinance, and even then may not be present if it was not explicitly specified by the sender. |
currentBalance | int |
|
The current mortgage balance, in dollars. |
debtToIncomePercent | float |
|
The borrower's debt-to-income ratio (DTI), as a percentage. This value is equivalent to 100 * (monthlyDebts * 12) / annualIncome. |
desiredPrograms | LoanProgram [] |
|
Loan programs which the borrower is interested in. |
displayedCreditScoreRange | string |
|
The borrower's self-reported credit score range as it was displayed to the borrower. If there is a co-borrower, this value represents the lower of the borrowers' credit score ranges. |
downPayment | int |
|
The down payment amount, in dollars. |
fhaStreamlineEligible | bool |
|
Whether the borrower is eligible for an FHA Streamline loan. |
firstTimeBuyer | bool |
|
Whether the borrower is a first-time buyer. |
harpEligible | bool |
|
Whether the borrower is eligible for a HARP refinance loan. |
hasAgent | bool |
|
Whether the borrower is working with a real-estate agent. |
hasBankruptcy | bool |
|
Whether the borrower or co-borrower has declared bankruptcy in the last 7 years. |
hasCoborrower | bool |
|
Whether there is a co-borrower. |
hasForeclosure | bool |
|
Whether the borrower or co-borrower has had a foreclosure in the last 7 years. |
hasSecondMortgage | bool |
|
Whether the borrower or co-borrower has a second mortgage. |
homeOwner | bool |
|
Whether the borrower or co-borrower currently owns a home. |
isDpaEligible | bool |
|
Whether the borrower is eligible for Down Payment Assistance This value will only be present if its value is true. |
isZGMIPaLead | bool |
|
Whether the borrower info was forwarded to PA L2 Leads API. This value will only be present if its value is true. |
journeyStage | JourneyStage |
|
The borrower's current stage in her purchase journey. |
loanAmount | int |
|
The desired loan amount, in dollars. |
loanPurpose | LoanPurpose |
|
The loan purpose. |
loanToValuePercent | float |
|
The borrower's loan-to-value ratio (LTV), as a percentage. This value is equivalent to 100 * loanAmount / propertyValue. |
message | string |
|
A free-form message from the sender to the lender. |
monthlyDebts | int |
|
The borrower's monthly debts, in dollars. If there is a co-borrower, this value represents the total of both borrowers' monthly debts. |
newConstruction | bool |
|
Whether the property is new construction. This value will only be present if loanPurpose is Purchase, and even then may not be present if it was not explicitly specified by the sender. |
preferredLanguage | Language |
|
The borrower's preferred language of communication. This value will only be present it the borrower provided a preferred language. |
propertyAddress | string |
|
The address of the property as a single string. The individual components of the address can be accessed via the streetAddress, city, stateAbbreviation, and zipCode details. Example: "123 Main St Seattle, WA 98102" |
propertyType | PropertyType |
|
The property type. |
propertyUse | PropertyUse |
|
The property use. |
propertyValue | int |
|
The property value. For a purchase loan, this is the purchase price. |
quoteId | QuoteId |
|
The Zillow ID of the loan quote associated with the contact. Example: "ZQ-EXAMPLE" |
requestId | RequestId |
|
The Zillow ID of the loan request associated with the contact. Example: "ZR-EXAMPLE" |
selfEmployed | bool |
|
Whether the borrower or co-borrwer is self-employed. |
sellingHome | bool |
|
Whether the borrower is also selling a home. |
stateAbbreviation | StateAbbreviation |
|
The two-letter abbreviation of the state where the property is located. Example: "WA" |
streetAddress | string |
|
The street address of the property. Example: "123 Main St" |
totalAssets | int |
|
The borrower's total assets, in dollars. If there is a co-borrower, this value represents the total of both borrowers' assets. |
wantsCashOut | bool |
|
Whether the borrower wants to take out cash as part of a refinance. |
vaEligible | bool |
|
Whether the borrower is eligible for VA loans. |
vaFirstTimeUser | bool |
|
Whether the borrower is a first-time VA loan user. This value will only be present if vaEligible is true, and even then may not be present if it was not explicitly specified by the sender. |
vaHasDisability | bool |
|
Whether the borrower has a VA-related disability. This value will only be present if vaEligible is true, and even then may not be present if it was not explicitly specified by the sender. |
veteranType | VeteranType |
|
The borrower's veteran type. This value will only be present if vaEligible is true, and even then may not be present if it was not explicitly specified by the sender. |
yearPurchased | int |
|
The year that the property was purchased. This value will only be present if loanPurpose is not Purchase, and even then may not be present if it was not explicitly specified by the sender. |
zipCode | string |
|
The ZIP code where the property is located. |
Information about a loan quote.
Name | Type | Attributes | Description |
---|---|---|---|
rate | float |
The interest rate of the loan, as a percentage. |
|
apr | float |
|
The annual percentage rate of the loan. This value will only be present if it was specified by the lender. The APR value displayed to the borrower is included as a field inside the "zillow" sub-structure. |
termMonths | int |
The number of months in the term of the loan. |
|
dueInMonths | int |
The number of months until the loan is due. |
|
interestOnlyMonths | int |
|
The number of months that the loan is interest-only. This value will only be present if the loan has an interest-only period. |
lockDays | int |
The number of days that the lender assumes the rate will be locked for. |
|
hasPrepaymentPenalty | bool |
|
Whether the loan has a prepayment penalty. This value will only be present if its value is true. |
jumbo | bool |
|
Whether the loan is a non-conforming jumbo loan. This value will only be present if its value is true. |
harp | bool |
|
Whether the loan is a HARP loan. This value will only be present if its value is true. |
lenderPaidMortgageInsurance | bool |
|
Whether the lender will pay the mortgage insurance on the loan. This value will only be present if its value is true. |
annualMortgageInsurancePercent | float |
|
The annual mortgage insurance premium, as a percentage. This value will only be present if it was specified by the lender. The monthly mortgage insurance amount displayed to the borrower is included as a field inside the "zillow" sub-structure. |
arm | ZillowLenderContactLoanQuoteARMDetails |
|
The ARM-specific details of an adjustable rate loan quote. |
fha | ZillowLenderContactLoanQuoteFHADetails |
|
The FHA-specific details of an FHA loan quote. |
va | ZillowLenderContactLoanQuoteVADetails |
|
The VA-specific details of a VA loan quote. |
currentBackerMustBeFannieMae | bool |
|
Whether the loan requires that the borrower's current loan is backed by Fannie Mae. This value will only be present if its value is true. |
currentBackerMustBeFreddieMac | bool |
|
Whether the loan requires that the borrower's current loan is backed by Freddie Mac. This value will only be present if its value is true. |
fees | ZillowLenderContactLoanQuoteFeeDetails [] |
HUD and other fees associated with the loan. |
|
lenderCredit | int |
|
The lender credit amount, if any, associated with the, in dollars. This value will only be present if the lender specified a fixed lender credit amount. |
lenderCreditPercent | float |
|
The lender credit amount, if any, associated with the loan, as a percentage. This value will only be present if the lender specified a lender credit as a percentage of the loan amount. |
maxAllowedLTV | int |
|
The maximum loan-to-value percentage allowed. |
zillow | ZillowLenderContactLoanQuoteZillowDetails |
Information about the quote that was displayed to the borrower but which was not necessarily specified explicitly by the lender. |
Loan quote details specific an ARM loan quote.
Name | Type | Description |
---|---|---|
fixedRateMonths | int |
The number of months until the rate becomes adjustable. |
adjustmentPeriodMonths | int |
The interval between rate adjustments, in months. |
index | ARMIndex |
The ARM index type. |
margin | float |
The ARM quote margin. |
initialCap | float |
The initial adjustment cap. |
periodicCap | float |
The periodic adjustment cap. |
lifetimeCap | float |
The lifetime adjustment cap. |
Information about a single fee associated with a loan quote.
Name | Type | Attributes | Description |
---|---|---|---|
hudLine | int |
The HUD line corresponding to this fee. |
|
name | string |
The fee name. |
|
amount | int |
|
The fee amount, in dollars. This value will only be present if the lender specified the fee as a dollar amount. |
percent | float |
|
The fee amount, as a percentage. This value will only be present if the lender specified the fee as a percentage of the loan amount. |
Loan quote details specific to an FHA loan quote.
Name | Type | Attributes | Description |
---|---|---|---|
upfrontPremiumPercent | float |
The FHA upfront premium, as a percentage. |
|
annualPremiumPercent | float |
The annual insurance premium, as a percentage. |
|
streamline | bool |
|
Whether the quote is for an FHA Streamline loan. |
Loan quote details specific to a VA loan quote.
Name | Type | Description |
---|---|---|
fundingFeePercent | float |
The VA funding fee, as a percentage. |
Information associated with a loan quote that was not explicitly provided by the lender that submitted the quote, but which was computed by Zillow and displayed to the borrower.
Name | Type | Description |
---|---|---|
created | datetime |
The date and time when the quote was created, in ISO-8601 format. Example: "2015-01-22T10:30:00-08:00" |
apr | float |
The annual percentage rate of the loan that was shown to the borrower. This value may not match the value submitted by the lender, if Zillow determined that the lender-submitted value did not adequately reflect fees or other inputs to the loan. |
upfrontCost | int |
The upfront cost of the loan, in dollars, that was shown to the borrower. |
monthlyPrincipalAndInterest | int |
The amount of monthly principal and interest, in dollars, that was shown to the borrower. |
monthlyMortgageInsurance | int |
The amount of monthly mortgage insurance, in dollars, that was shown to the borrower. This value may have been specified by the lender or estimated by Zillow. |
points | float |
The number of points that was shown to the borrower. |
feesRolledIntoLoanAmount | int |
The amount of upfront fees that the borrower will probably choose to roll into the loan amount, in dollars. This value typically includes the upfront premium on FHA loans and the funding fee on VA loans. |
loanAmount | int |
The final loan amount implied by this quote, in dollars. This value is equal to the nominal loan amount implied by the borrower's loan request, plus the value of the feesRolledIntoLoanAmount field. |
Information about the lender who is the intended recipient of a contact.
Name | Type | Attributes | Description |
---|---|---|---|
emailAddress | EmailAddress |
|
The email address, if known. |
phoneNumber | string |
|
The phone number, if known. Example: "(206) 555-1212" |
firstName | string |
|
The first name, if known. |
middleName | string |
|
The middle name, if known. |
lastName | string |
|
The last name, if known. |
suffix | string |
|
The name suffix, if known. |
lenderId | LenderId |
The lender's Zillow user ID. Example: "ZUexampleexample" |
|
nmlsLicense | string |
|
The lender's NMLS license, if known. |
Information about the sender of a contact.
Name | Type | Attributes | Description |
---|---|---|---|
emailAddress | EmailAddress |
|
The email address, if known. |
phoneNumber | string |
|
The phone number, if known. Example: "(206) 555-1212" |
firstName | string |
|
The first name, if known. |
middleName | string |
|
The middle name, if known. |
lastName | string |
|
The last name, if known. |
suffix | string |
|
The name suffix, if known. |
ARM index types.
Value |
---|
CD |
CMT |
CODI |
COFI |
COSI |
LIBOR_1_YEAR |
LIBOR_6_MONTH |
MTA |
PrimeRate |
TBill |
SOFR |
SOFR_6_MONTH |
Credit score ranges.
Value |
---|
R_760_ |
R_740_759 |
R_720_739 |
R_700_719 |
R_680_699 |
R_660_679 |
R_640_659 |
R_620_639 |
R_600_619 |
R_560_599 |
R_300_559 |
The borrower's stage in her purchase journey.
Value | Description |
---|---|
LookingAtListings |
Just looking at listings. |
TouringHomes |
Touring homes. |
MakingOffer |
Making or made an offer. |
UnderContract |
Under contract. |
EstimatedAffordability |
Estimated affordability. |
PreapprovedOrPrequalified |
Preapproved or prequalified. |
MakingOfferOrUnderContract |
Making offer or under contract. |
Known mortgage loan backers.
Value |
---|
FannieMae |
FreddieMac |
FHA |
Supported account languages.
Value |
---|
Arabic |
Bengali |
Cantonese |
English |
Farsi |
Filipino |
French |
German |
Greek |
Hebrew |
Hindi |
Hungarian |
Italian |
Japanese |
Korean |
Mandarin |
Polish |
Portuguese |
Russian |
Spanish |
Thai |
Turkish |
Vietnamese |
Types of loan program that a borrower can express interest in. These values are not comprehensive or orthogonal.
Value |
---|
Fixed30Year |
Fixed20Year |
Fixed15Year |
Fixed10Year |
ARM3 |
ARM5 |
ARM7 |
HomeEquity30Year |
HomeEquity30YearDueIn15 |
HomeEquity15Year |
HELOC20Year |
HELOC15Year |
HELOC10Year |
LowOrNoDown |
InterestOnly |
The purpose of a loan.
Value | Description |
---|---|
Purchase |
A purchase loan. |
Refinance |
A refinance loan. |
HomeEquity |
A home-equity loan. |
Construction |
A construction (building) loan. This is a loan used to finance the actual construction of the home. |
HELOC |
A home-equity line of credit. |
Types of property.
Value |
---|
SingleFamilyHome |
TownHouse |
CondoFourOrFewerStories |
CondoFiveOrMoreStories |
Cooperative |
MobileOrManufactured |
Modular |
Leasehold |
Uses of property.
Value |
---|
Primary |
SecondaryOrVacation |
InvestmentOrRental |
US state and territory abbreviations.
Value | Description |
---|---|
AK |
Alaska |
AL |
Alabama |
AR |
Arkansas |
AS |
American Samoa |
AZ |
Arizona |
CA |
California |
CO |
Colorado |
CT |
Connecticut |
DC |
Washington, D.C. |
DE |
Delaware |
FL |
Florida |
GA |
Georgia |
GU |
Guam |
HI |
Hawaii |
IA |
Iowa |
ID |
Idaho |
IL |
Illinois |
IN |
Indiana |
KS |
Kansas |
KY |
Kentucky |
LA |
Louisiana |
MA |
Massachusetts |
MD |
Maryland |
ME |
Maine |
MH |
Marshall Islands |
MI |
Michigan |
MN |
Minnesota |
MO |
Missouri |
MP |
Northern Mariana Islands |
MS |
Mississippi |
MT |
Montana |
NC |
North Carolina |
ND |
North Dakota |
NE |
Nebraska |
NH |
New Hampshire |
NJ |
New Jersey |
NM |
New Mexico |
NV |
Nevada |
NY |
New York |
OH |
Ohio |
OK |
Oklahoma |
OR |
Oregon |
PA |
Pennsylvania |
PR |
Puerto Rico |
RI |
Rhode Island |
SC |
South Carolina |
SD |
South Dakota |
TN |
Tennessee |
TX |
Texas |
UT |
Utah |
VA |
Virgina |
VI |
Virgin Islands |
VT |
Vermont |
WA |
Washington |
WI |
Wisconsin |
WV |
West Virginia |
WY |
Wyoming |
Types of veteran who qualify for VA loans.
Value |
---|
RegularMilitary |
Reserves |
NationalGuard |
SpouseOfRegularMilitary |
SpouseOfReserveMilitary |
Army |
Navy |
AirForce |
MarineCorps |
CoastGuard |
DepartmentOfDefense |
Brands owned by Zillow Group. New brands may be added to this list in the future. Notification processors should ignore any values they do not recognize.
Value | Description |
---|---|
Zillow Group |
The Zillow Group brand. |
Zillow |
The Zillow brand. |
Trulia |
The Trulia brand. |
StreetEasy |
The StreetEasy brand. |
HotPads |
The Hotpads brand. |
RealEstate.com |
The RealEstate.com brand. |
Zillow Home Loans |
The Zillow Home Loans brand. |
MLOA |
The Mortgage Lenders of America brand. |
Channels through which a contact may be initiated. New types may be added to this list in the future. Notification processors should ignore any values they do not recognize.
Value | Description |
---|---|
Default |
The contact was initiated via the default user experience for the contact type. |
Test |
The contact was initiated by a test tool. |
PAC |
The contact was initiated by the Premier Agent Concierge team. |
ZillowOffersInHome |
The contact was initated through a Zillow Offers in-home flyer. |
PremierAgent |
The contact was initiated through Premier Agent |
DeferredAppraisal |
The contact was initiated through the Deferred Appraisal campaign |
Types of mortgage contacts for which Zillow sends notifications. New types may be added to this list in the future. Notification processors should ignore any values they do not recognize.
Value | Description |
---|---|
simple |
A contact sent from a lender's Zillow profile page. |
quote |
A contact sent in regard to a loan quote submitted by the lender. |
longForm |
A contact sent from any of the Zillow Mortgages long-form or pre-approval wizards. |
propertyPreapproval |
A contact sent from a Zillow home details page as a side-effect of contacting a buyer's agent. |
zhl |
For internal use only. |