Most cash-flow API integration guides focus on the happy path: call the endpoint, parse the response, render the decision. What they underemphasize is the operational scaffolding around the API call that determines whether the integration actually works in a production lending environment. Authentication state management, payload construction from LOS data structures, error handling that does not stall loan processing, and adverse action flag routing each require deliberate design decisions that cannot be deferred to post-launch refinement.
This walkthrough covers a complete integration of a cash-flow decisioning API into a standard loan origination system workflow, including the parts that go wrong most often.
Prerequisites: What Needs to Be in Place Before Day One
Before any API call is written, three things need to be established:
- Decisioning policy documentation. The integration should implement a documented policy, not be the policy itself. Which applications trigger a cash-flow API call? Only FICO-null applications? FICO below 580? All applications in a specific product type? The answer should be in a written underwriting policy before the first line of integration code is written. The API is infrastructure; the decisioning logic is the institution's responsibility.
- Bank transaction data feed. The cash-flow API needs transaction history. How is that data being sourced? An open banking aggregator (connected via OAuth at application time) provides the cleanest integration but requires consumer-consent UX in the application flow. A direct feed from the institution's own core banking system (if the applicant is an existing member) is simpler but covers only members with accounts at your institution. Third-party aggregators can provide broader coverage but add a vendor dependency. Each path has different data freshness guarantees, coverage limitations, and integration complexity.
- Adverse action workflow. If the cash-flow API returns a decline recommendation with reason codes, those reason codes must flow into your adverse action notice generation process. Who generates the adverse action notice — the LOS, a compliance team member, or an automated system? How does the API reason code get translated into Regulation B-compliant plain language? This workflow must be designed before go-live, not improvised when the first decline happens.
Authentication and API Key Management
Cash-flow decisioning APIs typically use API key authentication, often combined with a request signing mechanism for payload integrity verification. The correct pattern for production environments:
POST /v1/decisions HTTP/1.1
Host: api.lendirow.com
Authorization: Bearer {API_KEY}
Content-Type: application/json
X-Request-Id: {unique_idempotency_key}
X-Timestamp: {unix_epoch_seconds}A few implementation notes that frequently get missed:
- The API key must not live in application code. It belongs in an environment variable or a secrets management service (AWS Secrets Manager, HashiCorp Vault, etc.). A production outage caused by an accidentally rotated API key that was hardcoded in a repository is a real and avoidable incident.
- Include an idempotency key on every request. Network timeouts and retry logic can result in duplicate API calls for the same application. An idempotency key (a stable UUID derived from the application ID and request type) allows the API to return the cached result of a duplicate request rather than creating a second decision record.
- Plan for API key rotation. Your integration should support rotation without downtime. The standard pattern is to have the application read the key from the secrets store at request time (not at startup), allowing a key rotation to take effect within seconds on the next request.
Payload Structure: What the API Needs
A cash-flow decisioning API expects three categories of input: applicant identity, application context, and transaction data. The transaction data payload is the most variable part.
{
"application_id": "APP-2025-094821",
"applicant": {
"external_id": "MBR-00048821",
"date_of_birth": "1989-04-12",
"address_state": "TX"
},
"loan_context": {
"product_type": "personal_installment",
"requested_amount_cents": 350000,
"requested_term_months": 36
},
"transaction_data": {
"source": "open_banking",
"account_type": "checking",
"lookback_months": 24,
"transactions": [
{
"date": "2025-01-03",
"amount_cents": 142500,
"direction": "credit",
"description": "DIRECT DEPOSIT - EMPLOYER PAYROLL",
"category_hint": "payroll"
}
]
}
}The category_hint field is worth noting. Most cash-flow APIs will perform their own transaction categorization, but providing a category hint when the LOS can reliably identify the transaction type (payroll, rent, utility) improves classification accuracy at the margin and reduces latency. Do not override the API's categorization with hints from unreliable sources — bad hints degrade model quality.
Response Parsing: Decision Fields That Matter
The API response will include a decision output, a score or tier, and reason codes. The fields your LOS integration needs to capture and store:
{
"decision_id": "DEC-7f4e2a19-cd83",
"application_id": "APP-2025-094821",
"decision": "approve",
"decision_tier": "standard",
"cash_flow_score": 682,
"confidence_band": "high",
"reason_codes": [
{
"code": "CF_INS_01",
"description": "Consistent recurring income deposits over 24-month period",
"direction": "positive"
},
{
"code": "CF_NSF_03",
"description": "No non-sufficient funds events in the past 12 months",
"direction": "positive"
}
],
"adverse_action_flags": [],
"model_version": "v2.4.1",
"processed_at": "2025-07-29T14:22:17Z"
}Critical fields to store permanently: decision_id, model_version, processed_at, all reason_codes, and adverse_action_flags. These are your regulatory record. The model_version field matters because adverse action notices must reference the model that governed the decision — if the vendor retrains the model, you need to know which version was used for each historical decision.
Adverse Action Flag Handling
When the API returns a decline recommendation, the adverse_action_flags array will contain the reason codes that must appear on the adverse action notice. Your LOS integration needs to route these codes to the adverse action notice generation workflow automatically — not as a manual step.
The mapping from API reason codes to Regulation B plain-language statements should be a configuration table maintained by your compliance team, not hardcoded in the integration layer. Reason codes can be added or updated when the model is retrained; a configuration table allows compliance team updates without engineering involvement.
One scenario that requires special handling: a partial decline where the cash-flow API recommends decline but the FICO-based system would have approved. Your decisioning policy should specify how this conflict is resolved, and the adverse action notice must reflect the actual basis of the denial — whichever system governed the decision. If cash-flow override is the tiebreaker, the adverse action reason codes come from the cash-flow API. If FICO governs and cash-flow is supplementary, the adverse action reason codes come from the FICO system.
Error Handling and Fallback Logic
The API will occasionally return errors: rate limit hits, temporary unavailability, malformed payload rejections. Your integration needs explicit fallback logic for each case.
The standard fallback pattern for a cash-flow decisioning call that fails with a 5xx error is to queue the application for manual review rather than automatically declining it. An automatic decline triggered by an API timeout — not by an actual negative credit decision — is a compliance exposure: the adverse action notice would need to explain a denial that was based on a system error, not on the applicant's creditworthiness. Manual review queuing, with a clear SLA for resolution, is the safer fallback.
For 4xx errors related to payload validation (missing fields, out-of-range values, insufficient transaction history), the recommended approach is to surface the specific error to the loan officer rather than attempting a silent retry. "Insufficient transaction history" is a meaningful signal that the application may not be suitable for cash-flow decisioning on that data source — it is not a transient error to be automatically retried.
Testing Before Production
A complete pre-production testing checklist for cash-flow API integrations should include: synthetic application payloads covering approve, decline, and review outcomes; adverse action flag routing through to notice generation for each decline reason code in the library; error handling validation (simulate 503, 429, and 422 responses); idempotency key collision testing (submit the same application twice, verify only one decision is created); and audit log completeness verification (confirm every field required for regulatory examination is persisted in your record system). The integration is not ready for production until every item on that checklist has been tested in a staging environment with realistic transaction payloads.