Submit a lead

POSThttps://api.ziplend.com/leads

Creates a lead from the fields below. Required: firstName, lastName, email, phone, leadSource. Everything else is optional; send what you have.

The reply carries Ziplend's leadId for the record. Keep it — it is the reference for any later question about the lead.

Authentication

The apikey header — see Obtaining authentication.

Request body

A JSON object. Required: firstName, lastName, email, phone, leadSource. Everything else is optional.

Request control

FieldTypeDescription
test boolean

Mark this submission as a test. It is validated, logged and answered like a real one.
externalId string(255)

Your own identifier for this lead, if you have one.
leadSource required string(255)

The source label for this lead, as agreed with Ziplend. A label not enabled for your key is refused (422).

Borrower

FieldTypeDescription
firstName required string(40)
lastName required string(80)
middleName string(40)
email required email
phone required string

Primary phone. Any format; must contain 10 digits.

10 digits, any format
alternatePhone string

A second number, if collected.

10 digits, any format
dateOfBirth date
YYYY-MM-DD
ssn string
preferredLanguage string
englishspanishchinesekoreantagalogvietnamese
employmentStatus string
employedselfEmployednotEmployed
jobTitle string(128)
employerName string(40)
lengthOfEmployment string(255)

Free text, e.g. "4 years".
monthlyIncome number

Gross monthly income before taxes, in dollars.
creditRating string

The borrower's own assessment.

excellentgoodfairpoor
creditScore integer
300–850
militaryStatus string

none sends nothing. A partner that only knows yes/no should send veteran for yes.

activeDutyveteranreserveOrNationalGuardnone

Borrower residence

Send the complete address or none of it — street, city, state and ZIP together. A partial address is refused.

FieldTypeDescription
residenceStreet string(255)

The borrower's home address, when it is not the subject property.
residenceCity string(40)
residenceState string
two-letter state code
residenceZip string
5 digits
residenceIsProperty boolean

True when the borrower lives in the subject property.

Co-borrower

FieldTypeDescription
coBorrowerFirstName string(40)
coBorrowerLastName string(80)
coBorrowerMiddleName string(40)
coBorrowerEmail email
coBorrowerPhone string
10 digits, any format
coBorrowerAlternatePhone string
10 digits, any format
coBorrowerDateOfBirth date
YYYY-MM-DD
coBorrowerSsn string
coBorrowerMonthlyIncome number
coBorrowerEmploymentStatus string
employedselfEmployednotEmployed
coBorrowerJobTitle string(128)
coBorrowerEmployerName string(80)
coBorrowerLengthOfEmployment string(255)
coBorrowerMilitaryStatus string
activeDutyveteranreserveOrNationalGuardnone
coBorrowerPreferredLanguage string
englishspanishchinesekoreantagalogvietnamese

Co-borrower residence

Send the complete address or none of it — street, city, state and ZIP together. A partial address is refused.

FieldTypeDescription
coBorrowerResidenceStreet string(255)

The co-borrower's home address, when it is not the subject property.
coBorrowerResidenceCity string(40)
coBorrowerResidenceState string
two-letter state code
coBorrowerResidenceZip string
5 digits
coBorrowerResidenceIsProperty boolean

Subject property

Send the complete address or none of it — street, city, state and ZIP together. A partial address is refused.

FieldTypeDescription
subjectPropertyStreet string(255)
subjectPropertyCity string(40)
subjectPropertyState string

Two-letter state code.

two-letter state code
subjectPropertyZip string
5 digits
subjectPropertyCounty string(80)
subjectPropertyType string
singleFamilyDetachedsingleFamilyAttachedtownhousepuddetachedCondositeCondocondoUnder5Storiescondo5To8StoriescondoOver8StoriescondotelcoopUnder5Storiescoop5To8StoriescoopOver8StoriestwoUnitthreeUnitfourUnitfiveUnitsixUnitsevenUniteightUnitnineUnittenUnitmanufacturedSingleWidemanufacturedDoubleWidemixedUsevacantLot
subjectPropertyOccupancy string
primaryResidencesecondHomeinvestment
subjectPropertyValue number

Estimated value of the subject property, in dollars.
subjectPropertyPurchaseDate date

When the borrower bought the subject property (refinance).

YYYY-MM-DD

Loan request

FieldTypeDescription
loanPurpose string

What the borrower is asking for.

purchaserefinancecashOutRefinancehelocpersonalLoan
loanAmount number

The amount requested, in dollars.
loanType string

The loan program the borrower wants, if known.

conventionalfhavahelocheloannonQmreverseusdaRuralDevelopment
cashOutAmount number

Cash the borrower wants out of a refinance, in dollars.
cashOutReason string
debtConsolidationeducationhomeImprovementinterestRateReductionother

Current mortgage (refinance)

FieldTypeDescription
currentMortgageBalance number

Balance of the first mortgage, in dollars.
currentRate number

The current interest rate as a percentage, e.g. 6.5.
currentLoanType string
conventionalfhavahelocheloannonQmreverseusdaRuralDevelopment
currentLender string(255)
currentMonthlyPayment number
paymentIncludesTaxesAndInsurance boolean

Whether currentMonthlyPayment includes escrowed taxes and insurance. Omit if unknown.
monthlyTaxes number
monthlyInsurance number
monthlyHoaDues number
monthlyPmi number
monthlyEscrow number

Purchase

FieldTypeDescription
homeBuyingStage string
gettingStartedmakingOffersfoundHouseOrOfferPendingunderContract
foundHome boolean
purchaseAgreement boolean

A purchase agreement has been signed.
firstTimeBuyer boolean
purchasePrice number

Price of the home being bought, in dollars.
downPaymentPercent number

Down payment as a percentage of the price, e.g. 20.

0–100

Examples

A refinance lead with cash out

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@example.com",
  "phone": "5551234567",
  "leadSource": "Example Partner",
  "subjectPropertyStreet": "123 Main St",
  "subjectPropertyCity": "Riverside",
  "subjectPropertyState": "CA",
  "subjectPropertyZip": "92501",
  "loanPurpose": "cashOutRefinance",
  "subjectPropertyType": "singleFamilyDetached",
  "subjectPropertyOccupancy": "primaryResidence",
  "subjectPropertyValue": 650000,
  "currentMortgageBalance": 410000,
  "cashOutAmount": 50000,
  "cashOutReason": "debtConsolidation",
  "creditRating": "good",
  "tcpaConsent": true,
  "externalId": "1790366143",
  "trustedFormCertUrl": "https://cert.trustedform.com/f756854b794b2b891b80691758552824b86b6b2a"
}

A purchase lead

{
  "firstName": "John",
  "lastName": "Smith",
  "email": "john.smith@example.com",
  "phone": "5559876543",
  "leadSource": "Example Partner",
  "subjectPropertyState": "TX",
  "subjectPropertyZip": "78701",
  "loanPurpose": "purchase",
  "homeBuyingStage": "makingOffers",
  "firstTimeBuyer": true,
  "purchasePrice": 425000,
  "downPaymentPercent": 10,
  "loanAmount": 382500,
  "tcpaConsent": true,
  "test": true
}

Responses

201

The lead was created.

FieldTypeDescription
leadId uuid

Ziplend's identifier for this lead.
received date-time

When Ziplend accepted it.
test boolean

Echoes the request's test flag.

 
{
  "leadId": "3f2c9b2e-7c1a-4f0e-9a8c-2d1e5b6f7a90",
  "received": "2026-10-01T22:23:28.750Z",
  "test": false
}
400

The body is not a JSON object.

FieldTypeDescription
error string 
{
  "error": "invalid json"
}
401

The apikey header is missing or not recognised.

FieldTypeDescription
error string 
{
  "error": "Unauthorized"
}
403

This key may not submit leads.

FieldTypeDescription
error string 
{
  "error": "Forbidden"
}
413

The body is larger than 32 KB.

FieldTypeDescription
error string 
{
  "error": "too large"
}
422

One or more fields are missing or malformed. Nothing was created.

FieldTypeDescription
error string
must be "validation"
fields array 
{
  "error": "validation",
  "fields": [
    {
      "field": "email",
      "message": "must be a valid email"
    },
    {
      "field": "leadSource",
      "message": "is required"
    }
  ]
}
502

Ziplend's systems did not accept the lead.

FieldTypeDescription
error string 
{
  "error": "upstream"
}