SDK Reference
Client configuration, rate limits, pagination, idempotency, and glossary for the LendIQ SDK.
Client Configuration
Constructor Options
import { LendIQ } from "@lendworks/lendiq";
const client = new LendIQ({
apiKey: "liq_live_...", // Required
baseUrl: "https://iq.lend.works", // Default API endpoint
timeout: 30_000, // Request timeout in ms
maxRetries: 2, // Retry count for transient errors
logger: console, // Enable debug logging
geminiModel: "gemini-2.0-flash-exp", // Override extraction model
});from lendiq import LendIQ
client = LendIQ(
api_key="liq_live_...", # Required
base_url="https://iq.lend.works", # Default API endpoint
timeout=30_000, # Request timeout in ms
max_retries=2, # Retry count for transient errors
logger=True, # Enable debug logging
)Options Reference
| Name | Type | Required | Description |
|---|---|---|---|
apiKey | string | Yes | Your LendIQ API key (liq_live_... or liq_test_...) |
baseUrl | string | No | API base URL. Defaults to https://iq.lend.works |
timeout | number | No | Request timeout in milliseconds. Defaults to 30000 |
maxRetries | number | No | Max retry attempts for transient errors. Defaults to 2 |
logger | object | No | Logger instance (e.g., console) for debug output |
geminiModel | string | No | Override the AI model used for document extraction |
Timeout Constants
The SDK uses different default timeouts for different operation types. You can reference these constants when configuring custom timeouts.
console.log(LendIQ.TIMEOUT_READ); // 10_000ms — for reads
console.log(LendIQ.TIMEOUT_WRITE); // 30_000ms — for writes
console.log(LendIQ.TIMEOUT_UPLOAD); // 120_000ms — for uploads
console.log(LendIQ.TIMEOUT_REPORT); // 300_000ms — for reportsRate Limits & Quotas
Plan Limits
| Plan | Deals/Month | Rate Limit | Price |
|---|---|---|---|
| Free | 25 | 60 req/min | $0 |
| Starter | 100 | 120 req/min | $49/mo |
| Pro | 500 | 600 req/min | $149/mo |
| Business | 2,000 | 1,200 req/min | $399/mo |
| Enterprise | Unlimited | Custom | Contact us |
Auto-Retry
The SDK automatically retries requests that receive a 429 rate limit response. It respects the Retry-After header and uses exponential backoff. You can configure the maximum number of retries.
const client = new LendIQ({
apiKey: "liq_live_...",
maxRetries: 3, // default is 2
});client = LendIQ(
api_key="liq_live_...",
max_retries=3, # default is 2
)Info: When rate limited, the SDK waits for the duration specified in the Retry-After header before retrying. No manual backoff logic is needed.
Pagination
How Pagination Works
All list endpoints return paginated responses with data, has_more, and next_cursor fields. Use the cursor to fetch subsequent pages.
Response Shape
| Name | Type | Required | Description |
|---|---|---|---|
data | array | Yes | The current page of results |
has_more | boolean | Yes | Whether there are more pages to fetch |
next_cursor | string | null | Yes | Opaque cursor to pass on the next request, or null if this is the last page |
Iterating All Pages
const allDeals: typeof page.data = []
let cursor: string | undefined
do {
const page = await client.deals.list({ cursor, per_page: 50 })
allDeals.push(...page.data)
cursor = page.has_more ? page.next_cursor ?? undefined : undefined
} while (cursor)
console.log(`Fetched ${allDeals.length} deals`)all_deals = []
cursor = None
while True:
page = client.deals.list(cursor=cursor, per_page=50)
all_deals.extend(page.data)
if not page.has_more:
break
cursor = page.next_cursor
print(f"Fetched {len(all_deals)} deals")Tip: For most use cases, the default page size of 20 is sufficient. Only increase per_page if you need to process large batches.
Page Size Limits
| Parameter | Min | Max | Default |
|---|---|---|---|
per_page | 1 | 100 | 20 |
Idempotency
What Is Idempotency
Network failures happen. Idempotency keys let you safely retry create operations without risk of duplicating deals or documents. If a request with the same idempotency key has already succeeded, the API returns the original result instead of creating a new resource.
Using Idempotency Keys
// deals.quickStart with idempotency key
const result = await client.deals.quickStart({
business_name: "Acme Trucking LLC",
file: "./statements/chase_jan.pdf",
document_type: "bank_statement",
idempotency_key: "deal-acme-trucking-2026-03-29",
})
// documents.upload with idempotency key
const doc = await client.documents.upload(
dealId,
"./statements/bofa_feb.pdf",
{ idempotencyKey: "upload-bofa-feb-2026-03-29" }
)# deals.quick_start with idempotency key
result = client.deals.quick_start(
business_name="Acme Trucking LLC",
file="./statements/chase_jan.pdf",
document_type="bank_statement",
idempotency_key="deal-acme-trucking-2026-03-29",
)
# documents.upload with idempotency key
doc = client.documents.upload(
deal_id,
"./statements/bofa_feb.pdf",
idempotency_key="upload-bofa-feb-2026-03-29",
)When to Use
| Operation | Recommended |
|---|---|
deals.create | Yes — prevents duplicate deals on retry |
deals.quickStart | Yes — prevents duplicate deal + document |
documents.upload | Yes — prevents duplicate uploads |
documents.uploadBulk | Yes — each file gets its own key internally |
deals.get / deals.list | No — reads are naturally idempotent |
Warning: Idempotency keys expire after 24 hours. After that, a request with the same key will create a new resource.
Key Format
Keys can be any unique string up to 255 characters. UUIDs work well. Include enough context to make keys naturally unique — e.g., combine your internal record ID with the operation type.
// Combine internal ID + operation type for natural uniqueness
const idempotencyKey = `deal-${internalId}-${Date.now()}`Glossary
Financial Terms
| Term | Definition |
|---|---|
| Health Score | Composite 0-100 metric measuring a business's financial health based on 12 weighted sub-factors |
| Health Grade | Letter grade (A-D) derived from health score: A (80-100), B (60-79), C (40-59), D (0-39) |
| Factor Rate | Multiplier applied to advance amount to determine total repayment. E.g., $100K advance x 1.35 factor rate = $135K total repayment |
| Holdback | Percentage of daily revenue withheld for repayment. E.g., 15% holdback on $10K daily revenue = $1,500/day |
| ADB | Average Daily Balance — mean end-of-day bank balance over a statement period |
| NSF | Non-Sufficient Funds — bounced transactions due to insufficient balance |
| MCA | Merchant Cash Advance — a type of business financing repaid through daily holdback on revenue |
| MCA Stacking | When a business has multiple active MCA positions simultaneously, increasing repayment burden and default risk |
| Paper Grade | Internal quality rating (A+ through F) assigned to a deal based on underwriting analysis |
| Risk Tier | Classification from tier_1 (lowest risk) through tier_4 (highest risk) indicating the deal's risk profile |
API Terms
| Term | Definition |
|---|---|
| API Key | Authentication credential prefixed with liq_live_ (production) or liq_test_ (sandbox) |
| Idempotency Key | Unique string that prevents duplicate resource creation on retry |
| Webhook | HTTP callback that delivers real-time event notifications to your server |
| SSE | Server-Sent Events — persistent HTTP connection for real-time pipeline progress streaming |
| Pipeline | The 12-stage analysis process: classification, extraction, screening, scoring, decision |
| Ruleset | Custom set of underwriting criteria (thresholds, weights, exclusions) applied during deal evaluation |
| Deal | A single funding application submitted for analysis, containing one or more financial documents |
| Fundability Grade | Letter grade (A-D) indicating how likely a business is to receive additional MCA funding given existing positions |