LendWorksLendWorksDocs

SDK Reference

Client configuration, rate limits, pagination, idempotency, and glossary for the LendIQ SDK.

Client Configuration

Constructor Options

TypeScript
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
});
Python
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

NameTypeRequiredDescription
apiKeystringYesYour LendIQ API key (liq_live_... or liq_test_...)
baseUrlstringNoAPI base URL. Defaults to https://iq.lend.works
timeoutnumberNoRequest timeout in milliseconds. Defaults to 30000
maxRetriesnumberNoMax retry attempts for transient errors. Defaults to 2
loggerobjectNoLogger instance (e.g., console) for debug output
geminiModelstringNoOverride 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.

TypeScript
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 reports

Rate Limits & Quotas

Plan Limits

PlanDeals/MonthRate LimitPrice
Free2560 req/min$0
Starter100120 req/min$49/mo
Pro500600 req/min$149/mo
Business2,0001,200 req/min$399/mo
EnterpriseUnlimitedCustomContact 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.

TypeScript
const client = new LendIQ({
  apiKey: "liq_live_...",
  maxRetries: 3,  // default is 2
});
Python
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

NameTypeRequiredDescription
dataarrayYesThe current page of results
has_morebooleanYesWhether there are more pages to fetch
next_cursorstring | nullYesOpaque cursor to pass on the next request, or null if this is the last page

Iterating All Pages

TypeScript
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`)
Python
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

ParameterMinMaxDefault
per_page110020

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

TypeScript
// 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" }
)
Python
# 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

OperationRecommended
deals.createYes — prevents duplicate deals on retry
deals.quickStartYes — prevents duplicate deal + document
documents.uploadYes — prevents duplicate uploads
documents.uploadBulkYes — each file gets its own key internally
deals.get / deals.listNo — 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.

TypeScript
// Combine internal ID + operation type for natural uniqueness
const idempotencyKey = `deal-${internalId}-${Date.now()}`

Glossary

Financial Terms

TermDefinition
Health ScoreComposite 0-100 metric measuring a business's financial health based on 12 weighted sub-factors
Health GradeLetter grade (A-D) derived from health score: A (80-100), B (60-79), C (40-59), D (0-39)
Factor RateMultiplier applied to advance amount to determine total repayment. E.g., $100K advance x 1.35 factor rate = $135K total repayment
HoldbackPercentage of daily revenue withheld for repayment. E.g., 15% holdback on $10K daily revenue = $1,500/day
ADBAverage Daily Balance — mean end-of-day bank balance over a statement period
NSFNon-Sufficient Funds — bounced transactions due to insufficient balance
MCAMerchant Cash Advance — a type of business financing repaid through daily holdback on revenue
MCA StackingWhen a business has multiple active MCA positions simultaneously, increasing repayment burden and default risk
Paper GradeInternal quality rating (A+ through F) assigned to a deal based on underwriting analysis
Risk TierClassification from tier_1 (lowest risk) through tier_4 (highest risk) indicating the deal's risk profile

API Terms

TermDefinition
API KeyAuthentication credential prefixed with liq_live_ (production) or liq_test_ (sandbox)
Idempotency KeyUnique string that prevents duplicate resource creation on retry
WebhookHTTP callback that delivers real-time event notifications to your server
SSEServer-Sent Events — persistent HTTP connection for real-time pipeline progress streaming
PipelineThe 12-stage analysis process: classification, extraction, screening, scoring, decision
RulesetCustom set of underwriting criteria (thresholds, weights, exclusions) applied during deal evaluation
DealA single funding application submitted for analysis, containing one or more financial documents
Fundability GradeLetter grade (A-D) indicating how likely a business is to receive additional MCA funding given existing positions