Lendicity
API v1
REST · JSON

Personal Loan Waterfall API

Submit personal loan requests and receive a single accepted lender with a redirect URL. Tiers are processed sequentially (waterfall) until a match is found.

Overview

The Waterfall API uses the same request payload as the Offers API, but instead of returning a list of offers it runs your panel's tiers in waterfall (sequential) order. The first tier that accepts the lead wins — the response contains a redirect_url that you send the consumer to immediately.

The API is versioned via the /v1/ path segment. An x-api-version header is also accepted and must match.

POSThttps://www.lendicity.com/api/public/v1/waterfall

Authentication

Requests are authenticated with a partner access key in the x-partner-key header. Keys are issued by your account manager.

x-partner-key: <YOUR_PARTNER_KEY>
x-api-version: v1
Content-Type: application/json

Test mode

During integration, send "testMode": true in the JSON body or set x-test-mode: 1. Test leads are stored separately and do not affect live reporting.

Endpoint

POSThttps://www.lendicity.com/api/public/v1/waterfall

The v1 segment in the URL is the canonical version indicator. CORS is enabled (any origin).

Request example

A complete request body with all required fields. This is identical to the Offers API payload, plus the Waterfall-specific mandatory fields:

{
  "amount": 10000,
  "amountDebt": 5000,
  "purpose": "debt_consolidation",
  "term": 36,
  "credit": "good",
  "incomeSource": "employed_full_time",
  "annualIncome": 60000,
  "monthlyIncome": 5000,
  "payFrequency": "biweekly",
  "directDeposit": true,
  "military": false,
  "employerName": "Acme Corp",
  "employerPhone": "5125559876",
  "monthsAtEmployer": 24,
  "occupation": "Software Engineer",
  "nextPayDate": "2025-07-15",
  "followingPayDate": "2025-07-29",
  "bankName": "Chase",
  "bankAccountType": "Checking",
  "bankAccountNumber": "000123456789",
  "bankRoutingNumber": "021000021",
  "monthsAtBank": 36,
  "housing": "rent",
  "housingPayment": 1200,
  "monthsAtAddress": 18,
  "address": "123 Main St",
  "city": "Austin",
  "state": "TX",
  "zip": "78701",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane@example.com",
  "phone": "5551234567",
  "dob": "1990-06-15",
  "ssn": "123456789",
  "driverLicenseNumber": "D1234567",
  "driverLicenseState": "TX",
  "siteUrl": "partnerwebsite.com",
  "siteIp": "192.168.1.1",
  "clientIp": "203.0.113.45",
  "consentTcpa": true,
  "consentTerms": true,
  "consentPrivacy": true,
  "consentFcra": true,
  "userAgent": "Mozilla/5.1...",
  "testMode": false,
  "minPrice": 12.50,
  "maxTime": 30
}

Request payload

The request payload is nearly identical to the Offers API. All fields, validation rules, and required consents are the same. Refer to the Leads API docs for the full field reference.

Waterfall-specific required fields: the following fields are mandatory for the Waterfall API (they are optional in the Offers API): nextPayDate, followingPayDate, employerPhone, monthsAtEmployer, all bank account fields (bankName, bankAccountType, bankAccountNumber, bankRoutingNumber, monthsAtBank), and all driver license fields (driverLicenseNumber, driverLicenseState).

Loan request

amount
numberrequired Requested loan amount in dollars. Minimum 100, maximum 1,000,000. Requests below 100 are rejected with HTTP 422.
amountDebt
numberoptional Amount of unsecured debt the consumer has in dollars (0–1,000,000).
purpose
stringrequired One of "debt_consolidation", "home_improvement", "auto_vehicle", "medical", "major_life_event", "large_purchase", "other".
term
integeroptional Desired term in months (1–360).
credit
stringoptional One of "excellent" (720+), "good" (660–719), "fair" (620–659), "poor" (less than 620), "limited" (limited / no history).
educationLevel
stringoptional One of "High School", "Associate", "Bachelors", "Masters", "Other Graduate Degree", "Other".
minPrice
numberoptional Minimum price in dollars the lead can be sold for. Lendicity will not accept any tier offer below this floor. Omit or set to 0 for no floor.
maxTime
integeroptional Maximum time in seconds Lendicity is allowed to attempt selling the lead in the marketplace before the partner closes the connection. Once this window elapses Lendicity will let any in-flight lender ping finish but will not start a new lender attempt.

Income source & income

incomeSource
stringrequired One of "employed_full_time", "employed_part_time", "self_employed", "retired", "unemployed_benefits", "other".
annualIncome
numberconditional Annual gross income in dollars. At least one of annualIncome or monthlyIncome is required.
monthlyIncome
numberconditional Monthly gross income in dollars. At least one of annualIncome or monthlyIncome is required.
payFrequency
stringrequired One of "weekly", "biweekly", "semimonthly", "monthly".
directDeposit
0/1 or true/falserequired Whether income is direct-deposited.
military
0/1 or true/falserequired Active military or covered dependent.
employerName
stringrequired Name of the customer's employer. Up to 100 alphanumeric characters. If self employed pass "self" or the customer's trading name. If retired or unemployed pass "none".
workPhone
stringoptional Customer's work phone number. 10 digits.
employerPhone
stringrequired Employer's phone number. 10 digits. Required for Waterfall API.
monthsAtEmployer
integerrequired Months with current employer. If unemployed pass 0. If self employed pass the number of months self employed. If on benefits pass the number of months on benefits or 0.
occupation
stringoptional Customer's occupation.
nextPayDate
stringrequired The date of the customer's next paycheck in YYYY-MM-DD format. Required for Waterfall API.
followingPayDate
stringrequired The date of the paycheck following the next paycheck in YYYY-MM-DD format. Required for Waterfall API.

Bank account

bankName
stringrequired Name of the customer's bank. Up to 50 alphanumeric characters. Required for Waterfall API.
bankAccountType
stringrequired One of "Checking" or "Savings". Required for Waterfall API.
bankAccountNumber
stringrequired Bank account number. 4–17 numeric digits, no dashes or spaces. Required for Waterfall API.
bankRoutingNumber
stringrequired Bank routing number. Up to 9 numeric digits. Required for Waterfall API.
monthsAtBank
integerrequired The number of months the customer has been with his/her current Bank Account. Required for Waterfall API.

Housing

housing
stringrequired One of "own_mortgage", "own_outright", "rent", "live_with_family", "other".
housingPayment
numberrequired Monthly housing payment in dollars.
monthsAtAddress
integerrequired The number of months since the customer has moved in to his/her address.
address
stringrequired Street address. PO Box addresses are not allowed and will be rejected with a validation error.
city
stringrequired City.
state
stringrequired 2-letter US state code.
zip
stringrequired ZIP / postal code.

Identity & contact

firstName
stringrequired First name.
lastName
stringrequired Last name.
email
stringrequired Valid email address.
phone
stringrequired Phone number (any common format).
dob
stringrequired Date of birth, YYYY-MM-DD.
ssn
stringrequired SSN 123-45-6789 or 123456789.
driverLicenseNumber
stringrequired Customer's driver's license number. 6–20 alphanumeric characters. Required for Waterfall API.
driverLicenseState
stringrequired Two-letter state abbreviation for the customer's driver's license or state ID. Required for Waterfall API.

Submission context

siteUrl
stringrequired URL of the site where the user made the loan request. Format: websitename.com (no protocol).
siteIp
stringrequired IP address of the partner's site/server submitting the lead. XXX.XXX.XXX.XXX format.
clientIp
stringrequired IP address of the customer's browser. XXX.XXX.XXX.XXX format.

Compliance & metadata

consentTcpa
0/1 or true/falserequired Must be truthy. Consumer's affirmative consent to be contacted under TCPA.
consentTerms
0/1 or true/falserequired Must be truthy. Consumer's acceptance of the Terms of Use / E-SIGN disclosure.
consentPrivacy
0/1 or true/falserequired Must be truthy. Consumer's acknowledgment of the Privacy Policy.
consentFcra
0/1 or true/falserequired Must be truthy. Consumer's FCRA authorization to obtain a consumer/credit report.
userAgent
stringrequired User agent string captured from the browser.
testMode
0/1 or true/falserequired Routes the lead to the test table.

Tracking variables

Partners can pass up to eight free-form alphanumeric variables (dv1–dv8) that are stored on the lead and surfaced in reporting.

Recommended

dv1
stringoptional Recommended: a high-level sub-campaign identifier. Alphanumeric, max 120 chars.
dv2
stringoptional Recommended: a unique customer identifier that will be returned in reporting.

Additional

dv3
stringoptional Additional passthrough variable. Alphanumeric.
dv4
stringoptional Additional passthrough variable. Alphanumeric.
dv5
stringoptional Additional passthrough variable. Alphanumeric.
dv6
stringoptional Additional passthrough variable. Alphanumeric.
dv7
stringoptional Additional passthrough variable. Alphanumeric.
dv8
stringoptional Additional passthrough variable. Alphanumeric.

Response

Success: A valid submission returns 201 Created

Unlike the Leads API, the Waterfall API does not return an array of offers. Instead it returns either an accepted result with a redirect_url (send the consumer there immediately), or a rejection.

Accepted response example:

{
  "requestId": 104201,
  "redirect_url": "https://lendicity.com/r/abc123...",
  "accepted": true,
  "accepted_tier": 1,
  "partner_payout": 100.00
}

Rejected response example:

{
  "requestId": 104201,
  "redirect_url": null,
  "accepted": false,
  "accepted_tier": null,
  "partner_payout": null
}

Top-level fields

requestId
number Unique numeric identifier for the created lead.
redirect_url
string | null Partner tracking URL that redirects the consumer to the lender application. When accepted is true, redirect the consumer's browser to this URL immediately.
accepted
boolean true if a tier accepted the lead; false if all tiers rejected or timed out.
accepted_tier
integer | null The tier number (1-based) that accepted the lead. null when no tier accepted.
partner_payout
number | null Dollar amount Lendicity pays the partner for this accepted lead. null when accepted is false or the campaign has no CPA payout configured.
Integration note: When accepted is true, your platform must redirect the consumer's browser to redirect_url as quickly as possible. The waterfall is optimized for speed - delays increase abandonment rates. Redirect rates must be maintained above 75% to prevent automated traffic pauses.

Errors

Error responses and HTTP status codes are identical to the Offers API. Refer to that page for detailed examples.

400
Bad request Body is not valid JSON, or an unsupported x-api-version was supplied.
401
Unauthorized Missing, invalid, or disabled x-partner-key.
404
Not found Requested resource does not exist.
422
Unprocessable Schema validation failed. Response includes a details object.
429
Too Many Requests Per-minute rate limit exceeded for this campaign. Retry after the seconds indicated in the Retry-After header.
500
Server error Unexpected error. Safe to retry with the same payload.