zillowLenderContactNotification

Zillow Confidential

This is the Zillow Mortgages JSON lender contact notification API.

NOTE: Respond with non-2xx HTTP status code to indicate failure.

Input Parameters

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
  • optional

For internal use only.

affiliate bool
  • optional

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
  • optional

Information about the loan quote which the contact is in reference to, if any.

Output Parameters

Name Type Attributes Description
externalContactReference string
  • optional
  • nullable
  • len(value) < 256

The optional external contact reference ID.

applicationURL string
  • optional
  • nullable
  • len(value) <= 4000

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.

Error Codes

The action returns no custom error codes.

Typedefs

typedef ContactId

Encoded contact ID, like "LC-EXAMPLE".

Type
string

typedef EmailAddress

Email address.

Type Attributes
string
  • len(value) > 0
  • len(value) <= 254

typedef LenderId

Encoded lender ID (aka ZUID), like "ZUexampleexample".

Type
string

typedef QuoteId

Encoded quote ID, like "ZQ-EXAMPLE".

Type
string

typedef RequestId

Encoded loan request ID, like "ZR-EXAMPLE".

Type
string

typedef UserId

Encoded user ID (aka ZUID), like "ZUexampleexample".

Type
string

Struct Types

struct ZillowLenderContactDetails

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
  • optional

Whether the borrower is willing to accept a loan with a pre-payment penalty.

agentBusinessName string
  • optional

The business name of the real-estate agent, associated with the contact.

agentEmailAddress string
  • optional

The email address of the real-estate agent, associated with the contact.

agentFirstName string
  • optional

The first name of the real-estate agent, associated with the contact.

agentId UserId
  • optional

The Zillow user ID of the real-estate agent, associated with the contact. Example: "ZUexampleexample"

agentLastName string
  • optional

The last name of the real-estate agent, associated with the contact.

agentPhoneNumber string
  • optional

The first name of the real-estate agent, associated with the contact. Example: "(206) 555-1212"

annualIncome int
  • optional

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
  • optional

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
  • optional

The name of the city where the property is located. Example: "Seattle"

county string
  • optional

The name of the county where the property is located. Example: "King"

closingTimelineDays int
  • optional

The borrower's estimated days until closing.

creditScoreHigh int
  • optional

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
  • optional

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
  • optional

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
  • optional

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
  • optional

The current mortgage balance, in dollars.

debtToIncomePercent float
  • optional

The borrower's debt-to-income ratio (DTI), as a percentage. This value is equivalent to 100 * (monthlyDebts * 12) / annualIncome.

desiredPrograms LoanProgram []
  • optional

Loan programs which the borrower is interested in.

displayedCreditScoreRange string
  • optional

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
  • optional

The down payment amount, in dollars.

fhaStreamlineEligible bool
  • optional

Whether the borrower is eligible for an FHA Streamline loan.

firstTimeBuyer bool
  • optional

Whether the borrower is a first-time buyer.

harpEligible bool
  • optional

Whether the borrower is eligible for a HARP refinance loan.

hasAgent bool
  • optional

Whether the borrower is working with a real-estate agent.

hasBankruptcy bool
  • optional

Whether the borrower or co-borrower has declared bankruptcy in the last 7 years.

hasCoborrower bool
  • optional

Whether there is a co-borrower.

hasForeclosure bool
  • optional

Whether the borrower or co-borrower has had a foreclosure in the last 7 years.

hasSecondMortgage bool
  • optional

Whether the borrower or co-borrower has a second mortgage.

homeOwner bool
  • optional

Whether the borrower or co-borrower currently owns a home.

isDpaEligible bool
  • optional

Whether the borrower is eligible for Down Payment Assistance This value will only be present if its value is true.

isZGMIPaLead bool
  • optional

Whether the borrower info was forwarded to PA L2 Leads API. This value will only be present if its value is true.

journeyStage JourneyStage
  • optional

The borrower's current stage in her purchase journey.

loanAmount int
  • optional

The desired loan amount, in dollars.

loanPurpose LoanPurpose
  • optional

The loan purpose.

loanToValuePercent float
  • optional

The borrower's loan-to-value ratio (LTV), as a percentage. This value is equivalent to 100 * loanAmount / propertyValue.

message string
  • optional

A free-form message from the sender to the lender.

monthlyDebts int
  • optional

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
  • optional

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
  • optional

The borrower's preferred language of communication. This value will only be present it the borrower provided a preferred language.

propertyAddress string
  • optional

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
  • optional

The property type.

propertyUse PropertyUse
  • optional

The property use.

propertyValue int
  • optional

The property value. For a purchase loan, this is the purchase price.

quoteId QuoteId
  • optional

The Zillow ID of the loan quote associated with the contact. Example: "ZQ-EXAMPLE"

requestId RequestId
  • optional

The Zillow ID of the loan request associated with the contact. Example: "ZR-EXAMPLE"

selfEmployed bool
  • optional

Whether the borrower or co-borrwer is self-employed.

sellingHome bool
  • optional

Whether the borrower is also selling a home.

stateAbbreviation StateAbbreviation
  • optional

The two-letter abbreviation of the state where the property is located. Example: "WA"

streetAddress string
  • optional

The street address of the property. Example: "123 Main St"

totalAssets int
  • optional

The borrower's total assets, in dollars. If there is a co-borrower, this value represents the total of both borrowers' assets.

wantsCashOut bool
  • optional

Whether the borrower wants to take out cash as part of a refinance.

vaEligible bool
  • optional

Whether the borrower is eligible for VA loans.

vaFirstTimeUser bool
  • optional

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
  • optional

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
  • optional

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
  • optional

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
  • optional

The ZIP code where the property is located.

struct ZillowLenderContactLoanQuote

Information about a loan quote.

Name Type Attributes Description
rate float

The interest rate of the loan, as a percentage.

apr float
  • optional

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
  • optional

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
  • optional

Whether the loan has a prepayment penalty. This value will only be present if its value is true.

jumbo bool
  • optional

Whether the loan is a non-conforming jumbo loan. This value will only be present if its value is true.

harp bool
  • optional

Whether the loan is a HARP loan. This value will only be present if its value is true.

lenderPaidMortgageInsurance bool
  • optional

Whether the lender will pay the mortgage insurance on the loan. This value will only be present if its value is true.

annualMortgageInsurancePercent float
  • optional

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
  • optional

The ARM-specific details of an adjustable rate loan quote.

fha ZillowLenderContactLoanQuoteFHADetails
  • optional

The FHA-specific details of an FHA loan quote.

va ZillowLenderContactLoanQuoteVADetails
  • optional

The VA-specific details of a VA loan quote.

currentBackerMustBeFannieMae bool
  • optional

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
  • optional

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
  • optional

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
  • optional

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
  • optional

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.

struct ZillowLenderContactLoanQuoteARMDetails

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.

struct ZillowLenderContactLoanQuoteFeeDetails

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
  • optional

The fee amount, in dollars. This value will only be present if the lender specified the fee as a dollar amount.

percent float
  • optional

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.

struct ZillowLenderContactLoanQuoteFHADetails

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
  • optional

Whether the quote is for an FHA Streamline loan.

struct ZillowLenderContactLoanQuoteVADetails

Loan quote details specific to a VA loan quote.

Name Type Description
fundingFeePercent float

The VA funding fee, as a percentage.

struct ZillowLenderContactLoanQuoteZillowDetails

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.

struct ZillowLenderContactRecipient

Information about the lender who is the intended recipient of a contact.

Name Type Attributes Description
emailAddress EmailAddress
  • optional

The email address, if known.

phoneNumber string
  • optional

The phone number, if known. Example: "(206) 555-1212"

firstName string
  • optional

The first name, if known.

middleName string
  • optional

The middle name, if known.

lastName string
  • optional

The last name, if known.

suffix string
  • optional

The name suffix, if known.

lenderId LenderId

The lender's Zillow user ID. Example: "ZUexampleexample"

nmlsLicense string
  • optional

The lender's NMLS license, if known.

struct ZillowLenderContactSender

Information about the sender of a contact.

Name Type Attributes Description
emailAddress EmailAddress
  • optional

The email address, if known.

phoneNumber string
  • optional

The phone number, if known. Example: "(206) 555-1212"

firstName string
  • optional

The first name, if known.

middleName string
  • optional

The middle name, if known.

lastName string
  • optional

The last name, if known.

suffix string
  • optional

The name suffix, if known.

Enum Types

enum ARMIndex

ARM index types.

Value
CD
CMT
CODI
COFI
COSI
LIBOR_1_YEAR
LIBOR_6_MONTH
MTA
PrimeRate
TBill
SOFR
SOFR_6_MONTH

enum CreditScoreRange

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

enum JourneyStage

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.

enum KnownBacker

Known mortgage loan backers.

Value
FannieMae
FreddieMac
FHA

enum Language

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

enum LoanProgram

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

enum LoanPurpose

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.

enum PropertyType

Types of property.

Value
SingleFamilyHome
TownHouse
CondoFourOrFewerStories
CondoFiveOrMoreStories
Cooperative
MobileOrManufactured
Modular
Leasehold

enum PropertyUse

Uses of property.

Value
Primary
SecondaryOrVacation
InvestmentOrRental

enum StateAbbreviation

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

enum VeteranType

Types of veteran who qualify for VA loans.

Value
RegularMilitary
Reserves
NationalGuard
SpouseOfRegularMilitary
SpouseOfReserveMilitary
Army
Navy
AirForce
MarineCorps
CoastGuard
DepartmentOfDefense

enum ZillowGroupBrand

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.

enum ZillowLenderContactChannel

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

enum ZillowLenderContactType

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.